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

---

1. Abre el builder

   Ve a la página Templates y haz clic en Template Builder.

2. Nombra el Template

   Edita el nombre del Template en el encabezado. Usa un nombre que los operadores puedan identificar al generar el informe.

3. Elige el formato de salida

   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.

4. Añade bloques al canvas

   Usa la barra de bloques para añadir estructura. Los bloques comunes son Text, Variable, Loop, Conditional y Aggregation.

5. Conecta campos desde Data Sources

   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.

6. Revisa el código generado cuando sea necesario

   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.

7. Guarda el Template

   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

---

No aparecen Data Sources en la barra lateral

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.

Faltan campos obligatorios en los bloques

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.

Usar filtros en la parte incorrecta del flujo

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.

Elegir PDF sin entender el código generado

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 para probar el Template con filtros reales.
• Usa Actualizar un Template para editar el Template más tarde.
• Usa Añadir un Template si necesitas subir un archivo .tpl preparado en su lugar.

API equivalente

No existe un endpoint de API separado para el builder visual. Usa el Endpoint Upload template con un archivo .tpl preparado.