# Options de NEWACTION et l'objet d'une action reçoit

> Configurez NEWACTION et utilisez le contexte d’action pour gérer les demandes.

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

`NEWACTION(name, options)` déclare une action. `name` est son identifiant (`Users/insert`) : les routes l'utilisent avec `--> *Users/insert` et votre code avec `ACTION('Users/insert', payload)`.

## Options

| Option | Valeur | Ce qu'elle fait |
|---|---|---|
| `name` | texte | Une description de l'action ; elle est aussi disponible comme `$.name`. |
| `action` | `function($, model)` | Le code de l'action. `model` est l'entrée validée. |
| `input` | texte | Les champs du corps, sous la forme `name:Type` séparés par des virgules ; un `*` avant le nom le rend obligatoire. Voir la page sur les types d'entrée. |
| `output` | texte | Les champs de la réponse ; les champs non listés sont supprimés. |
| `params` | texte | Les segments `{name}` de la route, validés comme `input`. |
| `query` | texte | La chaîne de requête, validée comme `input`. |
| `partial` | `true` | Seuls les champs envoyés atteignent l'action. À utiliser pour `PATCH`. |
| `user` | `true` ou `false` | `true` répond 401 quand aucun utilisateur n'est connecté ; `false` n'accepte que les requêtes anonymes. |
| `permissions` | texte ou tableau | `'read,write'` : l'utilisateur doit en avoir un (ou être super administrateur). |
| `route` | texte | Déclare ici la route de l'action : `'GET /products/'`, ou `true` pour une route `API`. |
| `middleware` | texte | Noms des middleware exécutés avant l'action, séparés par des espaces ou des virgules. |
| `timeout` | millisecondes | Quand l'action ne répond pas à temps, la requête échoue avec l'erreur `Timeout.`. |
| `cache` | `true` ou un objet | Conservez le résultat d’une action avec `CACHE`. |
| `config` | objet | Valeurs que l'action lit depuis `$.config`. |
| `audit` | text | Enregistre un événement après une exécution réussie ; la recette dédiée vérifie les 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/) |

## L'objet `$` d'une action

| Membre | Ce que c'est |
|---|---|
| `$.query`, `$.params` | La chaîne de requête et les segments de la route, validés. |
| `$.payload` | L'entrée validée ; c'est le même objet que le second argument de `action`. |
| `$.user` | L'utilisateur connecté. |
| `$.config` | L'option `config`. |
| `$.name`, `$.id` | L'option `name` et l'identifiant de l'action. |
| `$.controller` | Le `$` de la route quand l'action a été appelée depuis une route, donc `$.controller.body` est le corps brut. Il n'existe pas quand l'action est appelée avec `ACTION()`. |
| `$.callback(value)` | Répond avec une valeur ; elle est filtrée par `output`. Sans argument, elle renvoie une fonction `(err, response)`. |
| `$.success(value)` | Répond `{ success: true }`. |
| `$.invalid(error)` | Répond avec une erreur : un texte, un code d'état ou un `ErrorBuilder`. |
| `$.done(arg)`, `$.successful(fn)` | Renvoient des callbacks pour des fonctions qui signalent une erreur en premier argument. |
| `$.cookie(name, value, expiration)` | Lit ou écrit un cookie de la requête. |
| `$.redirect(url)` | Redirige la requête. |
| `$.output(name)` | Choisit comment une route répond : `json`, `html`, `xml`, `text`, `redirect`, `binary`, `jsonstring`, `empty` ou `file`. |
| `$.unauthorized(...permissions)` | Répond 401 et renvoie `true` quand l'utilisateur n'a aucune des permissions. |
| `$.action(name, payload)` | Exécute une autre action avec la même requête. |
| `$.hostname(path)` | L'adresse de ce serveur. |

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