.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.
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.
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. 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.
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:
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:
Califica la referencia para eliminar la ambigüedad. La forma calificada nombra la fuente, el esquema y la tabla:
Bloques
Un bloque es la unidad con la que trabaja el generador visual de plantillas. Existen trece tipos, en seis categorías:
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. La plantilla que subes siempre es el texto.
Tres operaciones dan soporte a ese flujo:
- Validar bloques de plantilla verifica la estructura 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.
isNull y notNull toman true. Todos los demás operadores toman un arreglo. Varios operadores sobre un mismo campo se combinan, como muestra el rango de fechas anterior. isNull va solo en su campo.
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. Tres 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 el filtro decimal, como en {{ total|decimal:2 }}, 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:
Parámetros de generación
Una plantilla puede declarar los parámetros que responde una solicitud de informe. Cada declaración es un comentario de plantilla:
name, type, required, default, allowedValues, description y appliesTo. El tipo es string, integer, decimal, boolean, date (YYYY-MM-DD) o month (YYYY-MM). Una declaración mal formada hace fallar la carga.
La solicitud de informe envía los valores en parameters, y la plantilla muestra uno de ellos como {{ system.dataBase }}. Cuando la plantilla declara parámetros, Reporter rechaza una solicitud que envía un parámetro no declarado. También rechaza una solicitud que omite un parámetro obligatorio sin valor predeterminado.
appliesTo vincula un parámetro date o month a un campo de fecha, escrito como <dataSource>.<table>.<field>. Reporter entonces agrega el fin de ese período como un filtro lte en el campo. Rechaza una solicitud que también define un límite superior en ese campo.
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. Reporter también bloquea filter, que aplica un filtro a un bloque entero de salida.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.