# 07 — Frontend
---
## 1. Stack
| Capa | Tecnología | Ubicación |
|---|---|---|
| Plantilla | **Metronic 8.0.23 – Demo 1** | `public/metronic_html_v8.0.23_demo1/` |
| CSS framework | Bootstrap 5 (dentro del bundle de Metronic) | `assets/plugins/global/plugins.bundle.css`, `assets/css/style.bundle.css` |
| CSS propio | **Un solo fichero, 7 329 B** | `public/assets/kuorum-metronic-demo1.css` |
| JS framework | jQuery + Bootstrap 5 + KTApp (Metronic) | `assets/plugins/global/plugins.bundle.js`, `assets/js/scripts.bundle.js` |
| Tablas | DataTables (server-side) | `assets/plugins/custom/datatables/datatables.bundle.{css,js}` |
| Selectores | Select2 (`data-control="select2"`) | dentro del bundle |
| Iconos | Bootstrap Icons (`bi bi-*`) | dentro del bundle |
| Gráficas | ApexCharts | dentro del bundle |
| Tipografía | Poppins (Google Fonts) | CDN |
| Traducción DataTables | `https://cdn.datatables.net/plug-ins/1.11.3/i18n/es-mx.json` | CDN |
| Motor de plantillas | **Ninguno.** PHP plano | `app/views/` |
| Build tooling | **Ninguno.** No hay `package.json`, ni bundler, ni transpilación | — |
> Todo el JavaScript de la aplicación se genera **desde PHP**, principalmente en `core/ListaAjax.php`, o se escribe inline en las vistas. Solo hay tres ficheros `.js` propios: `public/js/quick-search.js`, `core/ajax.js` y `core/check_sessions.js`.
---
## 2. Estructura de una página
```mermaid
flowchart TD
L["app/layouts/metronic.php"] --> H["<head>: meta, favicon,\nQueueCss::getBefore(),\nplugins.bundle.css, style.bundle.css,\ndatatables.bundle.css,\nkuorum-metronic-demo1.css,\nQueueCss::getAfter(),\nplugins.bundle.js, scripts.bundle.js,\nQueueScripts::getBefore()"]
L --> A["#kt_aside\n→ layouts/menus/metronic.php"]
L --> HD["#kt_header\n→ layouts/shortcuts/metronic.php\n(quick-search + usuario + filtro de periodo)"]
L --> M["main#kt_content"]
M --> F["layouts/flashes/metronic.php"]
M --> C["include \$content\n(app/views/<carpeta>/<vista>.php)"]
M --> LG["layouts/logs/metronic.php"]
L --> FT["#kt_footer"]
L --> AL["alerts/metronic.php"]
L --> AI["_asistente_ia_widget.php"]
L --> S["datatables.bundle.js\nQueueScripts::getAfter()"]
```
El portal del colaborador (`metronic_public.php`) tiene la misma estructura con `menus/metronic_public.php` y `shortcuts/metronic_public.php`.
### Variables que el layout espera
Las inyecta `Controller::loadMetadata()`; el layout las consume tras el `extract()` de `View::render_view()`:
`$meta`, `$branding`, `$application`, `$Menu`, `$Shortcuts`, `$appColor`, `$controllerName`, `$currentAction`, `$parameters`, `$permission`, `$subtituloSection`, `$content`, `$menu_route`, `$shortcut_route`, `$flashes_route`, `$logs_route`.
El layout escapa con un closure local:
```php
$layoutEsc = static function ($value) {
return htmlspecialchars((string)$value, ENT_QUOTES, 'UTF-8');
};
```
---
## 3. Convenciones de vistas
### Contenedor estándar del backoffice
```php
```
### Formulario
```php
```
**Reglas no negociables del formulario:**
| # | Regla |
|---|---|
| 1 | El `action` se genera con `ROUTER::create_action_url()`, nunca a mano |
| 2 | `` siempre |
| 3 | Campo oculto con el `Id` del modelo, aunque esté vacío |
| 4 | El `name` de cada input es `[Campo->getName() ?>]` |
| 5 | La etiqueta sale de `$model->Campo->getTitle()` (definido en `getOptionsAttributes()`) |
| 6 | El valor sale de `$model->Campo->getValue()`, **siempre con `htmlspecialchars()`** |
| 7 | Los checkbox envían `value="1"` y se marcan con `Estado->getValue() === 1) echo 'checked'; ?>` |
| 8 | Botón Cancelar → `list`, botón Guardar → `submit` |
### Parciales
```php
```
`View::load_view($viewName, $parameters, $folder = 'app/views/')` hace `extract($parameters)` e incluye el fichero. Si no existe, registra `'Vista no encontrada :: …'` en `LogsConsole` **sin lanzar error**.
Convención: los parciales llevan prefijo `_` (`_form.php`, `_headboard.php`).
### Renderizar un fragmento a string (para AJAX)
```php
echo View::stream_view('home/seleccion_periodo_modal', $parameters, 'clear', 'home');
```
`stream_view()` devuelve el HTML como cadena en lugar de imprimirlo. El layout `clear` no añade envoltorio.
---
## 4. DataTables: el sistema de listados
Es el componente frontend más importante y **se genera íntegramente desde PHP**.
### En el controlador
```php
protected function getListAjaxObject()
{
$modelName = 'CompetenciasModel';
$fields = array('Id', 'Nombre', 'Categoria', 'Global', 'Nivel'); // columnas consultadas
$titles = array('Nombre', 'Categoría', 'Global', 'Nivel'); // cabeceras visibles
$fieldsShow = array('Nombre', 'Categoria', 'Global', 'Nivel'); // columnas mostradas
$fieldsType = array('Enlace', 'Texto', 'Texto', 'Texto'); // render por columna
$table = new ListaAjax($this->Module, $this->CurrentAction);
$table->setData(NULL, $fields, $titles, $fieldsType, $fieldsShow);
$table->setCheckbox(false);
$table->setFiltersSesion(array()); // array() = sin filtros globales de sesión
$table->setModel($modelName); // ← nombre de clase, NO instancia
return $table;
}
```
> ⚠️ `$titles` y `$fieldsShow` deben tener **la misma longitud**; `$fields` puede tener columnas adicionales que se consultan pero no se muestran (típicamente `Id` y `Estado`).
> `setModel()` recibe el **nombre de la clase como cadena**; `ListaAjax::generateDataListAjax()` hace `new $this->Model()`.
### En la vista
```php
```
`Controller::listAction()` ya rellena `$parameters['listaHtml'] = $table->getHtml()`.
### Métodos de configuración de `Lista` / `ListaAjax`
| Método | Efecto |
|---|---|
| `setData($data, $fields, $titles, $fieldsType, $fieldsShow)` | Configuración principal |
| `setModel($nombreClase)` | Modelo de origen |
| `setIdTable($id)` | Id HTML de la tabla (por defecto `Tabla1`) |
| `setActions($acciones)` | **Reemplaza** las acciones por defecto |
| `addActions($acciones)` | **Añade** a las existentes |
| `setPermission($permission)` | Permisos que gobiernan las acciones |
| `setCheckbox(bool)` | Columna de selección |
| `setCriteria($criteria)` | Criterio base |
| `setFilters($filtros)` | Filtros externos (inputs `#filtro-`) |
| `setFiltersSesion($array)` | `array()` desactiva los filtros globales |
| `setState(bool)` | Muestra la leyenda Activo/Inactivo y consulta `Estado` |
| `setRegistrationField($campo)` | Campo de propiedad (por defecto `UsuarioRegistro`) |
| `disableResponsive()` / `disablePaging()` / `disableOrdering()` | |
| `addAlias($fieldShow, $valores)` | Traduce valores a etiquetas |
| `addTags($fieldShow, $etiquetas)` | Renderiza el valor como badge |
| `addParameter($nombre, $valor)` | Parámetro extra en las URLs de acción |
### Acciones por defecto
`Lista::__construct()` establece:
```php
[
['name'=>'Editar','controller'=>$controller,'action'=>'edit',
'icon'=>'bi bi-pencil-fill fs-4','color'=>'btn-light-primary'],
['name'=>'Eliminar','controller'=>$controller,'action'=>'remove',
'icon'=>'bi bi-trash-fill fs-4','color'=>'btn-light-danger',
'confirm'=>['title'=>'Eliminar Registro',
'text'=>'¿Está seguro de que desea eliminar este registro de forma permanente?']]
]
```
**La acción `remove` no se renderiza como enlace, sino como un formulario POST con token CSRF:**
```html
```
Esto es lo que hace cumplible el guardia de `Controller::process()` que exige POST + CSRF para `remove`. Está cubierto por `tests/MutationSecurityRegressionTest::testLegacyRemoveActionsRequirePostAndCsrfAndListsSubmitThemAsForms`.
### Tipos de campo (`$fieldsType`)
| Valor | Render |
|---|---|
| `'Enlace'` | Enlace a `view`/`ver` del registro (solo si `permission['view'] > 0`), coloreado según `Estado` |
| `'Texto'` | Texto plano |
| `'Estado'` | Indicador de estado |
Otros valores se tratan como texto.
### Semántica de los valores de permiso
`ListaAjax` interpreta los permisos con **tres valores**, no dos:
| Valor | Significado |
|---|---|
| `0` | Sin acceso |
| `1` | Acceso total |
| `2` | **Solo los registros propios** — añade `WHERE {RegistrationField} = {usuarioActual}` al criterio y filtra las acciones fila a fila |
Este tercer nivel **solo lo implementa `ListaAjax`**; `Controller::validateAccess()` únicamente comprueba `> 0`.
### Flujo AJAX
```mermaid
sequenceDiagram
participant B as Navegador
participant DT as DataTables
participant C as XxxController
participant L as ListaAjax
participant M as XxxModel
B->>DT: carga la página, $listaHtml incluye el