Motor de plantillas de Reporter

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 lista cada etiqueta y cada filtro. Formatos de plantilla 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.

{
  "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.

{
  "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ó:

{% 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:

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 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:

{% 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 revisa la estructura, parsea el código generado y reporta cada problema contra el bloque que lo causó.
Generar código de plantilla devuelve el código terminado para un formato de salida.
Listar definiciones de bloque 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.

{
  "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 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:

{# reporter:output-encoding=utf-16be #}<?xml version="1.0" encoding="UTF-16"?>

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

Cómo funciona la generación de informes

El camino que va de una solicitud de informe a un archivo que puedes descargar.

Referencia de plantillas

Cada etiqueta, filtro y operador que acepta la sintaxis.

Formatos de plantilla

Una plantilla trabajada por formato de salida.

Conceptos centrales de Reporter

Plantillas, fuentes de datos, informes y plazos en un solo lugar.

Resumen

Conceptos

Guías

Integración

Console

Operaciones

Motor de plantillas de Reporter

El mapa de campos

El contexto de datos

Variables

Fuentes de datos multiesquema

Bloques

Dos clases de filtro

El paso de renderizado

Límites que aplica el motor

Próximos pasos

Cómo funciona la generación de informes

Referencia de plantillas

Formatos de plantilla

Conceptos centrales de Reporter

​El mapa de campos

​El contexto de datos

​Variables

​Fuentes de datos multiesquema

​Bloques

​Dos clases de filtro

​El paso de renderizado

​Límites que aplica el motor

​Próximos pasos

Cómo funciona la generación de informes

Referencia de plantillas

Formatos de plantilla

Conceptos centrales de Reporter

El mapa de campos

El contexto de datos

Variables

Fuentes de datos multiesquema

Bloques

Dos clases de filtro

El paso de renderizado

Límites que aplica el motor

Próximos pasos