# Opções de NOVAÇÃO e o objeto uma ação recebe

> Configure NEWACTION e use o contexto de ação para lidar com pedidos.

Framework: total5
Product: Total.js 5 (total5@0.0.19)
Language: pt
Content-SHA256: df8fe0ced12554678391108d0ee88556f9b620cc3b7dd58826420f457ae6c557
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: total5-installed@total5@0.0.19
Review: not-recorded

`NEWACTION(name, options)` declara uma ação. `name` é o seu id (`Users/insert`): as rotas usam-no com `--> *Users/insert` e o seu código com `ACTION('Users/insert', payload)`.

## Opções

| Opção | Valor | O que faz |
|---|---|---|
| `name` | texto | Uma descrição da ação; também está disponível como `$.name`. |
| `action` | `function($, model)` | O código da ação. `model` é a entrada validada. |
| `input` | texto | Os campos do corpo, como `name:Type` separados por vírgulas; um `*` antes do nome torna-o obrigatório. Veja a página dos tipos de entrada. |
| `output` | texto | Os campos da resposta; os campos que não estão listados são removidos. |
| `params` | texto | Os segmentos `{name}` da rota, validados como `input`. |
| `query` | texto | A query string, validada como `input`. |
| `partial` | `true` | Só os campos que foram enviados chegam à ação. Use-o para `PATCH`. |
| `user` | `true` ou `false` | `true` responde 401 quando não há utilizador autenticado; `false` aceita apenas pedidos anónimos. |
| `permissions` | texto ou array | `'read,write'`: o utilizador precisa de um deles (ou de ser super administrador). |
| `route` | texto | Declara aqui a rota da ação: `'GET /products/'`, ou `true` para uma rota `API`. |
| `middleware` | texto | Nomes de middleware que correm antes da ação, separados por espaços ou vírgulas. |
| `timeout` | milissegundos | Quando a ação não responde a tempo, o pedido falha com o erro `Timeout.`. |
| `cache` | `true` ou um objeto | Guarde o resultado de uma ação com `CACHE`. |
| `config` | objeto | Valores que a ação lê de `$.config`. |
| `audit` | text | Regista um evento após a conclusão bem-sucedida; a receita específica verifica os limites. [action-audit](/en/total5/action-audit/) |
| `csrf`, `encrypt`, `compress`, `publish` | - | [action-transport-boundaries](/en/total5/action-transport-boundaries/) |
| `sa`, `su` | true | [action-hooks-and-admin](/en/total5/action-hooks-and-admin/) |
| `oninput`, `onoutput` | function | [action-hooks-and-admin](/en/total5/action-hooks-and-admin/) |
| `extend` | path | [action-hooks-and-admin](/en/total5/action-hooks-and-admin/) |

## O objeto `$` de uma ação

| Membro | O que é |
|---|---|
| `$.query`, `$.params` | A query string e os segmentos da rota, validados. |
| `$.payload` | A entrada validada; é o mesmo objeto que o segundo argumento de `action`. |
| `$.user` | O utilizador autenticado. |
| `$.config` | A opção `config`. |
| `$.name`, `$.id` | A opção `name` e o id da ação. |
| `$.controller` | O `$` da rota quando a ação foi chamada a partir de uma rota, pelo que `$.controller.body` é o corpo em bruto. Não existe quando a ação é chamada com `ACTION()`. |
| `$.callback(value)` | Responde com um valor; é filtrado por `output`. Sem argumentos devolve uma função `(err, response)`. |
| `$.success(value)` | Responde `{ success: true }`. |
| `$.invalid(error)` | Responde com um erro: um texto, um código de estado ou um `ErrorBuilder`. |
| `$.done(arg)`, `$.successful(fn)` | Devolvem callbacks para funções que comunicam um erro como primeiro argumento. |
| `$.cookie(name, value, expiration)` | Lê ou escreve um cookie do pedido. |
| `$.redirect(url)` | Redireciona o pedido. |
| `$.output(name)` | Escolhe como responde uma rota: `json`, `html`, `xml`, `text`, `redirect`, `binary`, `jsonstring`, `empty` ou `file`. |
| `$.unauthorized(...permissions)` | Responde 401 e devolve `true` quando o utilizador não tem nenhuma das permissões. |
| `$.action(name, payload)` | Executa outra ação com o mesmo pedido. |
| `$.hostname(path)` | O endereço deste servidor. |

```js definitions/options.js
MIDDLEWARE('tag', function($, next) {
	$.response.headers['x-tag'] = 'on';
	next();
});

var counter = { cached: 0 };
MAIN.counter = counter;

NEWACTION('Options/named', {
	name: 'The name',
	config: { limit: 3 },
	action: function($) {
		$.callback({ name: $.name, id: $.id, limit: $.config.limit });
	}
});

NEWACTION('Options/guarded', {
	name: 'Needs a user',
	user: true,
	permissions: 'read',
	action: function($) {
		$.success();
	}
});

NEWACTION('Options/slow', {
	name: 'Never answers',
	timeout: 300,
	action: function($) {}
});

NEWACTION('Options/cached', {
	name: 'The cache option',
	query: 'page:Number',
	cache: { expire: '1 minute', query: 'page' },
	action: function($) {
		counter.cached++;
		$.callback({ page: $.query.page, runs: counter.cached });
	}
});

NEWACTION('Options/routed', {
	name: 'Declares its own route',
	route: 'GET /routed/ #tag',
	action: function($) {
		$.callback({ routed: true });
	}
});

NEWACTION('Options/output', {
	name: 'Chooses how to answer',
	action: function($) {
		$.output('plain');
		$.callback('plain text');
	}
});

AUTH(function($) {
	if ($.headers['x-user'])
		$.success({ id: '1', permissions: $.headers['x-user'].split(',') });
	else
		$.invalid();
});
```

```js controllers/options.js
exports.install = function() {
	ROUTE('GET /named/ --> *Options/named');
	ROUTE('GET /guarded/ --> *Options/guarded');
	ROUTE('GET /slow/ --> *Options/slow');
	ROUTE('GET /cached/ --> *Options/cached');
	ROUTE('GET /output/ --> *Options/output');
};
```