# L'objet de la Total.js 5

> Utilisez les propriétés et les méthodes du contrôleur reçus par un opérateur de route.

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

Un gestionnaire de route reçoit un objet, écrit `$` sur ce site. Il décrit la requête et y répond. Répondez **une seule fois** : après `$.json()`, `$.html()` ou toute autre réponse, la requête est terminée.

## Propriétés

| Propriété | Type | Ce que c'est |
|---|---|---|
| `$.url` | string | Le chemin de la requête, sans la chaîne de requête. |
| `$.method` | string | `GET`, `POST`... |
| `$.query` | object | La chaîne de requête, analysée. |
| `$.params` | object | Les segments `{name}` de la route. |
| `$.body` | object | Le corps, analysé selon son type de contenu (JSON, formulaire URL-encodé, XML ou champs multipart). |
| `$.files` | array | Les fichiers téléversés d'une requête multipart. |
| `$.headers` | object | Les en-têtes de la requête, avec des noms en minuscules. |
| `$.ip` | string | L'adresse IP ; la première adresse de `x-forwarded-for` quand l'en-tête existe. |
| `$.host` | string | L'en-tête `host`. |
| `$.referrer` | string | L'en-tête `referer`. |
| `$.protocol` | string | `http` ou `https` (aussi quand un proxy l'indique dans `x-forwarded-proto`). |
| `$.ext` | string | L'extension de l'URL, sans le point (`$.extension` est identique). |
| `$.xhr` | boolean | `true` quand l'en-tête `x-requested-with` vaut `XMLHttpRequest`. |
| `$.mobile` | boolean | `true` quand l'user agent ressemble à un navigateur mobile. |
| `$.robot` | boolean | `true` quand l'user agent ressemble à un robot d'exploration. |
| `$.ua` | string | Un nom court du navigateur et du système, comme `iPhone Safari` ou `Windows Chrome`. |
| `$.user` | object | L'utilisateur qu'`AUTH()` a approuvé, ou rien. |
| `$.language` | string | La langue que `LOCALIZE()` a choisie. |
| `$.datatype` | string | `json`, `urlencoded`, `multipart`, `xml`, `text` ou `binary` : le type du corps de la requête. |
| `$.response` | object | Ce qui sera envoyé : `status`, `headers` et `value`. Modifiez `$.response.status` et `$.response.headers` avant de répondre. |
| `$.req`, `$.res` | objects | La requête et la réponse Node.js. |

## Méthodes qui répondent

| Méthode | Ce qu'elle fait | Recette |
|---|---|---|
| `$.json(value)` | Répond avec du JSON. | [responses](/en/total5/responses/) |
| `$.jsonstring(text)` | Répond avec un texte qui est déjà du JSON, sans le sérialiser à nouveau. | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |
| `$.html(text)` | Répond avec du HTML. | [responses](/en/total5/responses/) |
| `$.plain(text)` | Répond avec du texte brut (`$.text` est identique). | [responses](/en/total5/responses/) |
| `$.xml(text)` | Répond avec du XML. | [responses](/en/total5/responses/) |
| `$.empty()` | Répond avec le statut 204 et sans corps. | [responses](/en/total5/responses/) |
| `$.redirect(url, permanent)` | Redirige (302, ou 301 quand `permanent` est vrai). | [responses](/en/total5/responses/) |
| `$.binary(buffer, type, name)` | Répond avec des octets et un type de contenu. | [responses](/en/total5/responses/) |
| `$.file(path, name)` | Envoie un fichier du disque. | [file-download](/en/total5/file-download/) |
| `$.stream(type, stream, name)` | Envoie un flux lisible. | [file-download](/en/total5/file-download/) |
| `$.filefs(storage, id)` | Envoie un fichier d'un `FILESTORAGE`. | [filestorage](/en/total5/filestorage/) |
| `$.image(options)` | Crée et envoie une image à la demande. | [images](/en/total5/images/) |
| `$.view(name, model)` | Rend une vue avec le layout et répond avec elle. | [views-and-layouts](/en/total5/views-and-layouts/) |
| `$.layout(name)` | Choisit un autre layout pour le prochain `$.view()`. | [view-sections](/en/total5/view-sections/) |
| `$.proxy(url)` | Transmet la requête à une autre URL et répond avec sa réponse. | [proxy](/en/total5/proxy/) |
| `$.respond(value)` | Répond au format de `$.response.output` (`json` s'il n'est pas défini). | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |
| `$.invalid(value)` | Répond avec une erreur : un texte, un code d'état comme `404` ou un `ErrorBuilder`. | [actions-crud](/en/total5/actions-crud/) |
| `$.fallback(code)` | Répond avec la page d'un code d'erreur, celle personnalisée quand `ROUTE('#404')` existe. | [error-pages](/en/total5/error-pages/) |
| `$.success(value)` | Répond `{ "success": true }` ; `value` y est ajouté. | [responses](/en/total5/responses/) |
| `$.callback(err, value)` | Avec une erreur, répond `$.invalid(err)`, sinon `$.json(value)`, ou `$.success()` quand `value` est `undefined`. Sans argument, renvoie une fonction `(err, response)` qui fait la même chose. | [actions-crud](/en/total5/actions-crud/) |
| `$.successful(fn)` | Renvoie une fonction `(err, a, b, c)` : avec une erreur, elle répond `$.invalid(err)`, sinon elle appelle `fn(a, b, c)`. | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |
| `$.done(arg)` | Renvoie une fonction `(err, response)` : avec une erreur, elle répond `$.invalid(err)`, sinon avec l'objet de succès. | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |

## Autres méthodes

| Méthode | Ce qu'elle fait | Recette |
|---|---|---|
| `$.cookie(name, value, expiration)` | Lit un cookie, ou en écrit un quand vous passez une valeur. | [headers-and-cookies](/en/total5/headers-and-cookies/) |
| `$.csrf()` | Crée un jeton CSRF pour ce client. | [csrf-protection](/en/total5/csrf-protection/) |
| `$.hostname(path)` | L'adresse de ce serveur : protocole, hôte et le chemin que vous passez. | [restbuilder](/en/total5/restbuilder/) |
| `$.action(name, model)` | Exécute une action avec cette requête (utilisateur, query et params). | [calling-actions-from-code](/en/total5/calling-actions-from-code/) |
| `$.transform(name, value, callback)` | Exécute une transformation avec cette requête. | [transforms](/en/total5/transforms/) |
| `$.authorize(callback)` | Exécute `AUTH()` pour cette requête et définit `$.user` ; renvoie une promesse quand il n'y a pas de callback. | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |
| `$.notmodified(date)` | Répond 304 et renvoie `true` quand la requête a l'en-tête `if-modified-since` avec cette date. | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |
| `$.httpcache(date)` | Définit les en-têtes de cache et `last-modified` de la réponse. | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |
| `$.clear()` | Supprime les fichiers temporaires du téléversement. Ils sont supprimés de toute façon à la fin de la requête. | [file-upload](/en/total5/file-upload/) |
| `$.autoclear(false)` | Conserve les fichiers téléversés après la requête, pour les utiliser plus tard. | [upload-lifecycle-and-href](/en/total5/upload-lifecycle-and-href/) |
| `$.custom()` | Indique au framework que vous répondez vous-même via `$.res` : il n'enverra rien. | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |
| `$.href(key, value)` | Utilisez `QUERIFY()` comme dans la recette liée, l’assistant natif testé pour les liens avec paramètres. | [upload-lifecycle-and-href](/en/total5/upload-lifecycle-and-href/) |
| `$.flush()`, `$.resume()`, `$.free()`, `$.cancel()` | Méthodes internes : ne les appelez pas. | - |

L'exemple répond avec les propriétés et appelle les méthodes qui ne nécessitent aucune préparation.

```js controllers/api.js
exports.install = function() {
	ROUTE('GET /info/{a}/{b}/', info);
	ROUTE('POST /body/ @json', body);
	ROUTE('GET /answers/{kind}/', answers);
	ROUTE('GET /callback/{kind}/', callback);
};

function info($) {
	$.json({
		url: $.url,
		method: $.method,
		query: $.query,
		params: $.params,
		ext: $.ext,
		xhr: $.xhr,
		mobile: $.mobile,
		robot: $.robot,
		ua: $.ua,
		ip: $.ip,
		host: $.host,
		referrer: $.referrer,
		protocol: $.protocol,
		hostname: $.hostname('/x/'),
		datatype: $.datatype
	});
}

function body($) {
	$.json({ body: $.body, datatype: $.datatype });
}

function answers($) {
	switch ($.params.kind) {
		case 'json': return $.json({ a: 1 });
		case 'jsonstring': return $.jsonstring('{"a":1}');
		case 'html': return $.html('<b>x</b>');
		case 'plain': return $.plain('x');
		case 'xml': return $.xml('<a>1</a>');
		case 'empty': return $.empty();
		case 'redirect': return $.redirect('/x/', true);
		case 'binary': return $.binary(Buffer.from('abc'), 'application/octet-stream');
		case 'invalid': return $.invalid(409);
		case 'success': return $.success({ id: 7 });
		case 'status': $.response.status = 201; return $.json({ created: true });
		case 'header': $.response.headers['x-example'] = 'yes'; return $.json({});
	}
}

function callback($) {
	switch ($.params.kind) {
		case 'error': return $.callback('failed');
		case 'value': return $.callback(null, { v: 1 });
		case 'nothing': return $.callback(null);
		case 'function': return setImmediate($.callback(), null, { later: true });
		case 'successful': return setImmediate($.successful(function(a, b) { $.json({ a: a, b: b }); }), null, 'x', 'y');
	}
}
```