> ## 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 > Crie templates de relatório visualmente, montando blocos em vez de escrever código .tpl manualmente. Use o Template Builder para criar ou manter um Template visualmente. O builder converte blocos em código `.tpl`, para que operadores definam a estrutura do relatório sem escrever o arquivo de Template manualmente. ## Objetivo *** Monte um Template a partir de blocos visuais e salve-o para geração de Report futura. Por exemplo, um Template de transação mensal pode usar texto fixo para o cabeçalho e um **Loop** para cada linha de transação. Também pode usar blocos **Variable** para campos como valor e data, e um bloco **Aggregation** para o total. ## Quando usar *** Use o Template Builder quando: * operadores precisam criar um Template sem editar código `.tpl`. * um Template do Template Builder precisa de manutenção visual. * a estrutura do relatório depende de campos, loops, condições ou totais de uma Data Source. * a equipe quer baixar o arquivo `.tpl` gerado depois de montá-lo. Use o upload de `.tpl` quando uma equipe técnica já criou e revisou o Template fora do Console. ## Antes de começar *** Confirme: * que existe pelo menos uma Data Source relevante, caso o Template precise de campos do banco de dados. Pode ser uma fonte interna já configurada no ambiente ou uma fonte externa adicionada em **Data Sources**. * que você testou a Data Source quando a saúde da conexão ou a visibilidade do schema forem incertas. As tabelas e campos dela ficam então disponíveis na barra lateral. * que você conhece o formato de saída esperado: XML, HTML, CSV, TXT ou PDF. * que o operador conhece a estrutura do relatório, como cabeçalho obrigatório, linhas, totais ou seções condicionais. Os blocos definem a estrutura da saída. Os filtros aplicados durante a geração do Report definem quais registros entram nessa estrutura. ## Passo a passo *** Vá até a página **Templates** e clique em **Template Builder**. Edite o nome do Template no cabeçalho. Use um nome que os operadores consigam identificar durante a geração do relatório. Selecione XML, HTML, CSV, TXT ou PDF. Quando você seleciona **PDF**, o código de template gerado usa formato HTML. O código é convertido para PDF durante a geração do relatório. Use a barra de ferramentas de blocos para adicionar estrutura. Os blocos comuns são **Text**, **Variable**, **Loop**, **Conditional** e **Aggregation**. Use a barra lateral de Data Sources para navegar por schemas, tabelas e campos. Clique em um campo para adicionar um bloco **Variable** para esse campo. Alterne de **Visual** para **Code** para inspecionar o preview do `.tpl` gerado. A visualização de código serve para revisão e cópia/download, não para edição manual. Clique em **Save**. O builder valida os campos obrigatórios dos blocos, gera o código `.tpl` e salva o Template. ## Guia de campos *** ### Campos e controles em nível de builder | Campo ou controle | O que faz | Exemplo | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | **Template name** | Nome obrigatório no cabeçalho do builder. Corresponde a `name` e se torna o rótulo do Template salvo e o prefixo do nome de arquivo `.tpl` gerado. | `Monthly transaction CSV` | | **Output format** | 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 ao organizar blocos | | **Code** | Preview somente leitura do código `.tpl` gerado. Estado técnico: `viewMode = code`. | Revisar o `.tpl` gerado | | **Download .tpl file** | Baixa o `.tpl` gerado sem salvar um novo Template. | `monthly-transaction-csv.tpl` | | **Save** | Valida blocos, gera código `.tpl` e envia ou atualiza o Template. Exige um nome não vazio e pelo menos um bloco. | Salvar depois que os blocos forem válidos | ### Guia de campos por bloco | Bloco | Campos a configurar | Efeito | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | **Text** | **Content** (`content`) | Renderiza texto fixo, como cabeçalhos CSV, tags XML ou fragmentos HTML. | | **Variable** | **Data Source**, **Table**, **Field**, **Index (optional)**, **Filters** (`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** | **Iterator name** e **Iterable source** (`iteratorName`, `iterableSource`) | Repete blocos filhos sobre uma coleção. Use o formato `dataSource.table` para a fonte iterável. | | **Conditional** | **Condition** e **Include else block** (`condition`, `hasElse`) | Renderiza blocos filhos apenas quando a condição é verdadeira; um conteúdo else opcional pode ser renderizado quando for falsa. | | **Aggregation** | **Aggregation type**, **Source**, **Field**, campos opcionais de agrupamento/ordem/resultado (`aggregationType`, `source`, `aggregationField`) | Produz totais, contagens, médias, mínimos/máximos ou valores de **Last Item by Group** a partir de uma coleção de origem. | | **Calculation** | **Expression** (`expression`) | Renderiza um valor calculado. Os operadores suportados exibidos na UI incluem `+`, `-`, `*`, `/`, `**` e `%`. | | **Date/Time** | **Format** e **Date source** (`format`, `dateSource`) | Formata um valor de data, por exemplo `YYYY-MM-DD` a partir de `transaction.createdAt`. | | **Counter** | **Mode**, **Counter name** e **Counter names** (`counterMode`, `counterName`, `counterNames[]`) | **Increment** avança um contador. **Display** exibe um ou mais contadores. | | **Comment** | **Comment** (`commentText`) | Armazena uma nota interna do Template e não aparece no Report final. | | **Section** | **Section title** (`sectionTitle`) | Agrupa blocos filhos para organizar Templates maiores. | | **With (Assign)** | **Variable name** e **Assignment expression** (`variableName`, `assignment`) | Cria uma variável reutilizável a partir de uma expressão para blocos filhos. | | **Expression** | **Expression** (`inlineExpression`) | Renderiza uma expressão inline, como `item.name\|upper`. | | **Custom Tag** | **Tag name** e **Tag arguments** (`tagName`, `tagArgs`) | Emite uma tag de Template avançada, como `include`, com argumentos como `"header.html"` ou `key=value`. | ## Tipos de bloco *** | Bloco | O que representa na prática | | ----------------- | --------------------------------------------------------------------------------------------- | | **Text** | Conteúdo fixo que sempre aparece na saída, como um cabeçalho ou rótulo. | | **Variable** | Um valor de um campo de data source, como número de documento, valor ou status. | | **Loop** | Uma seção repetida, como uma linha para cada transação. | | **Conditional** | Conteúdo que aparece apenas quando uma regra é verdadeira, como `account.status == "active"`. | | **Aggregation** | Um total, contagem, média, mínimo, máximo ou último item por grupo. | | **Calculation** | Um valor calculado, como `value * 1.05`. | | **Date/Time** | Um valor de data ou hora formatado. | | **Counter** | Um número de linha ou valor de sequência. | | **Comment** | Nota interna do Template que não aparece no Report gerado. | | **Section** | Um grupo nomeado de blocos para organizar Templates maiores. | | **With (Assign)** | Uma variável reutilizável criada a partir de uma expressão. | | **Expression** | Uma expressão inline renderizada na saída. | | **Custom Tag** | Uma tag de Template personalizada, para quando é necessária sintaxe avançada de Template. | ## Trabalhando com blocos *** * Clique em um tipo de bloco na barra de ferramentas para adicioná-lo ao canvas. * Arraste blocos para reordenar a saída. * Configure cada bloco inline. Por exemplo, uma **Variable** precisa de uma origem e um campo, enquanto uma **Conditional** precisa de uma condição. * Use **Inline** quando o bloco deve ser renderizado sem quebra de linha depois dele. * Use **Trim whitespace** para remover espaços extras ao redor da saída do bloco. * Use **Duplicate** para copiar um bloco configurado. * Use **Delete** para remover um bloco do Template. Blocos container como **Loop**, **Conditional**, **Section** e **With** podem conter blocos filhos. Use-os quando a saída precisar de conteúdo repetido ou agrupado. ## Resultado esperado *** Depois de salvar, o Template aparece na página **Templates**. Você pode selecioná-lo no assistente **Generate Report**. Você também pode baixar o arquivo `.tpl` gerado a partir do builder. ## Erros comuns e pontos de atenção *** A barra lateral mostra apenas Data Sources configuradas. Se a fonte interna esperada não aparecer, confirme a configuração com o administrador do Reporter. Se o relatório precisar de um banco de dados externo, adicione e teste essa Data Source antes de usar campos do banco de dados no Template. O builder valida os blocos durante o salvamento. Se um bloco não tiver origem, campo, condição ou expressão, corrija esse bloco antes de salvar. Os blocos do Template definem a estrutura do arquivo. Você seleciona os filtros do relatório depois, durante a geração do relatório. Eles decidem quais registros entram na saída. A saída em PDF vem de HTML. Monte o Template com conteúdo compatível com HTML quando o formato de saída final for PDF. ## Próximos passos *** * Use [Gerar um Report](/pt/products/reporter/console/generating-a-report) para testar o Template com filtros reais. * Use [Atualizar um Template](/pt/products/reporter/console/updating-a-template) para editar o Template depois. * Use [Adicionar um Template](/pt/products/reporter/console/adding-template) se precisar enviar um arquivo `.tpl` já pronto. Não existe um endpoint de API separado para o builder visual. Use [Upload template endpoint](/pt/reference/products/reporter/upload-template) com um arquivo `.tpl` já pronto.