Diccionario de Llaves JSON para Plantillas PDF

Las plantillas de reportes en Axol Systems se definen mediante documentos estructurados en formato JSON organizados bajo un patrón de árbol de componentes. Cada nodo representa un componente visual o contenedor que el motor de renderizado convierte en elementos de documento PDF.

1. Estructura Raíz del Documento

Toda plantilla de PDF contiene una estructura principal con las siguientes llaves raíz:

{
  "themeFont": "roboto",
  "header": { ... },
  "body": [
    { ... },
    { ... }
  ],
  "footer": { ... }
}

Llave	Tipo	Requerido	Descripción
`themeFont`	Texto	Opcional	Fuente tipográfica global para el documento. Valor por defecto: `"roboto"`.
`header`	Objeto Widget	Opcional	Widget contenedor que se renderizará automáticamente en la parte superior de cada página.
`body`	Lista de Widgets	Sí	Arreglo secuencial de widgets principales que conforman el cuerpo del reporte.
`footer`	Objeto Widget	Opcional	Widget contenedor que se renderizará automáticamente al pie de cada página.

2. Llaves Estructurales de Componentes

Cada elemento dentro de header, body o footer es un nodo de widget que comparte las siguientes llaves fundamentales:

{
  "type": "column",
  "attributes": { ... },
  "children": [ ... ]
}

type (Texto, Requerido): Especifica el tipo de componente a construir ("text", "row", "column", "container", "table", "divider", "repeat", "image", etc.).
attributes (Objeto, Opcional): Diccionario con las propiedades visuales, dimensiones, espaciados y configuraciones específicas del widget.
child (Objeto, Opcional): Se utiliza en widgets que envuelven a un solo hijo (ej. container, center, expanded, sizedBox, repeat).
children (Lista de Objetos, Opcional): Se utiliza en widgets contenedores que agrupan múltiples hijos en una dirección (ej. column, row).

3. Catálogo de Widgets y sus Atributos

`text`

Renderiza una cadena de texto simple o formateada en el documento.

{
  "type": "text",
  "attributes": {
    "text": "Factura N°: {{t0c1}}",
    "textAlign": "start",
    "textDirection": "ltr",
    "maxLines": 2,
    "overflow": "clip",
    "style": {
      "fontSize": 12.0,
      "fontWeight": "bold",
      "color": "0xff000000"
    }
  }
}

Atributos de `text`:

text (Texto): Contenido a mostrar. Permite la inyección dinámica de propiedades con {{columna}} y operadores especiales (ver sección de inyección).
style (Objeto): Configuración tipográfica (ver objeto TextStyle).
textAlign (Texto): Alineación horizontal del texto ("start", "center", "end", "left", "right", "justify").
textDirection (Texto): Dirección de lectura ("ltr" para izquierda a derecha, "rtl" para derecha a izquierda).
maxLines (Entero): Número máximo de líneas antes de truncar o cortar el texto.
overflow (Texto): Comportamiento al exceder el espacio disponible ("clip", "span", "visible").

`table`

Genera una cuadrícula o tabla de datos paginada automáticamente a partir de una lista de objetos o sub-tabla vinculada (ObjectList).

{
  "type": "table",
  "attributes": {
    "dataColumn": "t0c5",
    "headerHeight": 25.0,
    "cellHeight": 20.0,
    "columns": [
      {
        "column": "t1c1",
        "alterName": "Código",
        "width": 80.0
      },
      {
        "column": "t1c2",
        "alterName": "Descripción"
      },
      {
        "column": "t1c3",
        "alterName": "Precio",
        "format": "money",
        "width": 100.0
      }
    ],
    "columnWidths": {
      "1": 220.0
    },
    "cellAlignments": {
      "0": "center",
      "1": "centerLeft",
      "2": "centerRight"
    },
    "headerStyle": {
      "fontSize": 10.0,
      "fontWeight": "bold",
      "color": "0xffffffff"
    },
    "cellStyle": {
      "fontSize": 9.0
    },
    "headerDecoration": {
      "color": "0xff2A2D34"
    },
    "tableBorder": {
      "horizontalInside": { "width": 0.5, "color": "0xffE0E0E0", "style": "solid" }
    }
  }
}

Atributos de `table`:

dataColumn (Texto, Requerido): Identificador de la columna del objeto principal que almacena la lista de objetos o partidas.
columns (Lista de Objetos, Requerido): Definición de las columnas visibles:
- column: Nombre físico de la propiedad en la tabla hija (ej. "t1c1").
- alterName (Opcional): Título personalizado para el encabezado. Si se omite, se usa el nombre de la propiedad. También puede usarse la sintaxis corta "t1c1|Nombre Alterno".
- format (Opcional): Formato especial del valor. Opciones disponibles:
  - "money": Formatea números como moneda ($1,234.50).
  - "ddmmyyyy": Formatea fechas como día/mes/año (25/12/2026).
- width (Número, Opcional): Ancho fijo en puntos para esa columna individual.
columnWidths (Mapa, Opcional): Permite asignar anchos fijos indexados por columna ("0", "1", etc.). Si una columna tiene width individual y también figura en columnWidths, este último tiene precedencia.
headerHeight (Número): Alto fijo de la fila de encabezado.
cellHeight (Número): Alto mínimo para las filas de datos.
cellAlignments (Mapa): Alineación del contenido por columna según su índice base cero ("0": "center", "1": "centerLeft").
headerStyle / cellStyle (Objeto TextStyle): Estilos tipográficos para el encabezado y celdas.
headerDecoration (Objeto BoxDecoration): Fondo y bordes de la fila de encabezado.
tableBorder (Objeto): Configuración de bordes de la tabla (top, bottom, left, right, verticalInside, horizontalInside).

`repeat`

Duplica su widget hijo tantas veces como se indique en times. Es la herramienta ideal para formatos que requieren varias copias idénticas en una misma hoja (como pagarés, vales o acuses de recibo).

{
  "type": "repeat",
  "attributes": {
    "times": 2,
    "itemHeight": 350.0,
    "gap": 16.0,
    "divider": {
      "type": "divider",
      "attributes": {
        "style": "dashed",
        "thickness": 0.8,
        "color": "0xff888888"
      }
    }
  },
  "child": { ... }
}

times (Entero): Cantidad de repeticiones del bloque.
itemHeight (Número, Opcional): Alto reservado para cada copia. Si no cabe en la hoja actual, salta automáticamente a la siguiente.
gap (Número, Opcional): Espacio vertical de separación entre copias consecutivas.
divider (Objeto, Opcional): Widget o atributos de línea separadora (ej. línea punteada para recortar).

`column` y `row`

Organizan widgets secundarios en sentido vertical (column) u horizontal (row).

{
  "type": "row",
  "attributes": {
    "mainAxisAlignment": "spaceBetween",
    "crossAxisAlignment": "center",
    "mainAxisSize": "max"
  },
  "children": [
    { ... },
    { ... }
  ]
}

mainAxisAlignment: Alineación en el eje principal.
- Opciones: "start" (defecto), "center", "end", "spaceBetween".
crossAxisAlignment: Alineación en el eje perpendicular.
- Opciones: "start" (defecto), "center", "end", "stretch".
mainAxisSize: Tamaño del contenedor en el eje principal ("max" o "min").
verticalDirection: Sentido de apilamiento ("down" o "up").

`container`

Caja de diseño para envolver a un hijo, agregando relleno interior (padding), márgenes, fondos decorativos y dimensiones fijas.

{
  "type": "container",
  "attributes": {
    "width": 200.0,
    "height": 50.0,
    "alignment": "center",
    "padding": {
      "left": 8.0,
      "top": 4.0,
      "right": 8.0,
      "bottom": 4.0
    },
    "decoration": {
      "color": "0xffF4F5F7",
      "borderRadius": {
        "topLeft": 4.0,
        "topRight": 4.0,
        "bottomLeft": 4.0,
        "bottomRight": 4.0
      }
    }
  },
  "child": { ... }
}

width / height (Número): Dimensiones exactas del contenedor.
alignment (Texto): Alineación del widget interno dentro del contenedor ("center", "topLeft", "centerLeft", etc.).
padding (Objeto): Espaciado interior con llaves top, bottom, left, right.
decoration (Objeto BoxDecoration): Estilo del contenedor (color de fondo, bordes y esquinas redondeadas).

`divider` y `verticalDivider`

Líneas de separación visual horizontal (divider) o vertical (verticalDivider).

{
  "type": "divider",
  "attributes": {
    "thickness": 1.0,
    "height": 15.0,
    "color": "0xffCCCCCC",
    "style": "solid",
    "indent": 10.0,
    "endIndent": 10.0
  }
}

thickness (Número): Grosor de la línea en puntos.
height (en divider) / width (en verticalDivider): Espacio total ocupado por el separador.
color (Texto Hexadecimal): Color de la línea.
style (Texto): "solid", "dashed", "dotted", "none".
indent / endIndent (Número): Margen al inicio o al final de la línea.

`image`

Inserta una imagen (como logos o firmas) dentro del documento.

{
  "type": "image",
  "attributes": {
    "image": "{{img:logo_empresa}}",
    "width": 120.0,
    "height": 50.0
  }
}

image (Texto): Nombre o identificador de la imagen precedido por el tag de inyección {{img:nombre}}.
width / height (Número): Dimensiones visuales para la imagen.

`center`, `expanded` y `sizedBox`

center: Centra a su hijo horizontal y verticalmente dentro del espacio asignado.
expanded: Hace que un hijo dentro de una row o column ocupe todo el espacio sobrante disponible ("flex": 1.0, "fit": "tight").
sizedBox: Caja invisible para forzar una separación fija en blanco ("width": 10.0, "height": 20.0).

4. Objetos de Estilo y Decoración

`TextStyle`

Define la apariencia del texto:

{
  "fontSize": 12.0,
  "color": "0xff000000",
  "font": "helvetica",
  "fontWeight": "bold",
  "fontStyle": "italic",
  "height": 1.2,
  "lineSpacing": 2.0,
  "letterSpacing": 0.5,
  "decoration": "underline",
  "decorationColor": "0xff0000FF"
}

fontSize (Número): Tamaño de la letra en puntos.
color (Texto Hexadecimal): Color del texto (0xffRRGGBB).
font (Texto): Familia tipográfica ("roboto", "helvetica", "times", "courier").
fontWeight (Texto): "normal" o "bold".
fontStyle (Texto): "normal" o "italic".
height (Número): Multiplicador del tamaño de línea (interlineado = fontSize * height).
lineSpacing (Número): Espacio vertical adicional fijo entre líneas sucesivas.
letterSpacing / wordSpacing (Número): Espacio adicional entre caracteres o palabras.
decoration (Texto): Línea decorativa ("none", "underline", "overline", "lineThrough").

`BoxDecoration`

Define el fondo y el contorno de contenedores o celdas de tablas:

{
  "color": "0xffFFFFFF",
  "border": {
    "top": { "width": 1.0, "color": "0xff000000", "style": "solid" },
    "bottom": { "width": 1.0, "color": "0xff000000", "style": "solid" }
  },
  "borderRadius": {
    "topLeft": 6.0,
    "topRight": 6.0,
    "bottomLeft": 6.0,
    "bottomRight": 6.0
  }
}

5. Inyección Dinámica de Datos y Operadores

En cualquier texto o atributo que soporte cadenas, puedes intercalar datos vivos del registro que se está exportando:

1. Inyección de Propiedad: `{{columna}}`

Sustituye la etiqueta por el valor que tiene esa columna en el objeto seleccionado.

Ejemplo: "Cliente: {{t0c2}}" $\rightarrow$ "Cliente: Distribuidora del Norte"

2. Concatenación Dinámica: `{{join:col1,col2,...;separador}}`

Concatena de forma inteligente múltiples campos utilizando el separador indicado, omitiendo automáticamente aquellos que se encuentren vacíos o nulos.

Sintaxis: {{join:columna1,columna2,columna3; separador}}
Ejemplo: "Dirección: {{join:calle,numero,colonia; / }}"
Resultado: Si el número está vacío, genera "Dirección: Av. Juárez / Centro" sin dobles diagonales.

3. Número de Página: `{{page}}`

Inserta automáticamente el número de página actual. Ideal para colocarse dentro del bloque footer.

Ejemplo: "Página {{page}}"

6. Mapeo de Enums y Formato de Colores

Colores (Notación Hexadecimal)

Los colores se expresan como cadenas de texto con el formato hexadecimal de 32 bits con prefijo 0x seguido del canal Alfa (opacidad) y los canales RGB: 0xAARRGGBB.

"0xff000000": Negro completamente opaco.
"0xffffffff": Blanco completamente opaco.
"0xff2A2D34": Gris grafito oscuro.
"0x80000000": Negro con 50% de transparencia.

Alineaciones Geométricas (`alignment`)

"topLeft", "topCenter", "topRight"
"centerLeft", "center", "centerRight"
"bottomLeft", "bottomCenter", "bottomRight"

Diccionario de Llaves JSON para Plantillas PDF

1. Estructura Raíz del Documento

2. Llaves Estructurales de Componentes

3. Catálogo de Widgets y sus Atributos

text

Atributos de text:

table

Atributos de table:

repeat

column y row

container

divider y verticalDivider

image

center, expanded y sizedBox