> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Usando o Template Builder
> Construa templates de relatório visualmente, montando blocos em vez de escrever o código .tpl manualmente, e deixe o builder gerá-lo para você.
Use o Template Builder para criar ou manter um Template visualmente. O builder converte blocos em código `.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 `.tpl` gerado depois de construí-lo.
Use o envio de `.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
***
Vá para a página **Templates** e clique em **Template Builder**.
Edite o nome do Template no cabeçalho. Use um nome que os operadores possam identificar ao gerar o relatório.
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.
Use a barra de blocos para adicionar estrutura. Blocos comuns são **Texto**, **Variável**, **Loop**, **Condicional** e **Agregação**.
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.
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.
Clique em **Salvar**. O builder valida os campos obrigatórios dos blocos, gera o código `.tpl` e salva o Template.
## 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.
Blocos contêineres como **Loop**, **Condicional**, **Seção** e **With** podem conter blocos filhos. Use-os quando a saída precisar de conteúdo repetido ou agrupado.
## 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
***
A sidebar mostra apenas Data Sources configurados. Se a fonte interna esperada não está listada, confirme a configuração com o administrador do Reporter. Se o relatório precisa de um banco externo, adicione e teste esse Data Source antes de usar campos de banco no Template.
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.
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.
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](/pt/lerian-console/reporter-console/generating-a-report) para testar o Template com filtros reais.
* Use [Atualizar um Template](/pt/lerian-console/reporter-console/updating-a-template) para editar o Template depois.
* Use [Adicionar um Template](/pt/lerian-console/reporter-console/adding-template) se precisar enviar um arquivo `.tpl` preparado em vez disso.
Não há um endpoint de API separado para o builder visual. Use o [Endpoint Upload template](/pt/reference/reporter/upload-template) com um arquivo `.tpl` preparado.