# Referencia del controlador de Total.js 5
> Consulta las propiedades y métodos del controlador para leer peticiones, responder, gestionar archivos y renderizar vistas.
Framework: total5
Product: Total.js 5 (total5@0.0.19)
Language: es
Content-SHA256: bac6e32479ab53c970cc3bd1e35d4c914da98c54eeefcbfd461afd1fe4435dae
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: total5-installed@total5@0.0.19
Review: not-recorded
Un manejador de ruta recibe un objeto, escrito `$` en este sitio. Describe la petición y la responde. Responde **una sola vez**: después de `$.json()`, `$.html()` o cualquier otra respuesta, la petición ha terminado.
## Propiedades
| Propiedad | Tipo | Qué es |
|---|---|---|
| `$.url` | string | La ruta de la petición, sin la cadena de consulta. |
| `$.method` | string | `GET`, `POST`... |
| `$.query` | object | La cadena de consulta, analizada. |
| `$.params` | object | Los segmentos `{name}` de la ruta. |
| `$.body` | object | El cuerpo, analizado según su tipo de contenido (JSON, formulario URL-encoded, XML o campos multipart). |
| `$.files` | array | Los archivos subidos de una petición multipart. |
| `$.headers` | object | Las cabeceras de la petición, con nombres en minúsculas. |
| `$.ip` | string | La dirección IP; la primera dirección de `x-forwarded-for` cuando existe la cabecera. |
| `$.host` | string | La cabecera `host`. |
| `$.referrer` | string | La cabecera `referer`. |
| `$.protocol` | string | `http` o `https` (también cuando un proxy lo indica en `x-forwarded-proto`). |
| `$.ext` | string | La extensión de la URL, sin el punto (`$.extension` es lo mismo). |
| `$.xhr` | boolean | `true` cuando la cabecera `x-requested-with` es `XMLHttpRequest`. |
| `$.mobile` | boolean | `true` cuando el user agent parece un navegador móvil. |
| `$.robot` | boolean | `true` cuando el user agent parece un rastreador. |
| `$.ua` | string | Un nombre corto del navegador y el sistema, como `iPhone Safari` o `Windows Chrome`. |
| `$.user` | object | El usuario que `AUTH()` aprobó, o nada. |
| `$.language` | string | El idioma que eligió `LOCALIZE()`. |
| `$.datatype` | string | `json`, `urlencoded`, `multipart`, `xml`, `text` o `binary`: el tipo del cuerpo de la petición. |
| `$.response` | object | Lo que se enviará: `status`, `headers` y `value`. Cambia `$.response.status` y `$.response.headers` antes de responder. |
| `$.req`, `$.res` | objects | La petición y la respuesta de Node.js. |
## Métodos que responden
| Método | Qué hace | Receta |
|---|---|---|
| `$.json(value)` | Responde con JSON. | [responses](/en/total5/responses/) |
| `$.jsonstring(text)` | Responde con un texto que ya es JSON, sin volver a serializarlo. | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |
| `$.html(text)` | Responde con HTML. | [responses](/en/total5/responses/) |
| `$.plain(text)` | Responde con texto plano (`$.text` es lo mismo). | [responses](/en/total5/responses/) |
| `$.xml(text)` | Responde con XML. | [responses](/en/total5/responses/) |
| `$.empty()` | Responde con estado 204 y sin cuerpo. | [responses](/en/total5/responses/) |
| `$.redirect(url, permanent)` | Redirige (302, o 301 cuando `permanent` es true). | [responses](/en/total5/responses/) |
| `$.binary(buffer, type, name)` | Responde con bytes y un tipo de contenido. | [responses](/en/total5/responses/) |
| `$.file(path, name)` | Envía un archivo del disco. | [file-download](/en/total5/file-download/) |
| `$.stream(type, stream, name)` | Envía un stream legible. | [file-download](/en/total5/file-download/) |
| `$.filefs(storage, id)` | Envía un archivo de un `FILESTORAGE`. | [filestorage](/en/total5/filestorage/) |
| `$.image(options)` | Crea y envía una imagen bajo demanda. | [images](/en/total5/images/) |
| `$.view(name, model)` | Renderiza una vista con el layout y responde con ella. | [views-and-layouts](/en/total5/views-and-layouts/) |
| `$.layout(name)` | Elige otro layout para el siguiente `$.view()`. | [view-sections](/en/total5/view-sections/) |
| `$.proxy(url)` | Reenvía la petición a otra URL y responde con su respuesta. | [proxy](/en/total5/proxy/) |
| `$.respond(value)` | Responde en el formato de `$.response.output` (`json` cuando no está definido). | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |
| `$.invalid(value)` | Responde con un error: un texto, un código de estado como `404` o un `ErrorBuilder`. | [actions-crud](/en/total5/actions-crud/) |
| `$.fallback(code)` | Responde con la página de un código de error, la personalizada cuando existe `ROUTE('#404')`. | [error-pages](/en/total5/error-pages/) |
| `$.success(value)` | Responde `{ "success": true }`; `value` se le añade. | [responses](/en/total5/responses/) |
| `$.callback(err, value)` | Con un error responde `$.invalid(err)`, si no `$.json(value)`, o `$.success()` cuando `value` es `undefined`. Sin argumentos devuelve una función `(err, response)` que hace lo mismo. | [actions-crud](/en/total5/actions-crud/) |
| `$.successful(fn)` | Devuelve una función `(err, a, b, c)`: con un error responde `$.invalid(err)`, si no llama a `fn(a, b, c)`. | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |
| `$.done(arg)` | Devuelve una función `(err, response)`: con un error responde `$.invalid(err)`, si no responde con el objeto de éxito. | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |
## Otros métodos
| Método | Qué hace | Receta |
|---|---|---|
| `$.cookie(name, value, expiration)` | Lee una cookie, o escribe una cuando pasas un valor. | [headers-and-cookies](/en/total5/headers-and-cookies/) |
| `$.csrf()` | Crea un token CSRF para este cliente. | [csrf-protection](/en/total5/csrf-protection/) |
| `$.hostname(path)` | La dirección de este servidor: protocolo, host y la ruta que pasas. | [restbuilder](/en/total5/restbuilder/) |
| `$.action(name, model)` | Ejecuta una acción con esta petición (usuario, query y params). | [calling-actions-from-code](/en/total5/calling-actions-from-code/) |
| `$.transform(name, value, callback)` | Ejecuta una transformación con esta petición. | [transforms](/en/total5/transforms/) |
| `$.authorize(callback)` | Ejecuta `AUTH()` para esta petición y establece `$.user`; devuelve una promesa cuando no hay callback. | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |
| `$.notmodified(date)` | Responde 304 y devuelve `true` cuando la petición tiene la cabecera `if-modified-since` con esa fecha. | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |
| `$.httpcache(date)` | Establece las cabeceras de caché y `last-modified` de la respuesta. | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |
| `$.clear()` | Elimina los archivos temporales de la subida. Se eliminan de todos modos cuando termina la petición. | [file-upload](/en/total5/file-upload/) |
| `$.autoclear(false)` | Conserva los archivos subidos después de la petición, para que puedas usarlos más tarde. | [upload-lifecycle-and-href](/en/total5/upload-lifecycle-and-href/) |
| `$.custom()` | Indica al framework que respondes tú mismo a través de `$.res`: no enviará nada. | [controller-completion-and-cache](/en/total5/controller-completion-and-cache/) |
| `$.href(key, value)` | Usa `QUERIFY()` como en la receta enlazada, el helper nativo probado para enlaces con consulta. | [upload-lifecycle-and-href](/en/total5/upload-lifecycle-and-href/) |
| `$.flush()`, `$.resume()`, `$.free()`, `$.cancel()` | Métodos internos: no los llames. | - |
El ejemplo responde con las propiedades y llama a los métodos que no necesitan preparación.
```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('x');
case 'plain': return $.plain('x');
case 'xml': return $.xml('1');
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');
}
}
```