# L'oggetto di un Total.js 5

> Utilizzare le proprietà e i metodi del controller ricevuti da un operatore di rotazione.

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

Un handler di route riceve un oggetto, scritto `$` in questo sito. Descrive la richiesta e vi risponde. Rispondi **una sola volta**: dopo `$.json()`, `$.html()` o qualsiasi altra risposta, la richiesta è terminata.

## Proprietà

| Proprietà | Tipo | Cos'è |
|---|---|---|
| `$.url` | string | Il percorso della richiesta, senza la query string. |
| `$.method` | string | `GET`, `POST`... |
| `$.query` | object | La query string, analizzata. |
| `$.params` | object | I segmenti `{name}` della route. |
| `$.body` | object | Il corpo, analizzato in base al tipo di contenuto (JSON, form URL-encoded, XML o campi multipart). |
| `$.files` | array | I file caricati di una richiesta multipart. |
| `$.headers` | object | Gli header della richiesta, con nomi in minuscolo. |
| `$.ip` | string | L'indirizzo IP; il primo indirizzo di `x-forwarded-for` quando l'header esiste. |
| `$.host` | string | L'header `host`. |
| `$.referrer` | string | L'header `referer`. |
| `$.protocol` | string | `http` o `https` (anche quando un proxy lo indica in `x-forwarded-proto`). |
| `$.ext` | string | L'estensione dell'URL, senza il punto (`$.extension` è lo stesso). |
| `$.xhr` | boolean | `true` quando l'header `x-requested-with` è `XMLHttpRequest`. |
| `$.mobile` | boolean | `true` quando lo user agent sembra un browser mobile. |
| `$.robot` | boolean | `true` quando lo user agent sembra un crawler. |
| `$.ua` | string | Un nome breve del browser e del sistema, come `iPhone Safari` o `Windows Chrome`. |
| `$.user` | object | L'utente approvato da `AUTH()`, oppure nulla. |
| `$.language` | string | La lingua scelta da `LOCALIZE()`. |
| `$.datatype` | string | `json`, `urlencoded`, `multipart`, `xml`, `text` o `binary`: il tipo del corpo della richiesta. |
| `$.response` | object | Ciò che verrà inviato: `status`, `headers` e `value`. Cambia `$.response.status` e `$.response.headers` prima di rispondere. |
| `$.req`, `$.res` | objects | La richiesta e la risposta di Node.js. |

## Metodi che rispondono

| Metodo | Cosa fa | Ricetta |
|---|---|---|
| `$.json(value)` | Risponde con JSON. | [responses](/en/total5/responses/) |
| `$.jsonstring(text)` | Risponde con un testo che è già JSON, senza serializzarlo di nuovo. | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |
| `$.html(text)` | Risponde con HTML. | [responses](/en/total5/responses/) |
| `$.plain(text)` | Risponde con testo semplice (`$.text` è lo stesso). | [responses](/en/total5/responses/) |
| `$.xml(text)` | Risponde con XML. | [responses](/en/total5/responses/) |
| `$.empty()` | Risponde con stato 204 e senza corpo. | [responses](/en/total5/responses/) |
| `$.redirect(url, permanent)` | Reindirizza (302, o 301 quando `permanent` è true). | [responses](/en/total5/responses/) |
| `$.binary(buffer, type, name)` | Risponde con byte e un tipo di contenuto. | [responses](/en/total5/responses/) |
| `$.file(path, name)` | Invia un file dal disco. | [file-download](/en/total5/file-download/) |
| `$.stream(type, stream, name)` | Invia uno stream leggibile. | [file-download](/en/total5/file-download/) |
| `$.filefs(storage, id)` | Invia un file di un `FILESTORAGE`. | [filestorage](/en/total5/filestorage/) |
| `$.image(options)` | Crea e invia un'immagine su richiesta. | [images](/en/total5/images/) |
| `$.view(name, model)` | Renderizza una vista con il layout e risponde con essa. | [views-and-layouts](/en/total5/views-and-layouts/) |
| `$.layout(name)` | Sceglie un altro layout per il prossimo `$.view()`. | [view-sections](/en/total5/view-sections/) |
| `$.proxy(url)` | Inoltra la richiesta a un altro URL e risponde con la sua risposta. | [proxy](/en/total5/proxy/) |
| `$.respond(value)` | Risponde nel formato di `$.response.output` (`json` quando non è impostato). | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |
| `$.invalid(value)` | Risponde con un errore: un testo, un codice di stato come `404` o un `ErrorBuilder`. | [actions-crud](/en/total5/actions-crud/) |
| `$.fallback(code)` | Risponde con la pagina di un codice di errore, quella personalizzata quando esiste `ROUTE('#404')`. | [error-pages](/en/total5/error-pages/) |
| `$.success(value)` | Risponde `{ "success": true }`; `value` viene aggiunto. | [responses](/en/total5/responses/) |
| `$.callback(err, value)` | Con un errore risponde `$.invalid(err)`, altrimenti `$.json(value)`, oppure `$.success()` quando `value` è `undefined`. Senza argomenti restituisce una funzione `(err, response)` che fa lo stesso. | [actions-crud](/en/total5/actions-crud/) |
| `$.successful(fn)` | Restituisce una funzione `(err, a, b, c)`: con un errore risponde `$.invalid(err)`, altrimenti chiama `fn(a, b, c)`. | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |
| `$.done(arg)` | Restituisce una funzione `(err, response)`: con un errore risponde `$.invalid(err)`, altrimenti risponde con l'oggetto di successo. | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |

## Altri metodi

| Metodo | Cosa fa | Ricetta |
|---|---|---|
| `$.cookie(name, value, expiration)` | Legge un cookie, o ne scrive uno quando passi un valore. | [headers-and-cookies](/en/total5/headers-and-cookies/) |
| `$.csrf()` | Crea un token CSRF per questo client. | [csrf-protection](/en/total5/csrf-protection/) |
| `$.hostname(path)` | L'indirizzo di questo server: protocollo, host e il percorso che passi. | [restbuilder](/en/total5/restbuilder/) |
| `$.action(name, model)` | Esegue un'azione con questa richiesta (utente, query e params). | [calling-actions-from-code](/en/total5/calling-actions-from-code/) |
| `$.transform(name, value, callback)` | Esegue una trasformazione con questa richiesta. | [transforms](/en/total5/transforms/) |
| `$.authorize(callback)` | Esegue `AUTH()` per questa richiesta e imposta `$.user`; restituisce una promise quando non c'è callback. | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |
| `$.notmodified(date)` | Risponde 304 e restituisce `true` quando la richiesta ha l'header `if-modified-since` con quella data. | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |
| `$.httpcache(date)` | Imposta gli header di cache e `last-modified` della risposta. | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |
| `$.clear()` | Rimuove i file temporanei dell'upload. Vengono comunque rimossi quando la richiesta termina. | [file-upload](/en/total5/file-upload/) |
| `$.autoclear(false)` | Mantiene i file caricati dopo la richiesta, così puoi usarli in seguito. | [upload-lifecycle-and-href](/en/total5/upload-lifecycle-and-href/) |
| `$.custom()` | Dice al framework che rispondi tu stesso tramite `$.res`: non invierà nulla. | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |
| `$.href(key, value)` | Usa `QUERIFY()` come nella ricetta collegata, l’helper nativo testato per i link con query. | [upload-lifecycle-and-href](/en/total5/upload-lifecycle-and-href/) |
| `$.flush()`, `$.resume()`, `$.free()`, `$.cancel()` | Metodi interni: non chiamarli. | - |

L'esempio risponde con le proprietà e chiama i metodi che non richiedono preparazione.

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