Motor de templates do Reporter

Um template do Reporter é um arquivo .tpl em texto simples. O Reporter o renderiza com um motor Pongo2, que lê tags no estilo Django e filtros com pipe. Referência de template lista todas as tags e filtros. Formatos de template mostra um arquivo pronto para cada formato de saída.

O mapa de campos

Quando você envia um template, o Reporter analisa o texto e deriva um mapa de campos: cada fonte de dados, cada tabela e cada campo que o template nomeia.

{
  "external_db": {
    "sales__orders": ["id", "total", "created_at"]
  }
}

O mapa é armazenado com os metadados do template e viaja com cada requisição de relatório. A extração lê apenas o que o mapa lista. Um campo que o seu template nunca nomeia nunca é consultado, então um template permanece barato à medida que as tabelas subjacentes crescem. Duas consequências decorrem disso. Primeiro, o Reporter deriva o mapa quando você envia ou substitui o arquivo, nunca no momento da renderização. Uma nova referência de campo apenas chega a um relatório depois que você envia o template alterado. Segundo, o Reporter confere o mapa com o esquema de cada fonte de dados no momento do envio. Um nome de tabela errado ou um nome de campo errado aparece ali, antes de qualquer relatório rodar. Quando uma fonte de dados não pode responder, o Reporter retorna avisos e ainda assim aceita o template. Um banco de dados inacessível não bloqueia o seu trabalho.

O contexto de dados

A extração monta um contexto para a renderização. O primeiro nível é o nome de configuração da fonte de dados. O segundo nível é a tabela. Cada valor é uma lista de linhas.

{
  "external_db": {
    "orders": [
      { "id": "018f...", "total": "1200.00", "created_at": "2026-07-01" }
    ]
  }
}

O seu template acessa esse contexto pelos mesmos nomes usados para declará-los:

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

As linhas voltam sob a chave que o seu template escreveu. Um nome de tabela sem qualificação permanece sem qualificação. Uma referência qualificada por esquema vira schema__table, com underscore duplo, tanto no mapa de campos quanto no contexto de renderização. Os filtros de linha são mais flexíveis e aceitam tanto schema.table quanto schema__table.

Variáveis

Um template lê o contexto por meio de variáveis. Um alias de loop vincula uma linha por vez, e {% with %} nomeia parte do contexto para o bloco abaixo dele. Os dois aliases são locais ao bloco que os declara. O analisador rastreia um alias de volta até a tabela por trás dele. Um campo que você lê como order.total dentro de um loop sobre external_db.orders chega ao mapa de campos como total sob essa tabela, então a extração o retorna.

Fontes de dados multi-schema

Uma fonte de dados normalmente vive no registro persistente do Reporter e é gerenciada pela API de fontes de dados. Um bloco de ambiente pode semear uma entrada no registro na inicialização do Manager apenas quando nenhuma entrada ativa ou com exclusão lógica já usa esse nome de configuração. CONFIG_NAME define o nome que os seus templates usam, e SCHEMAS lista os esquemas que o Reporter descobre nela. Use o mesmo nome para o segmento de nome de ambiente e para CONFIG_NAME, deixando esse nome em maiúsculas nas chaves de variável de ambiente, como no bloco abaixo:

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

Sem SCHEMAS, o Reporter descobre apenas o esquema public. A chave de esquema é DATASOURCE_{CONFIG_NAME}_SCHEMAS, enquanto as outras chaves de ambiente usam o segmento {NAME}. Veja Variáveis de ambiente para o bloco de bootstrap completo. O motor resolve um nome de tabela sem qualificação em relação a cada esquema descoberto:

Donos do nome da tabela	Resultado
Exatamente um esquema	O motor lê essa tabela.
Vários esquemas, nenhum deles `public`	O motor reporta a tabela como ambígua e nomeia as candidatas.
Nenhum esquema	O motor reporta a tabela como não encontrada.

Qualifique a referência para remover a ambiguidade. A forma qualificada nomeia a fonte, o esquema e a tabela:

{% for order in external_db:sales.orders %}
  {{ order.id }}
{% endfor %}

Uma referência qualificada deve corresponder exatamente ao esquema descoberto. O motor não procura em outros esquemas por ela.

Blocos

Um bloco é a unidade com que o construtor visual de templates trabalha. Existem treze tipos, em seis categorias:

Categoria	Tipos de bloco
Básico (`basic`)	`text`, `variable`, `comment`
Controle (`control`)	`loop`, `conditional`, `with`
Dados (`data`)	`aggregation`, `calculation`, `date_time`, `expression`
Layout (`layout`)	`section`
Numeração (`dimp`)	`counter`
Avançado (`advanced`)	`custom_tag`

O valor entre parênteses é o que o catálogo de blocos retorna como string de categoria. Um cliente que faz correspondência na resposta da API usa essa chave, não o rótulo. Quatro deles contêm filhos: loop, conditional, section e with. Um conditional também carrega ramos alternativos. Os blocos se aninham até cinquenta níveis de profundidade. Os blocos nunca são armazenados. O construtor os envia ao Reporter, e o Reporter retorna o código-fonte Pongo2. O template que você envia é sempre o texto. Três operações dão suporte a esse fluxo:

Validar blocos de template confere a estrutura e reporta cada problema em relação ao bloco que o causou.
Gerar código de template retorna o código-fonte finalizado para um formato de saída.
Listar definições de bloco retorna o catálogo, para que um cliente permaneça alinhado com o motor.

Dois tipos de filtro

O Reporter usa a palavra filtro para duas coisas diferentes, que rodam em momentos diferentes. Filtros de linha rodam durante a extração. Eles vivem na requisição de relatório, não no template, e restringem as linhas que o banco de dados retorna. O payload os aninha em três níveis: fonte de dados, depois tabela, depois 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"] }
      }
    }
  }
}

Existem doze operadores:

Operador	Significado	Valores
`eq`	Corresponde a qualquer valor listado	Um ou mais
`gt`	Acima do valor	Um
`gte`	No valor ou acima	Um
`lt`	Abaixo do valor	Um
`lte`	No valor ou abaixo	Um
`between`	Dentro de um intervalo inclusivo	Exatamente dois
`in`	Corresponde a qualquer valor listado	Um ou mais
`nin`	Exclui todos os valores listados e mantém uma linha sem valor	Um ou mais
`startsWith`	Começa com qualquer prefixo listado	Um ou mais prefixos de texto
`notStartsWith`	Não começa com nenhum prefixo listado e mantém uma linha sem valor	Um ou mais prefixos de texto
`isNull`	Não tem valor	`true`
`notNull`	Tem um valor	`true`

isNull e notNull recebem true. Todos os outros operadores recebem um array. Vários operadores em um mesmo campo se combinam, como o intervalo de datas acima mostra. isNull fica sozinho no seu campo. Filtros de template rodam durante a renderização, depois que as linhas chegam. Eles moldam um valor dentro do documento e usam sintaxe de pipe: {{ value|percent_of:total }}. Listar definições de filtro retorna o catálogo com um exemplo por filtro.

A etapa de renderização

O motor faz o parsing do template preparado uma vez por relatório e o executa contra o contexto. Três comportamentos dessa etapa mudam como você projeta um documento. A saída numérica perde os zeros à direita, então 1200.00 é renderizado como 1200. Use o filtro decimal, como em {{ total|decimal:2 }}, quando uma coluna precisar de casas decimais fixas. Valores com vários pontos permanecem intactos, o que mantém um código contábil como 1.1.2.00.000 inalterado. Um template XML pode declarar a codificação do arquivo armazenado. Coloque o marcador na mesma linha da declaração XML:

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

O Reporter então grava o arquivo em UTF-16BE com marca de ordem de bytes. A saída em PDF ignora o marcador. Quando a saída renderizada começa com linhas em branco e depois uma declaração XML, o Reporter remove as linhas em branco, então os comentários do template podem ficar acima da declaração.

Parâmetros de geração

Um template pode declarar os parâmetros que uma requisição de relatório responde. Cada declaração é um comentário de template:

{# reporter:parameter name=dataBase type=month required=true #}

Uma declaração aceita as chaves name, type, required, default, allowedValues, description e appliesTo. O tipo é string, integer, decimal, boolean, date (YYYY-MM-DD) ou month (YYYY-MM). Uma declaração malformada faz o upload falhar. A requisição de relatório envia os valores em parameters, e o template mostra um deles como {{ system.dataBase }}. Quando o template declara parâmetros, o Reporter recusa uma requisição que envia um parâmetro não declarado. Ele também recusa uma requisição que omite um parâmetro obrigatório sem valor padrão. appliesTo vincula um parâmetro date ou month a um campo de data, escrito como <dataSource>.<table>.<field>. O Reporter então adiciona o fim desse período como um filtro lte no campo. Ele recusa uma requisição que também define um limite superior nesse campo.

Limites que o motor aplica

O Reporter bloqueia as tags do Pongo2 que carregam ou estendem outro arquivo: include, extends, import, block e ssi. Um template é um documento autocontido. O Reporter também bloqueia filter, que aplica um filtro a um bloco inteiro de saída.

O aninhamento de blocos para em cinquenta níveis, tanto na validação quanto na geração de código. Campos de bloco de texto livre rejeitam delimitadores de template, então a entrada do construtor não pode injetar uma tag. Templates enviados rejeitam tags de script.

Próximos passos

Como funciona a geração de relatórios

O caminho de uma requisição de relatório até um arquivo que você pode baixar.

Referência de template

Toda tag, filtro e operador que a sintaxe aceita.

Formatos de template

Um template pronto para cada formato de saída.

Conceitos essenciais do Reporter

Templates, fontes de dados, relatórios e prazos em um só lugar.

Visão geral

Conceitos

Guias

Integração

Console

Operações

Motor de templates do Reporter

O mapa de campos

O contexto de dados

Variáveis

Fontes de dados multi-schema

Blocos

Dois tipos de filtro

A etapa de renderização

Parâmetros de geração

Limites que o motor aplica

Próximos passos

Como funciona a geração de relatórios

Referência de template

Formatos de template

Conceitos essenciais do Reporter

​O mapa de campos

​O contexto de dados

​Variáveis

​Fontes de dados multi-schema

​Blocos

​Dois tipos de filtro

​A etapa de renderização

​Parâmetros de geração

​Limites que o motor aplica

​Próximos passos

Como funciona a geração de relatórios

Referência de template

Formatos de template

Conceitos essenciais do Reporter

O mapa de campos

O contexto de dados

Variáveis

Fontes de dados multi-schema

Blocos

Dois tipos de filtro

A etapa de renderização

Parâmetros de geração

Limites que o motor aplica

Próximos passos