# Le opzioni di NEWACTION e l'oggetto una azione riceve

> Configurare NEWACTION e utilizzare il contesto di azione per gestire le richieste.

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

`NEWACTION(name, options)` dichiara un'azione. `name` è il suo id (`Users/insert`): le route lo usano con `--> *Users/insert` e il tuo codice con `ACTION('Users/insert', payload)`.

## Opzioni

| Opzione | Valore | Cosa fa |
|---|---|---|
| `name` | testo | Una descrizione dell'azione; è disponibile anche come `$.name`. |
| `action` | `function($, model)` | Il codice dell'azione. `model` è l'input validato. |
| `input` | testo | I campi del corpo, come `name:Type` separati da virgole; un `*` prima del nome lo rende obbligatorio. Vedi la pagina sui tipi di input. |
| `output` | testo | I campi della risposta; i campi non elencati vengono rimossi. |
| `params` | testo | I segmenti `{name}` della route, validati come `input`. |
| `query` | testo | La query string, validata come `input`. |
| `partial` | `true` | Solo i campi inviati raggiungono l'azione. Usalo per `PATCH`. |
| `user` | `true` o `false` | `true` risponde 401 quando non c'è un utente autenticato; `false` accetta solo richieste anonime. |
| `permissions` | testo o array | `'read,write'`: l'utente ne deve avere uno (o essere super amministratore). |
| `route` | testo | Dichiara qui la route dell'azione: `'GET /products/'`, oppure `true` per una route `API`. |
| `middleware` | testo | Nomi dei middleware eseguiti prima dell'azione, separati da spazi o virgole. |
| `timeout` | millisecondi | Quando l'azione non risponde in tempo, la richiesta fallisce con l'errore `Timeout.`. |
| `cache` | `true` o un oggetto | Conserva il risultato di un’azione con `CACHE`. |
| `config` | oggetto | Valori che l'azione legge da `$.config`. |
| `audit` | text | Registra un evento dopo il completamento riuscito; la ricetta dedicata ne verifica i limiti. [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/) |

## L'oggetto `$` di un'azione

| Membro | Cos'è |
|---|---|
| `$.query`, `$.params` | La query string e i segmenti della route, validati. |
| `$.payload` | L'input validato; è lo stesso oggetto del secondo argomento di `action`. |
| `$.user` | L'utente autenticato. |
| `$.config` | L'opzione `config`. |
| `$.name`, `$.id` | L'opzione `name` e l'id dell'azione. |
| `$.controller` | Il `$` della route quando l'azione è stata chiamata da una route, quindi `$.controller.body` è il corpo grezzo. Non esiste quando l'azione viene chiamata con `ACTION()`. |
| `$.callback(value)` | Risponde con un valore; viene filtrato da `output`. Senza argomenti restituisce una funzione `(err, response)`. |
| `$.success(value)` | Risponde `{ success: true }`. |
| `$.invalid(error)` | Risponde con un errore: un testo, un codice di stato o un `ErrorBuilder`. |
| `$.done(arg)`, `$.successful(fn)` | Restituiscono callback per funzioni che segnalano un errore come primo argomento. |
| `$.cookie(name, value, expiration)` | Legge o scrive un cookie della richiesta. |
| `$.redirect(url)` | Reindirizza la richiesta. |
| `$.output(name)` | Sceglie come risponde una route: `json`, `html`, `xml`, `text`, `redirect`, `binary`, `jsonstring`, `empty` o `file`. |
| `$.unauthorized(...permissions)` | Risponde 401 e restituisce `true` quando l'utente non ha nessuno dei permessi. |
| `$.action(name, payload)` | Esegue un'altra azione con la stessa richiesta. |
| `$.hostname(path)` | L'indirizzo di questo server. |

```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');
};
```