Motor de plantillas de Reporter

Una plantilla de Reporter es un archivo de texto plano .tpl. Reporter la renderiza con un motor Pongo2, que interpreta etiquetas al estilo Django y filtros con sintaxis de barra vertical. Referencia de plantillas enumera cada etiqueta y filtro. Formatos de plantilla muestra un archivo resuelto por cada formato de salida.

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 almacena 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 se mantiene económica a medida que crecen las tablas subyacentes. De esto se derivan dos consecuencias. Primero, Reporter deriva el mapa cuando subes o reemplazas el archivo, nunca en el momento del renderizado. Una nueva referencia de campo llega a un informe solo después de que subes la plantilla modificada. Segundo, Reporter verifica el mapa contra el esquema en vivo de cada fuente de datos en el momento de la carga. Un nombre de tabla incorrecto o un nombre de campo incorrecto aparece ahí, antes de que se ejecute cualquier informe. Cuando una fuente de datos no puede responder, Reporter devuelve advertencias y aun así acepta la plantilla. Una base de datos inalcanzable no bloquea tu trabajo.

El contexto de datos

La extracción construye un único 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 se refiere a ese contexto con los mismos nombres que usó para declararlos:

{% for order in external_db.orders %}
  {{ order.id }} — {{ order.total|floatformat:2 }}
{% endfor %}

Las filas regresan bajo la clave que escribió tu plantilla. Un nombre de tabla sin calificar permanece sin calificar. Una referencia calificada por esquema se convierte en schema__table, con doble guion bajo, tanto en el mapa de campos como en el contexto de renderizado. Los filtros de fila son más flexibles y aceptan tanto schema.table como schema__table.

Variables

Una plantilla lee el contexto a través de variables. Un alias de bucle vincula una fila a la vez, y {% with %} nombra parte del contexto para el bloque que le sigue. Ambos alias son locales al bloque que los declara. El analizador rastrea un alias hasta la tabla que hay detrás de él. Un campo que lees como order.total dentro de un bucle sobre external_db.orders llega al mapa de campos como total bajo esa tabla, así que la extracción lo devuelve.

Fuentes de datos multiesquema

Una fuente de datos normalmente vive en el registro persistente de Reporter y se gestiona a través de la API de fuentes de datos. En modo de un solo tenant, un bloque de entorno puede sembrar una entrada del registro al iniciar el Manager, solo cuando ninguna entrada activa o eliminada de forma lógica ya usa ese nombre de configuración. El modo multi-tenant crea fuentes de datos por tenant a través de la API. CONFIG_NAME establece el nombre que usan tus plantillas, y SCHEMAS lista los esquemas que Reporter descubre en ella. Usa el mismo nombre para el segmento de nombre de entorno y para CONFIG_NAME, en mayúsculas en las claves de las variables de entorno, 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. La clave del esquema es DATASOURCE_{CONFIG_NAME}_SCHEMAS, mientras que las demás claves de entorno usan el segmento {NAME}. Consulta Variables de entorno para ver el bloque de arranque completo. El motor resuelve un nombre de tabla sin calificar contra cada esquema descubierto:

Propietarios del nombre de la 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 los candidatos.
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 la busca en otros esquemas.

Bloques

Un bloque es la unidad con la que trabaja el generador visual de plantillas. Existen trece tipos, en seis categorías:

Categoría	Tipos de bloque
Básica (`basic`)	`text`, `variable`, `comment`
Control (`control`)	`loop`, `conditional`, `with`
Datos (`data`)	`aggregation`, `calculation`, `date_time`, `expression`
Diseño (`layout`)	`section`
Numeración (`dimp`)	`counter`
Avanzada (`advanced`)	`custom_tag`

El valor entre paréntesis es lo que el catálogo de bloques devuelve como la cadena de categoría. Un cliente que compara la respuesta de la API se basa en eso, no en la etiqueta. Cuatro de ellos contienen hijos: loop, conditional, section y with. Un conditional también lleva ramas alternativas. Los bloques se anidan hasta cincuenta niveles de profundidad. Los bloques nunca se almacenan. El generador los envía a Reporter, y Reporter devuelve el 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 dan soporte a ese flujo:

Validar bloques de plantilla verifica la estructura, analiza el código generado y reporta cada problema contra el bloque que lo causó.
Generar código de plantilla devuelve el código final para un formato de salida.
Listar definiciones de bloque devuelve el catálogo, para que un cliente se mantenga sincronizado con el motor.

Dos tipos de filtro

Reporter usa la palabra filtro para dos cosas distintas, y se ejecutan en momentos diferentes. Los filtros de fila se ejecutan durante la extracción. Viven en la solicitud del informe, no en la plantilla, y limitan las filas que devuelve la base de datos. El payload los anida en tres niveles: fuente de datos, luego tabla, luego 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 o por encima del valor	Uno
`lt`	Por debajo del valor	Uno
`lte`	En o por debajo del valor	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 anterior. Los filtros de plantilla se ejecutan durante el renderizado, después de que llegan las filas. Dan forma a un valor dentro del documento, y usan sintaxis de barra vertical: {{ value|percent_of:total }}. Listar definiciones de filtro devuelve el catálogo con un ejemplo por filtro.

El paso de renderizado

El motor analiza 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 sus ceros finales, así que 1200.00 se renderiza como 1200. Usa floatformat cuando una columna necesite decimales fijos. Los valores que llevan varios puntos permanecen 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 almacenado. 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 entonces escribe el archivo en UTF-16BE sin marca de orden de bytes. La salida en 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 forma libre rechazan los delimitadores de plantilla, de modo que la entrada del generador no puede inyectar una etiqueta. Las plantillas subidas rechazan las etiquetas de script.

Próximos pasos

Cómo funciona la generación de informes

El camino desde una solicitud de informe hasta un archivo que puedes descargar.

Referencia de plantillas

Cada etiqueta, filtro y operador que acepta la sintaxis.

Formatos de plantilla

Una plantilla resuelta por cada formato de salida.

Conceptos básicos 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 tipos 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 básicos de Reporter

​El mapa de campos

​El contexto de datos

​Variables

​Fuentes de datos multiesquema

​Bloques

​Dos tipos 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 básicos de Reporter

El mapa de campos

El contexto de datos

Variables

Fuentes de datos multiesquema

Bloques

Dos tipos de filtro

El paso de renderizado

Límites que aplica el motor

Próximos pasos