> ## 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 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`. * 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 for incerta. A barra lateral **Data Sources** lista as tabelas e campos dela. * 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. > [!NOTE] > > 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 *** **1. Abra o builder** Vá até a página **Templates** e clique em **Template Builder**. **2. Nomeie o Template** Edite o nome do Template no cabeçalho. Use um nome que os operadores consigam identificar durante a geração do relatório. Depois informe a **Categoria**, a família do relatório, como `cadoc`. **3. Escolha o formato de saída** Selecione XML, HTML, CSV, TXT ou PDF. > [!NOTE] > > 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. **4. Adicione blocos ao canvas** Use a barra de ferramentas de blocos para adicionar estrutura. Os blocos comuns são **Text**, **Variable**, **Loop**, **Conditional** e **Aggregation**. **5. Conecte campos das Data Sources** 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. **6. Revise o código ou o preview quando necessário** Alterne de **Visual** para **Code** para inspecionar uma aproximação local, somente leitura, do código `.tpl`. Alterne para **Preview** para ver o Template renderizado pelo Reporter com valores de exemplo, não com dados reais. **7. Salve o Template** 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` | | **Categoria** | Família de relatório obrigatória no cabeçalho do builder. | `cadoc` | | **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. | Use ao organizar blocos | | **Code** | Aproximação local, somente leitura, do código `.tpl`, com **Copy code**. | Revisar o `.tpl` gerado | | **Preview** | O Template renderizado pelo Reporter com valores de exemplo. Um Template PDF é pré-visualizado como seu estágio HTML. | Conferir onde cada campo aparece | | **Download .tpl file** | Baixa o `.tpl` gerado sem salvar um novo Template. | `monthly-transaction-csv.tpl` | | **Save** | Valida blocos, gera código `.tpl` e cria o Template. Exige um nome, uma categoria 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 aceitos mostrados 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** mostra 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 *** > [accordion] Nenhuma Data Source aparece na barra lateral > > 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. > [accordion] Campos obrigatórios de bloco estão faltando > > 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. > [accordion] Usar filtros na parte errada do workflow > > 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. > [accordion] Escolher PDF sem entender o código gerado > > 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](https://docs.lerian.studio/pt/products/reporter/console/generating-a-report.md) para testar o Template com filtros reais. * Use [Atualizar um Template](https://docs.lerian.studio/pt/products/reporter/console/updating-a-template.md) para alterar o nome, o formato de saída, a categoria ou o arquivo `.tpl` depois. O builder não abre um Template salvo. * Use [Adicionar um Template](https://docs.lerian.studio/pt/products/reporter/console/adding-template.md) se precisar enviar um arquivo `.tpl` já pronto. > [card] Equivalente na API > > Chame o [Generate template code endpoint](https://docs.lerian.studio/pt/reference/products/reporter/generate-template-code.md) e depois envie o arquivo `.tpl` gerado com o [Upload template endpoint](https://docs.lerian.studio/pt/reference/products/reporter/upload-template.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.