> ## 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.
# Usar el Template Builder
> Construye templates de informe visualmente ensamblando bloques en lugar de escribir el código .tpl a mano, y deja que el builder lo genere por ti.
Usa Template Builder para crear o mantener un Template visualmente. El builder convierte los bloques en código `.tpl`, de modo que los operadores pueden definir la estructura del informe sin escribir el archivo del Template a mano.
## Objetivo
***
Construir un Template a partir de bloques visuales y guardarlo para futuras generaciones de Report.
Por ejemplo, un Template de transacciones mensuales puede usar texto fijo para la cabecera, un **Loop** por cada fila de transacción, bloques **Variable** para campos como monto y fecha, y un bloque **Aggregation** para el total.
## Cuándo usarlo
***
Usa Template Builder cuando:
* los operadores necesitan crear un Template sin editar código `.tpl`;
* un Template del Template Builder debe mantenerse visualmente;
* la estructura del informe depende de campos, bucles, condiciones o totales de un Data Source;
* el equipo quiere descargar el archivo `.tpl` generado tras construirlo.
Usa la subida de `.tpl` en su lugar cuando un equipo técnico ya creó y revisó el Template fuera de la Console.
## Antes de empezar
***
Confirma:
* existe al menos un Data Source relevante si el Template necesita campos de base de datos. Puede ser una fuente interna ya configurada para el entorno o una externa añadida desde **Data Sources**;
* el Data Source fue probado cuando la salud de la conexión o la visibilidad del schema es incierta, para que sus tablas y campos estén disponibles en la barra lateral;
* se conoce el formato de salida esperado: XML, HTML, CSV, TXT o PDF;
* el operador conoce la estructura del informe, como cabecera requerida, filas, totales o secciones condicionales.
Los bloques definen la estructura de la salida. Los filtros aplicados durante la generación del Report definen qué registros entran en esa estructura.
## Paso a paso
***
Ve a la página **Templates** y haz clic en **Template Builder**.
Edita el nombre del Template en el encabezado. Usa un nombre que los operadores puedan identificar al generar el informe.
Selecciona XML, HTML, CSV, TXT o PDF.
Cuando se selecciona **PDF**, el código del template generado usa formato HTML y se convierte a PDF durante la generación del informe.
Usa la barra de bloques para añadir estructura. Los bloques comunes son **Text**, **Variable**, **Loop**, **Conditional** y **Aggregation**.
Usa la barra lateral de Data Sources para navegar por schemas, tablas y campos. Haz clic en un campo para añadir un bloque **Variable** para ese campo.
Cambia de **Visual** a **Code** para inspeccionar la previsualización `.tpl` generada. La vista de código es para revisión y copia/descarga, no para edición manual.
Haz clic en **Save**. El builder valida los campos requeridos de los bloques, genera el código `.tpl` y guarda el Template.
## Guía de campos
***
### Campos y controles a nivel de builder
| Campo o control | Qué hace | Ejemplo |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| **Template name** | Nombre obligatorio en el encabezado del builder. Se mapea a `name` y se convierte en la etiqueta guardada del Template y el prefijo del nombre del archivo `.tpl` generado. | `Monthly transaction CSV` |
| **Output format** | Formato obligatorio. Usa `xml`, `html`, `csv`, `txt` o `pdf`. Cuando se selecciona `pdf`, la generación de código usa HTML internamente. | `pdf` |
| **Visual** | Modo de editor de bloques para ensamblar el Template. Estado técnico: `viewMode = visual`. | Usar mientras organizas los bloques |
| **Code** | Previsualización solo-lectura del código `.tpl` generado. Estado técnico: `viewMode = code`. | Revisar el `.tpl` generado |
| **Download .tpl file** | Descarga el `.tpl` generado sin guardar un nuevo Template. | `monthly-transaction-csv.tpl` |
| **Save** | Valida bloques, genera código `.tpl` y sube o actualiza el Template. Requiere un nombre no vacío y al menos un bloque. | Guardar tras tener los bloques válidos |
### Guía de campos por bloque
| Bloque | Campos a configurar | Efecto |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Text** | **Content** (`content`) | Renderiza texto fijo como cabeceras CSV, etiquetas XML o fragmentos HTML. |
| **Variable** | **Data Source**, **Table**, **Field**, **Index (optional)**, **Filters** (`dataSource`, `table`, `field`, `index`, `filters[]`) | Inserta el valor de un campo. Dentro de un **Loop** padre, **Data Source** puede autocompletarse desde el iterador del loop. |
| **Loop** | **Iterator name** e **Iterable source** (`iteratorName`, `iterableSource`) | Repite bloques hijos sobre una colección. Usa el formato `dataSource.table` para la fuente iterable. |
| **Conditional** | **Condition** e **Include else block** (`condition`, `hasElse`) | Renderiza bloques hijos solo cuando la condición es verdadera; el contenido else opcional puede renderizarse cuando es falsa. |
| **Aggregation** | **Aggregation type**, **Source**, **Field**, campos opcionales de agrupación/orden/resultado (`aggregationType`, `source`, `aggregationField`) | Produce totales, conteos, promedios, mín/máx o valores **Last Item by Group** a partir de una colección fuente. |
| **Calculation** | **Expression** (`expression`) | Renderiza un valor calculado. Los operadores soportados que muestra la UI incluyen `+`, `-`, `*`, `/`, `**` y `%`. |
| **Date/Time** | **Format** y **Date source** (`format`, `dateSource`) | Formatea un valor de fecha, por ejemplo `YYYY-MM-DD` a partir de `transaction.createdAt`. |
| **Counter** | **Mode**, **Counter name** y **Counter names** (`counterMode`, `counterName`, `counterNames[]`) | **Increment** avanza un contador. **Display** muestra uno o más contadores. |
| **Comment** | **Comment** (`commentText`) | Almacena una nota interna del Template y no aparece en el Report final. |
| **Section** | **Section title** (`sectionTitle`) | Agrupa bloques hijos para organizar Templates más grandes. |
| **With (Assign)** | **Variable name** y **Assignment expression** (`variableName`, `assignment`) | Crea una variable reutilizable a partir de una expresión para los bloques hijos. |
| **Expression** | **Expression** (`inlineExpression`) | Renderiza una expresión inline como `item.name\|upper`. |
| **Custom Tag** | **Tag name** y **Tag arguments** (`tagName`, `tagArgs`) | Emite una etiqueta avanzada de Template como `include` con argumentos del tipo `"header.html"` o `key=value`. |
## Tipos de bloque
***
| Bloque | Qué representa en la práctica |
| ----------------- | -------------------------------------------------------------------------------------------- |
| **Text** | Contenido fijo que siempre aparece en la salida, como una cabecera o etiqueta. |
| **Variable** | Un valor de un campo de un data source, como número de documento, monto o estado. |
| **Loop** | Una sección repetida, como una fila por cada transacción. |
| **Conditional** | Contenido que aparece solo cuando una regla es verdadera, como `account.status == "active"`. |
| **Aggregation** | Un total, conteo, promedio, mín, máx o last item by group. |
| **Calculation** | Un valor calculado, como `value * 1.05`. |
| **Date/Time** | Un valor de fecha o tiempo formateado. |
| **Counter** | Un número de fila o valor de secuencia. |
| **Comment** | Nota interna del Template que no aparece en el Report generado. |
| **Section** | Un grupo con nombre de bloques para organizar Templates más grandes. |
| **With (Assign)** | Una variable reutilizable creada a partir de una expresión. |
| **Expression** | Una expresión inline renderizada en la salida. |
| **Custom Tag** | Una etiqueta de Template personalizada cuando se necesita sintaxis avanzada. |
## Trabajar con bloques
***
* Haz clic en un tipo de bloque en la barra para añadirlo al canvas.
* Arrastra los bloques para reordenar la salida.
* Configura cada bloque inline. Por ejemplo, un **Variable** necesita fuente y campo, mientras que un **Conditional** necesita una condición.
* Usa **Inline** cuando el bloque deba renderizarse sin un salto de línea después.
* Usa **Trim whitespace** para eliminar espacios extra alrededor de la salida del bloque.
* Usa **Duplicate** para copiar un bloque configurado.
* Usa **Delete** para quitar un bloque del Template.
Los bloques contenedores como **Loop**, **Conditional**, **Section** y **With** pueden contener bloques hijos. Úsalos cuando la salida necesite contenido repetido o agrupado.
## Resultado esperado
***
Tras guardar, el Template aparece en la página **Templates** y puede seleccionarse en el wizard **Generate Report**. También puedes descargar el archivo `.tpl` generado desde el builder.
## Errores comunes y puntos de atención
***
La barra lateral solo muestra Data Sources configurados. Si la fuente interna esperada no aparece, confirma la configuración con el administrador de Reporter. Si el informe necesita una base de datos externa, añade y prueba ese Data Source antes de usar campos de base de datos en el Template.
El builder valida los bloques al guardar. Si a un bloque le falta una fuente, campo, condición o expresión, corrige ese bloque antes de guardar.
Los bloques del Template definen la estructura del archivo. Los filtros de Report se seleccionan más tarde durante la generación y deciden qué registros entran en la salida.
La salida PDF se genera a partir de HTML. Construye el Template como contenido compatible con HTML cuando el formato final sea PDF.
## Pasos siguientes
***
* Usa [Generar un Report](/es/lerian-console/reporter-console/generating-a-report) para probar el Template con filtros reales.
* Usa [Actualizar un Template](/es/lerian-console/reporter-console/updating-a-template) para editar el Template más tarde.
* Usa [Añadir un Template](/es/lerian-console/reporter-console/adding-template) si necesitas subir un archivo `.tpl` preparado en su lugar.
No existe un endpoint de API separado para el builder visual. Usa el [Endpoint Upload template](/es/reference/reporter/upload-template) con un archivo `.tpl` preparado.