> ## 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 Template Builder
> Crea plantillas de informes de forma visual ensamblando bloques en lugar de escribir código .tpl manualmente.
Usa Template Builder para crear o mantener una plantilla de forma visual. El constructor convierte los bloques en código `.tpl`, de modo que los operadores puedan definir la estructura del informe sin escribir manualmente el archivo de la plantilla.
## Objetivo
***
Construye una plantilla a partir de bloques visuales y guárdala para la futura generación de informes.
Por ejemplo, una plantilla de transacciones mensuales puede usar texto fijo para el encabezado y un **Loop** para cada fila de transacción. También puede usar bloques **Variable** para campos como el monto y la fecha, y un bloque **Aggregation** para el total.
## Cuándo usarlo
***
Usa Template Builder cuando:
* los operadores necesitan crear una plantilla sin editar código `.tpl`.
* una plantilla de Template Builder necesita mantenimiento visual.
* la estructura del informe depende de campos, bucles, condiciones o totales de una fuente de datos.
* el equipo quiere descargar el archivo `.tpl` generado después de construirlo.
Usa la carga de `.tpl` en su lugar cuando un equipo técnico ya creó y revisó la plantilla fuera de la Console.
## Antes de empezar
***
Confirma:
* existe al menos una fuente de datos relevante si la plantilla necesita campos de base de datos. Puede ser una fuente interna ya configurada para el entorno o una fuente externa agregada desde **Data Sources**.
* probaste la fuente de datos cuando el estado de la conexión o la visibilidad del esquema son inciertos. Sus tablas y campos quedan entonces disponibles en la barra lateral.
* conoces el formato de salida esperado: XML, HTML, CSV, TXT o PDF.
* el operador conoce la estructura del informe, como el encabezado obligatorio, las filas, los totales o las secciones condicionales.
Los bloques definen la estructura de salida. Los filtros aplicados durante la generación del informe 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 de la plantilla en el encabezado. Usa un nombre que los operadores puedan identificar durante la generación del informe.
Selecciona XML, HTML, CSV, TXT o PDF.
Cuando seleccionas **PDF**, el código de plantilla generado usa formato HTML. El código se convierte a PDF durante la generación del informe.
Usa la barra de herramientas de bloques para agregar estructura. Los bloques comunes son **Text**, **Variable**, **Loop**, **Conditional** y **Aggregation**.
Usa la barra lateral de Data Sources para explorar esquemas, tablas y campos. Haz clic en un campo para agregar un bloque **Variable** para ese campo.
Cambia de **Visual** a **Code** para inspeccionar la vista previa del `.tpl` generado. La vista de código es para revisión y copia/descarga, no para edición manual.
Haz clic en **Save**. El constructor valida los campos de bloque obligatorios, genera el código `.tpl` y guarda la plantilla.
## Guía de campos
***
### Campos y controles del constructor
| Campo o control | Qué hace | Ejemplo |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| **Template name** | Nombre obligatorio en el encabezado del constructor. Se asigna a `name` y se convierte en la etiqueta guardada de la plantilla y en el prefijo del nombre de 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 la plantilla. Estado técnico: `viewMode = visual`. | Usar mientras se organizan los bloques |
| **Code** | Vista previa de 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 una nueva plantilla. | `monthly-transaction-csv.tpl` |
| **Save** | Valida los bloques, genera el código `.tpl` y sube o actualiza la plantilla. Requiere un nombre no vacío y al menos un bloque. | Guardar después de que los bloques sean válidos |
### Guía de campos de bloques
| Bloque | Campos por configurar | Efecto |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Text** | **Content** (`content`) | Renderiza texto fijo, como encabezados CSV, etiquetas XML o fragmentos HTML. |
| **Variable** | **Data Source**, **Table**, **Field**, **Index (optional)**, **Filters** (`dataSource`, `table`, `field`, `index`, `filters[]`) | Inserta un valor de campo. Dentro de un **Loop** superior, **Data Source** puede completarse automáticamente desde el iterador del bucle. |
| **Loop** | **Iterator name** y **Iterable source** (`iteratorName`, `iterableSource`) | Repite los bloques hijos sobre una colección. Usa el formato `dataSource.table` para la fuente iterable. |
| **Conditional** | **Condition** y **Include else block** (`condition`, `hasElse`) | Renderiza los 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 de **Last Item by Group** a partir de una colección de origen. |
| **Calculation** | **Expression** (`expression`) | Renderiza un valor calculado. Los operadores admitidos que se muestran en la interfaz incluyen `+`, `-`, `*`, `/`, `**` y `%`. |
| **Date/Time** | **Format** y **Date source** (`format`, `dateSource`) | Da formato a 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** genera uno o más contadores. |
| **Comment** | **Comment** (`commentText`) | Almacena una nota interna de la plantilla y no aparece en el informe final. |
| **Section** | **Section title** (`sectionTitle`) | Agrupa bloques hijos para organizar plantillas 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 en línea, como `item.name\|upper`. |
| **Custom Tag** | **Tag name** y **Tag arguments** (`tagName`, `tagArgs`) | Emite una etiqueta avanzada de plantilla, como `include`, con argumentos como `"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 un encabezado o una etiqueta. |
| **Variable** | Un valor de un campo de la fuente de datos, 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 último elemento por grupo. |
| **Calculation** | Un valor calculado, como `value * 1.05`. |
| **Date/Time** | Un valor de fecha u hora con formato. |
| **Counter** | Un número de fila o valor de secuencia. |
| **Comment** | Nota interna de la plantilla que no aparece en el informe generado. |
| **Section** | Un grupo con nombre de bloques para organizar plantillas más grandes. |
| **With (Assign)** | Una variable reutilizable creada a partir de una expresión. |
| **Expression** | Una expresión en línea renderizada en la salida. |
| **Custom Tag** | Una etiqueta de plantilla personalizada cuando se necesita sintaxis avanzada de plantilla. |
## Trabajar con bloques
***
* Haz clic en un tipo de bloque en la barra de herramientas para agregarlo al lienzo.
* Arrastra los bloques para reordenar la salida.
* Configura cada bloque en línea. Por ejemplo, un **Variable** necesita una fuente y un 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 adicionales alrededor de la salida del bloque.
* Usa **Duplicate** para copiar un bloque configurado.
* Usa **Delete** para eliminar un bloque de la plantilla.
Los bloques contenedores como **Loop**, **Conditional**, **Section** y **With** pueden contener bloques hijos. Úsalos cuando la salida necesite contenido repetido o agrupado.
## Resultado esperado
***
Después de guardar, la plantilla aparece en la página **Templates**. Puedes seleccionarla en el asistente **Generate Report**. También puedes descargar el archivo `.tpl` generado desde el constructor.
## Errores comunes y puntos de atención
***
La barra lateral solo muestra las Data Sources configuradas. 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, agrega y prueba esa fuente de datos antes de usar campos de base de datos en la plantilla.
El constructor valida los bloques durante el guardado. Si un bloque no tiene fuente, campo, condición o expresión, corrige ese bloque antes de guardar.
Los bloques de la plantilla definen la estructura del archivo. Los filtros del informe se seleccionan después, durante la generación del informe. Ellos deciden qué registros entran en la salida.
La salida en PDF proviene de HTML. Construye la plantilla como contenido compatible con HTML cuando el formato de salida final es PDF.
## Próximos pasos
***
* Usa [Genera un informe](/es/products/reporter/console/generating-a-report) para probar la plantilla con filtros reales.
* Usa [Actualizar una plantilla](/es/products/reporter/console/updating-a-template) para editar la plantilla más adelante.
* Usa [Agrega una plantilla](/es/products/reporter/console/adding-template) si necesitas subir en su lugar un archivo `.tpl` preparado.
No existe un endpoint de API separado para el constructor visual. Usa [Endpoint de carga de plantilla](/es/reference/products/reporter/upload-template) con un archivo `.tpl` preparado.