# El controlador `crudl/controller.dkl` atiende cada petición: analiza lo que llegó, carga el modelo y el controlador de la entidad, abre la conexión, elige y ejecuta la operación y llama a la vista. Su cuerpo se ejecuta al incluirse, por eso va al final del punto de entrada. ## Análisis de la petición ### Parámetros Vienen de `@http_context/request/get`: la cadena de consulta y los marcadores de `routes.map`. ### Carga útil Se obtiene en este orden: 1. Si `request/post` tiene campos (un formulario `application/x-www-form-urlencoded`), se usa. 2. Si no, se interpreta `request/POST_STRING` como JSON. 3. Si ninguna produce datos, la carga útil es nula. No se procesan cuerpos `multipart/form-data`: el marco no recibe archivos. ### Campos de control (---) Antes de entregar la carga útil al modelo, los campos cuyo nombre empieza con `---` se **mueven** de la carga útil a los parámetros. Así un formulario puede llevar información de control sin que llegue a la entidad: ```html ``` `---from_url` no se intenta guardar como columna, y queda disponible en `parameters`. Funciona igual con un cuerpo JSON (`{"codigo":"CLI-0010","---origen":"7"}` guarda el cliente sin el campo `---origen`). Vea [Patrón PRG](/es/devkron/2.0/marcos/crudl/prg-y-redireccion.md#campos-de-control). ### Negociación de contenido Si el encabezado `Accept` contiene `text/html`, el controlador trabaja en **modo HTML** (vistas, PRG); con cualquier otro valor, en **modo REST** (JSON). Esa sola decisión define el formato de respuesta, la selección de vistas y el tratamiento de `POST`. ## Modelo y controlador de la entidad Con `@path_root` + `@base_path` + `_entities_type`, el controlador busca en la carpeta de la entidad: 1. **`model.dk`**: si existe, se incluye. Puede sustituir cualquier puntero del modelo genérico ([El modelo](/es/devkron/2.0/marcos/crudl/modelo.md)). 2. **`controller.dk`**: si existe, se incluye después del modelo, antes de resolver la operación. Conviene separarlos así: el modelo declara las funciones disponibles y el controlador elige, según la petición, qué puntero apunta a cuál. Desde `controller.dk` también puede cambiar `@form_view`, `@list_view`, `@url_redir` o cualquier otra variable, para que una entidad presente formularios distintos según el caso. ### Subrecursos con _view Una entidad necesita a menudo consultas auxiliares que no son entidades por derecho propio: el saldo de un cliente, buscar clientes al capturar una factura, los folios disponibles. El patrón es distinguirlas con un parámetro y reasignar el puntero de lectura o de lista: **`entidades/cliente/model.dk`** (fragmento) ```dkl Cliente.saldo::&db, ¶ms { ref c = entity.read(db, params) new r { @"codigo": @@(c,"$codigo") @"saldo": @@(c,"#saldo") } return r } ``` **`entidades/cliente/controller.dk`** ```dkl #include "dkli.dkh" #! module "Controlador de cliente" { switch @@(@http_context,"$request/get/_view") { case "saldo" { point @read to Cliente.saldo break } } } ``` ```text GET /tienda/cliente/1?_view=saldo → {"codigo":"CLI-0001","saldo":0.00} ``` El marco no reserva ningún nombre para esto: `_view` es la convención habitual de los sistemas construidos sobre CRUD-L; úsela por coherencia y no la emplee para otros fines. Las funciones pueden devolver cualquier estructura, no necesariamente la entidad. ## Selección de la operación ### POST en modo HTML Los formularios HTML solo emiten `GET` y `POST`. Por eso, en modo HTML, un `POST` sobre un identificador real (ni vacío ni `_new`) se trata como `PATCH` (modificación). Así el mismo formulario sirve para alta (`POST .../_new`) y edición (`POST .../10`). ### Correspondencia final | `Accept` | Método | `_entity_id` | Operación | Puntero | |---|---|---|---|---| | cualquiera | GET | ausente | list | `@list` | | cualquiera | GET | presente | read | `@read` | | cualquiera | GET | `_new` | read de un elemento en blanco | `@blank` | | `text/html` | POST | ausente o `_new` | create | `@create` | | `text/html` | POST | identificador real | update | `@update` | | otro | POST | cualquiera | create | `@create` | | cualquiera | PUT o PATCH | presente | update | `@update` | | cualquiera | DELETE | presente | delete | `@delete` | `_new` se configura con `@entity_id_blank`. `PUT` y `PATCH` invocan el mismo `@update`: use `PUT` cuando envíe todos los campos y `PATCH` cuando envíe solo algunos (con `PUT` incompleto, los omitidos no se tocan con el modelo genérico, pero un modelo propio podría ponerlos en nulo). ### Argumentos de cada puntero | Operación | Puntero | Argumentos | |---|---|---| | create | `@create` | `&db, ¶ms, &data` | | read | `@read` | `&db, ¶ms` | | read con `_new` | `@blank` | `&db, ¶ms` | | update | `@update` | `&db, ¶ms, &data` | | delete | `@delete` | `&db, ¶ms` | | list | `@list` | `&db, ¶ms` | Si el puntero de la operación es nulo, responde **404** `Operación no admitida` (con `_new`: `Operación no admitida (nuevo)`). En la baja, el estado se pone en **204** antes de invocar el puntero. ## Selección de la vista Terminada la operación se invoca `@success_view`; si hubo una excepción, `@fail_view`. Ambas reciben `¶ms, &input_data, &output_data, &error_info`. En modo REST las dos apuntan a la vista JSON; en modo HTML, el controlador de vistas (`@view_controller`) las asigna según la operación ([Vistas](/es/devkron/2.0/marcos/crudl/vistas.md)). ## Tratamiento de errores Toda la ejecución está protegida. Ante una excepción: 1. El estado HTTP es el código del error si es 400 o mayor; si no, **500**. 2. Se arma el objeto de error `{"message": "texto del error"}`. 3. Se invoca `@fail_view` con ese objeto. En modo REST, el objeto de error es el cuerpo de la respuesta. Ejemplo real: `GET /tienda/cliente/99` responde **404** con ```json {"message":"{404} Elemento no encontrado: {\"_entities_type\":\"cliente\",\"_entity_id\":\"99\",\"_operation\":\"read\"}[Ln= 98]"} ``` El mensaje trae el código y la línea porque el controlador del servidor activa `errordet(@true)`. Si quiere mensajes limpios para sus clientes, ponga `do errordet(@false)` en el punto de entrada. | Código | Situación | |---|---| | 204 | Baja realizada | | 404 | Elemento no encontrado; operación no admitida; identidad no indicada (`No se ha indicado la identidad de la entidad`); `Id no encontrado` con una clave alterna | | 500 | Vista no disponible; errores de base de datos (incluido el de concurrencia); cualquier otro error | ## Errores típicos | Síntoma | Causa y solución | |---|---| | Un formulario HTML crea en lugar de modificar | El `action` no lleva el identificador, o falta `Accept: text/html` (un `fetch` sin ese encabezado está en modo REST) | | `Operación no admitida` | El puntero de esa operación es nulo en el modelo | | Un campo de control llega a la base | No empieza con tres guiones (`---`) | | El `controller.dk` no se aplica | No está en la carpeta de la entidad, o se equivocó el nombre del parámetro (`_view`) |