.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
.tplgenerado tras construirlo.
.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
Nombra el Template
Edita el nombre del Template en el encabezado. Usa un nombre que los operadores puedan identificar al generar el informe.
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.
Añade bloques al canvas
Usa la barra de bloques para añadir estructura. Los bloques comunes son Text, Variable, Loop, Conditional y Aggregation.
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.
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.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 (opcional), 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.
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
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
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
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
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
.tplpreparado en su lugar.