.tpl, então os operadores podem definir a estrutura do relatório sem escrever o arquivo do Template manualmente.
Objetivo
Construir um Template a partir de blocos visuais e salvá-lo para futuras gerações de Relatório. Por exemplo, um Template de transações mensais pode usar texto fixo no cabeçalho, um Loop para cada linha de transação, blocos Variável para campos como valor e data, e um bloco Agregação para o total.
Quando usar
Use o Template Builder quando:
- os operadores precisam criar um Template sem editar código
.tpl; - um Template do Template Builder precisa ser mantido visualmente;
- a estrutura do relatório depende de campos, loops, condições ou totais de um Data Source;
- o time quer baixar o arquivo
.tplgerado depois de construí-lo.
.tpl em vez disso quando um time técnico já criou e revisou o Template fora do Console.
Antes de começar
Confirme:
- existe pelo menos um Data Source relevante se o Template precisa de campos de banco. Pode ser uma fonte interna já configurada para o ambiente ou uma externa adicionada a partir de Data Sources;
- o Data Source foi testado quando a saúde da conexão ou a visibilidade do schema são incertas, para que as tabelas e campos fiquem disponíveis na sidebar;
- o formato de saída esperado é conhecido: XML, HTML, CSV, TXT ou PDF;
- o operador conhece a estrutura do relatório, como cabeçalho exigido, linhas, totais ou seções condicionais.
Os blocos definem a estrutura da saída. Os filtros aplicados durante a geração do Relatório definem quais registros entram nessa estrutura.
Passo a passo
Dê nome ao Template
Edite o nome do Template no cabeçalho. Use um nome que os operadores possam identificar ao gerar o relatório.
Escolha o formato de saída
Selecione XML, HTML, CSV, TXT ou PDF.
Quando PDF é selecionado, o código do template gerado usa o formato HTML e é convertido para PDF durante a geração do relatório.
Adicione blocos ao canvas
Use a barra de blocos para adicionar estrutura. Blocos comuns são Texto, Variável, Loop, Condicional e Agregação.
Conecte campos a partir de Data Sources
Use a sidebar de Data Sources para navegar por schemas, tabelas e campos. Clique em um campo para adicionar um bloco Variável para esse campo.
Revise o código gerado quando necessário
Mude de Visual para Código para inspecionar a pré-visualização
.tpl gerada. A visão de código é para revisão e cópia/download, não para edição manual.Guia de campos
Campos e controles a nível de builder
| Campo ou controle | O que faz | Exemplo |
|---|---|---|
| Nome do template | Nome obrigatório no cabeçalho do builder. Mapeia para name e vira o rótulo salvo do Template e o prefixo do nome do arquivo .tpl gerado. | Monthly transaction CSV |
| Formato de saída | Formato obrigatório. Use xml, html, csv, txt ou pdf. Quando pdf é selecionado, a geração de código usa HTML internamente. | pdf |
| Visual | Modo de editor de blocos para montar o Template. Estado técnico: viewMode = visual. | Use enquanto organiza os blocos |
| Código | Pré-visualização somente leitura do código .tpl gerado. Estado técnico: viewMode = code. | Revisar o .tpl gerado |
| Baixar arquivo .tpl | Baixa o .tpl gerado sem salvar um novo Template. | monthly-transaction-csv.tpl |
| Salvar | Valida blocos, gera código .tpl e envia ou atualiza o Template. Requer um nome não vazio e pelo menos um bloco. | Salve após os blocos ficarem válidos |
Guia de campos por bloco
| Bloco | Campos a configurar | Efeito |
|---|---|---|
| Texto | Conteúdo (content) | Renderiza texto fixo como cabeçalhos CSV, tags XML ou fragmentos HTML. |
| Variável | Data Source, Tabela, Campo, Índice (opcional), Filtros (dataSource, table, field, index, filters[]) | Insere o valor de um campo. Dentro de um Loop pai, Data Source pode ser preenchido automaticamente a partir do iterador do loop. |
| Loop | Nome do iterador e Fonte iterável (iteratorName, iterableSource) | Repete blocos filhos sobre uma coleção. Use o formato dataSource.table para a fonte iterável. |
| Condicional | Condição e Incluir bloco else (condition, hasElse) | Renderiza blocos filhos somente quando a condição é verdadeira; o conteúdo else opcional pode renderizar quando falsa. |
| Agregação | Tipo de agregação, Fonte, Campo, campos opcionais de agrupamento/ordem/resultado (aggregationType, source, aggregationField) | Produz totais, contagens, médias, mín/máx ou valores Último Item por Grupo a partir de uma coleção fonte. |
| Cálculo | Expressão (expression) | Renderiza um valor calculado. Operadores suportados exibidos na UI incluem +, -, *, /, ** e %. |
| Data/Hora | Formato e Fonte da data (format, dateSource) | Formata um valor de data, por exemplo YYYY-MM-DD a partir de transaction.createdAt. |
| Contador | Modo, Nome do contador e Nomes dos contadores (counterMode, counterName, counterNames[]) | Incrementar avança um contador. Exibir exibe um ou mais contadores. |
| Comentário | Comentário (commentText) | Armazena uma nota interna do Template e não aparece no Relatório final. |
| Seção | Título da seção (sectionTitle) | Agrupa blocos filhos para organizar Templates maiores. |
| With (Atribuir) | Nome da variável e Expressão de atribuição (variableName, assignment) | Cria uma variável reutilizável a partir de uma expressão para os blocos filhos. |
| Expressão | Expressão (inlineExpression) | Renderiza uma expressão inline como item.name|upper. |
| Tag Personalizada | Nome da tag e Argumentos da tag (tagName, tagArgs) | Emite uma tag avançada de Template como include com argumentos do tipo "header.html" ou key=value. |
Tipos de bloco
| Bloco | O que representa na prática |
|---|---|
| Texto | Conteúdo fixo que sempre aparece na saída, como um cabeçalho ou rótulo. |
| Variável | Um valor de um campo de data source, como número de documento, valor ou status. |
| Loop | Uma seção repetida, como uma linha por transação. |
| Condicional | Conteúdo que aparece somente quando uma regra é verdadeira, como account.status == "active". |
| Agregação | Um total, contagem, média, mín, máx ou last item by group. |
| Cálculo | Um valor calculado, como value * 1.05. |
| Data/Hora | Um valor de data ou hora formatado. |
| Contador | Um número de linha ou valor de sequência. |
| Comentário | Nota interna do Template que não aparece no Relatório gerado. |
| Seção | Um grupo nomeado de blocos para organizar Templates maiores. |
| With (Atribuir) | Uma variável reutilizável criada a partir de uma expressão. |
| Expressão | Uma expressão inline renderizada na saída. |
| Tag Personalizada | Uma tag de Template personalizada quando sintaxe avançada é necessária. |
Trabalhando com blocos
- Clique em um tipo de bloco na barra para adicioná-lo ao canvas.
- Arraste blocos para reordenar a saída.
- Configure cada bloco inline. Por exemplo, um Variável precisa de fonte e campo, enquanto um Condicional precisa de uma condição.
- Use Inline quando o bloco deve renderizar sem uma quebra de linha depois.
- Use Remover espaços em branco para remover espaços extras ao redor da saída do bloco.
- Use Duplicar para copiar um bloco configurado.
- Use Excluir para remover um bloco do Template.
Resultado esperado
Após salvar, o Template aparece na página Templates e pode ser selecionado no wizard Gerar Relatório. Você também pode baixar o arquivo
.tpl gerado a partir do builder.
Erros comuns e pontos de atenção
Nenhum Data Source aparece na sidebar
Nenhum Data Source aparece na sidebar
Campos obrigatórios estão faltando nos blocos
Campos obrigatórios estão faltando nos blocos
O builder valida os blocos ao salvar. Se um bloco está sem fonte, campo, condição ou expressão, corrija esse bloco antes de salvar.
Usar filtros na parte errada do fluxo
Usar filtros na parte errada do fluxo
Os blocos do Template definem a estrutura do arquivo. Os filtros de Relatório são selecionados depois durante a geração e decidem quais registros entram na saída.
Escolher PDF sem entender o código gerado
Escolher PDF sem entender o código gerado
A saída PDF é gerada a partir de HTML. Construa o Template como conteúdo compatível com HTML quando o formato final for PDF.
Próximos passos
- Use Gerar um Relatório para testar o Template com filtros reais.
- Use Atualizar um Template para editar o Template depois.
- Use Adicionar um Template se precisar enviar um arquivo
.tplpreparado em vez disso.