> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Motor de plantillas de Reporter > Cómo Reporter evalúa una plantilla: el mapa de campos que deriva, el contexto de datos que arma, los bloques, los filtros de plantilla, los filtros de fila y el modelo de fuentes de datos multiesquema. Una plantilla de Reporter es un archivo `.tpl` de texto plano. Reporter la renderiza con un motor Pongo2, que lee etiquetas al estilo Django y filtros con sintaxis de pipe. [Referencia de plantillas](/es/reporter/template-reference) lista cada etiqueta y cada filtro. [Formatos de plantilla](/es/reporter/template-examples) muestra un archivo trabajado por formato de salida. Esta página cubre lo que hace el motor alrededor de esa sintaxis: qué lee de tu archivo, qué datos pone delante de él y qué límites le aplica. ## El mapa de campos *** Cuando subes una plantilla, Reporter analiza el texto y deriva un **mapa de campos**: cada fuente de datos, cada tabla y cada campo que la plantilla nombra. ```json theme={null} { "external_db": { "sales__orders": ["id", "total", "created_at"] } } ``` El mapa se guarda junto con los metadatos de la plantilla y viaja con cada solicitud de informe. La extracción lee solo lo que el mapa lista. Un campo que tu plantilla nunca nombra nunca se consulta, así que una plantilla sigue siendo barata a medida que crecen las tablas que hay detrás. De ahí se siguen dos consecuencias. Primero, Reporter deriva el mapa cuando subes o reemplazas el archivo, nunca en el momento del renderizado. Una referencia a un campo nuevo llega a un informe solo después de que subes la plantilla modificada. Segundo, Reporter contrasta el mapa con el esquema en vivo de cada fuente de datos al subirla. Un nombre de tabla equivocado o un nombre de campo equivocado aparece ahí, antes de que corra ningún informe. Cuando una fuente de datos no puede responder, Reporter devuelve advertencias y acepta la plantilla igual. Una base de datos inalcanzable no bloquea tu trabajo. ## El contexto de datos *** La extracción arma un contexto para el renderizado. El primer nivel es el nombre de configuración de la fuente de datos. El segundo nivel es la tabla. Cada valor es una lista de filas. ```json theme={null} { "external_db": { "orders": [ { "id": "018f...", "total": "1200.00", "created_at": "2026-07-01" } ] } } ``` Tu plantilla direcciona ese contexto con los mismos nombres con los que lo declaró: ```django theme={null} {% for order in external_db.orders %} {{ order.id }} — {{ order.total|floatformat:2 }} {% endfor %} ``` Las filas vuelven bajo la clave que escribió tu plantilla. Un nombre de tabla simple se mantiene simple. Una referencia calificada con esquema se vuelve `schema__table`, con doble guion bajo, tanto en el mapa de campos como en el contexto de render. Los filtros de fila son más flexibles y aceptan `schema.table` o `schema__table`. ### Variables Una plantilla lee el contexto a través de variables. Un alias de bucle liga una fila a la vez, y `{% with %}` nombra una parte del contexto para el bloque que va debajo. Ambos alias son locales al bloque que los declara. El analizador sigue un alias hasta la tabla que hay detrás. Un campo que lees como `order.total` dentro de un bucle sobre `external_db.orders` aterriza en el mapa de campos como `total` bajo esa tabla, así que la extracción lo devuelve. ## Fuentes de datos multiesquema *** Un operador declara cada fuente de datos mediante variables de entorno. `CONFIG_NAME` fija el nombre que usan tus plantillas, y `SCHEMAS` lista los esquemas que Reporter descubre en ella. Mantén idénticos el segmento del nombre de entorno y el valor de `CONFIG_NAME`, como en el bloque de abajo: ```bash theme={null} DATASOURCE_EXTERNAL_DB_CONFIG_NAME=external_db DATASOURCE_EXTERNAL_DB_HOST=external-postgres DATASOURCE_EXTERNAL_DB_PORT=5432 DATASOURCE_EXTERNAL_DB_USER=db_user DATASOURCE_EXTERNAL_DB_DATABASE=external_database DATASOURCE_EXTERNAL_DB_TYPE=postgresql DATASOURCE_EXTERNAL_DB_SCHEMAS=sales,inventory,reporting ``` Sin `SCHEMAS`, Reporter descubre solo el esquema `public`. Consulta [Variables de entorno](/es/reporter/reporter-environment-variables) para el bloque completo. El motor resuelve un nombre de tabla simple contra todos los esquemas descubiertos: | Dueños del nombre de tabla | Resultado | | ------------------------------------------ | --------------------------------------------------------------- | | Exactamente un esquema | El motor lee esa tabla. | | Varios esquemas, uno de ellos `public` | El motor lee la tabla de `public`. | | Varios esquemas, ninguno de ellos `public` | El motor reporta la tabla como ambigua y nombra las candidatas. | | Ningún esquema | El motor reporta la tabla como no encontrada. | Califica la referencia para eliminar la ambigüedad. La forma calificada nombra la fuente, el esquema y la tabla: ```django theme={null} {% for order in external_db:sales.orders %} {{ order.id }} {% endfor %} ``` Una referencia calificada debe coincidir exactamente con el esquema descubierto. El motor no busca esa tabla en otros esquemas. ## Bloques *** Un bloque es la unidad con la que trabaja el editor visual de plantillas. Existen trece tipos, en seis categorías: | Categoría | Tipos de bloque | | --------------------- | ------------------------------------------------------- | | Básico (`basic`) | `text`, `variable`, `comment` | | Control (`control`) | `loop`, `conditional`, `with` | | Datos (`data`) | `aggregation`, `calculation`, `date_time`, `expression` | | Diseño (`layout`) | `section` | | Numeración (`dimp`) | `counter` | | Avanzado (`advanced`) | `custom_tag` | El valor entre paréntesis es la cadena de categoría que devuelve el catálogo de bloques, así que un cliente que compara contra la respuesta de la API usa esa cadena y no la etiqueta. Cuatro de ellos contienen hijos: `loop`, `conditional`, `section` y `with`. Un condicional además lleva ramas alternativas. Los bloques anidan hasta cincuenta niveles de profundidad. Los bloques nunca se almacenan. El editor se los envía a Reporter, y Reporter devuelve código fuente Pongo2 más el mapa de campos que ese código implica. La plantilla que subes siempre es el texto. Tres operaciones sostienen ese flujo: * [Validar bloques de plantilla](/es/reference/reporter/validate-template-blocks) revisa la estructura, parsea el código generado y reporta cada problema contra el bloque que lo causó. * [Generar código de plantilla](/es/reference/reporter/generate-template-code) devuelve el código terminado para un formato de salida. * [Listar definiciones de bloque](/es/reference/reporter/list-block-definitions) devuelve el catálogo, para que un cliente se mantenga al día con el motor. ## Dos clases de filtro *** Reporter usa la palabra filtro para dos cosas distintas, y corren en momentos distintos. **Los filtros de fila** corren durante la extracción. Viven en la solicitud del informe, no en la plantilla, y reducen las filas que devuelve la base de datos. El payload los anida tres niveles: fuente de datos, después tabla, después campo. ```json theme={null} { "templateId": "018f2a6c-1c2f-7a10-9f1e-2b8c4d5e6f70", "filters": { "external_db": { "orders": { "status": { "nin": ["cancelled", "draft"] }, "created_at": { "gte": ["2026-07-01"], "lte": ["2026-07-31"] } } } } } ``` Existen ocho operadores: | Operador | Significado | Valores | | --------- | ------------------------------------ | --------------- | | `eq` | Coincide con cualquier valor listado | Uno o más | | `gt` | Por encima del valor | Uno | | `gte` | En el valor o por encima | Uno | | `lt` | Por debajo del valor | Uno | | `lte` | En el valor o por debajo | Uno | | `between` | Dentro de un rango inclusivo | Exactamente dos | | `in` | Coincide con cualquier valor listado | Uno o más | | `nin` | Excluye todos los valores listados | Uno o más | Cada operador toma un arreglo. Varios operadores sobre un mismo campo se combinan, como muestra el rango de fechas de arriba. **Los filtros de plantilla** corren durante el renderizado, después de que llegan las filas. Dan forma a un valor dentro del documento y usan sintaxis de pipe: `{{ value|percent_of:total }}`. [Listar definiciones de filtro](/es/reference/reporter/list-filter-definitions) devuelve el catálogo con un ejemplo por filtro. ## El paso de renderizado *** El motor parsea la plantilla preparada una vez por informe y la ejecuta contra el contexto. Dos comportamientos de ese paso cambian cómo diseñas un documento. La salida numérica pierde los ceros finales, así que `1200.00` se renderiza como `1200`. Usa `floatformat` cuando una columna necesite decimales fijos. Los valores que llevan varios puntos quedan intactos, lo que mantiene sin cambios un código contable como `1.1.2.00.000`. Una plantilla XML puede declarar la codificación del archivo guardado. Coloca el marcador en la misma línea que la declaración XML: ```django theme={null} {# reporter:output-encoding=utf-16be #} ``` Reporter escribe entonces el archivo en UTF-16BE sin marca de orden de bytes. La salida PDF ignora el marcador. ## Límites que aplica el motor *** Reporter bloquea las etiquetas de Pongo2 que cargan o extienden otro archivo: `include`, `extends`, `import`, `block` y `ssi`. Una plantilla es un documento autocontenido. El anidamiento de bloques se detiene en cincuenta niveles, tanto en la validación como en la generación de código. Los campos de bloque de formato libre rechazan los delimitadores de plantilla, así que la entrada del editor no puede inyectar una etiqueta. Las plantillas subidas rechazan etiquetas de script. ## Próximos pasos *** El camino que va de una solicitud de informe a un archivo que puedes descargar. Cada etiqueta, filtro y operador que acepta la sintaxis. Una plantilla trabajada por formato de salida. Plantillas, fuentes de datos, informes y plazos en un solo lugar.