Referencia de configuración YAML

Guía completa para editar manualmente el archivo template.yaml, cubriendo diseño, mapeo y lógica.

Esta guía está dirigida a usuarios avanzados y desarrolladores que deseen editar el archivo template.yaml directamente. Este archivo actúa como la "Fuente Única de Verdad" para su perfil, definiendo el diseño del PDF, el mapeo de datos y la lógica de cálculos.

Ubicación del archivo

El archivo de configuración se encuentra en el directorio de su perfil dentro del espacio de trabajo:

Documents/PDFMailEngine_Workspace/Profiles/<NombreDeSuPerfil>/template.yaml

La ubicación predeterminada del espacio de trabajo es la carpeta PDFMailEngine_Workspace dentro de su directorio de Documentos. Puede cambiar la ubicación del espacio de trabajo desde la configuración de la aplicación.

1. Configuración PAGE (Lienzo)

Define las propiedades físicas del lienzo del PDF.

size: Tamaños estándar (A3, A4, A5, B4, B5, LETTER, LEGAL).
orientation: PORTRAIT o LANDSCAPE.
margins: Márgenes globales en milímetros.

Gestión manual de recursos

Al agregar PDFs de fondo manualmente en el archivo YAML, la aplicación NO importa automáticamente el archivo a la carpeta de su perfil.

Debe copiar manualmente el archivo .pdf al directorio del perfil.

Ruta predeterminada del diseñador: assets/background/
Recomendado: Use rutas relativas (ej., ./background.pdf o assets/background/bg.pdf).

PAGE:
  size: "A4"
  orientation: "PORTRAIT"
  margins:
    top: 20
    bottom: 20
    left: 20
    right: 20
  background: "assets/background/stationery.pdf" # PDF de fondo opcional

2. FONTS

Registra fuentes TrueType (.ttf) u OpenType (.otf) personalizadas.

Gestión manual de recursos

Debe copiar manualmente el archivo de fuente al directorio del perfil.

Ruta predeterminada del diseñador: assets/fonts/

FONTS:
  # NombreFuente : Ruta Relativa
  "MyCustomFont": "assets/fonts/MyFont-Bold.ttf"
  "CorporateFont": "Corporate-Regular.otf"

3. MAPPING (Enlace de datos)

Mapea los encabezados de columnas de su CSV/Excel a nombres de variables internos usados en la plantilla.

Sintaxis: ClaveInterna: "Encabezado de Columna CSV"

MAPPING:
  # Interno : Externo
  customer_name: "Customer Name"
  invoice_no: "Invoice Number"
  date: "Issue Date"
  amount: "Total Amount"

4. CALCULATIONS

Define cálculos automáticos que se ejecutan durante la ingesta de datos.

Consistencia de sintaxis

Use llaves {{ }} para variables. Para consistencia con los campos de texto, se recomienda envolver los nombres de variables en llaves {{ }}, incluso en fórmulas de cálculo.

Estándar: {{ quantity }} * {{ price }}

scope:
- item: se calcula para cada fila (ej., {{ quantity }} * {{ price }}).
- group: se calcula para un grupo de filas (ej., sum de totales).
expression: Una expresión matemática. Admite funciones math como floor(), ceil(), round().

CALCULATIONS:
  # Cálculo a nivel de fila (ej., Impuesto)
  - scope: "item"
    target: "tax_amount"
    expression: "floor({{ amount }} * 0.10)" # Usar funciones matemáticas

  # Agregar esto para mostrar el origen de total_with_tax
  - scope: "item"
    target: "total_with_tax"
    expression: "{{ amount }} + {{ tax_amount }}"

  # Cálculo a nivel de grupo (Suma de todas las filas de la factura)
  - scope: "group"
    target: "grand_total"
    type: "sum" # 'sum' suma los valores
    field: "total_with_tax"

5. LAYOUT (Elementos)

La lista LAYOUT define cada elemento visual en el PDF. Los elementos se dibujan en orden (los posteriores se dibujan encima).

Sistema de coordenadas

Origen de coordenadas

Las plantillas creadas por el Diseñador usan un sistema de coordenadas con origen en la esquina superior izquierda (Y=0 es la parte superior de la página). Al editar YAML manualmente con la clave PAGE, el sistema de coordenadas predeterminado tiene origen en la esquina inferior izquierda (Y=0 es la parte inferior de la página).

El sistema de coordenadas se determina automáticamente: las plantillas que usan la clave canvas (formato del Diseñador) usan el origen superior izquierdo, mientras que las que usan la clave PAGE usan el origen inferior izquierdo.

Propiedades comunes

La mayoría de los elementos admiten estas propiedades:

x, y: Posición en milímetros.
visible: Una expresión de condición que controla si el elemento se renderiza (ver más abajo).
position: absolute (predeterminado) o relative.

La propiedad `visible`

La propiedad visible acepta una expresión Python que se evalúa contra la fila de datos actual. Si la expresión se evalúa como False (o un valor falso), el elemento se oculta.

Funciones integradas disponibles: int(), float(), str(), len()

# Mostrar solo cuando el monto es positivo
- type: "text"
  value: "Total: {{ amount }}"
  visible: "{{ amount }} > 0"
  x: 20
  y: 250

# Mostrar solo cuando un campo no está vacío
- type: "text"
  value: "Nota: {{ note }}"
  visible: "len(str({{ note }})) > 0"
  x: 20
  y: 240

# Combinar múltiples condiciones
- type: "text"
  value: "Descuento Aplicado"
  visible: "{{ discount_rate }} > 0 and {{ amount }} >= 10000"
  x: 20
  y: 230

Text

Muestra texto estático o variables dinámicas usando sintaxis Jinja2 {{ key }}.

- type: "text"
  value: "Factura #{{ invoice_no }}" # Dinámico
  x: 20
  y: 250
  font_family: "Helvetica"
  font_size: 12
  font_weight: "bold"
  align: "LEFT" # LEFT, CENTER, RIGHT
  color: "#000000"
  opacity: 1.0

Image

Incrusta un archivo de imagen.

Gestión manual de recursos

Debe copiar manualmente el archivo de imagen al directorio del perfil.

Ruta predeterminada del diseñador: assets/images/

- type: "image"
  path: "assets/images/logo.png"
  x: 150
  y: 260
  width: 40
  height: 20

Group Table (Dinámica)

Renderiza una tabla dinámica que itera sobre las filas de datos (Detalle/Líneas de artículos).

- type: "group_table"
  x: 20
  y: 180
  # Estilos globales
  header_height: 8
  row_height: 6
  border_color: "#000000"
  grid_color: "#cccccc"
  alt_row_color: "#f0f0f0" # Filas alternadas

  columns:
    - header: "Artículo"
      key: "item_name"
      width: 60
      align: "LEFT"

    - header: "Precio"
      key: "unit_price"
      width: 30
      align: "RIGHT"
      format: "currency" # Formato con separadores

Static Table (Fija)

Renderiza una cuadrícula fija donde define las filas manualmente. Útil para pies de página, datos bancarios o bloques de firma.

- type: "static_table"
  x: 20
  y: 50
  width: 170 # Opcional. Se infiere de la suma de anchos de columnas si no se especifica

  columns:
    - width: 30
      header: "Etiqueta"
    - width: 140
      header: "Valor"

  # Filas definidas manualmente
  rows:
    - ["Banco", "Mizuho Bank"]
    - ["N° Cuenta", "{{ account_number }}"] # Puede usar variables
    - ["Nota", "Por favor pague en un plazo de 30 días"]

Barcode

Genera un código de barras 1D.

Tipos compatibles: CODE128, JAN (EAN13 mixto), EAN13, EAN8, CODE39, UPCA, NW-7 (Codabar), ITF.

- type: "barcode"
  value: "{{ invoice_no }}"
  x: 20
  y: 20
  width: 50        # Ancho máximo (se reduce si es necesario)
  height: 10       # Altura total

  barcode_type: "CODE128"
  bar_width: 1.0   # Grosor de las barras
  bar_height: 10   # Altura de las barras

  # Texto legible
  human_readable: true
  hr_font: "Helvetica"
  hr_size: 10
  hr_color: "#000000"

QR Code

Genera un código QR 2D.

Niveles de corrección de errores: L (7%), M (15%), Q (25%), H (30%).

- type: "qrcode"
  value: "https://example.com/inv/{{ invoice_no }}"
  x: 150
  y: 20
  width: 20       # Tamaño (relación de aspecto fija)

  qr_error_level: "M"
  qr_quiet_zone: true   # Incluir margen blanco

  color: "#000000"      # Primer plano
  back_color: "#ffffff" # Fondo
  opacity: 1.0

Shapes (Rect / Line)

Solo edición manual de YAML

Los elementos de forma (rect y line) no se pueden agregar a través de la interfaz del diseñador. Solo están disponibles al editar el archivo YAML directamente.

Propiedades de Rect:

x, y: Posición en milímetros.
width, height: Dimensiones en milímetros.
stroke_color: Color del borde (hex, ej., "#000000").
fill_color: Color de relleno (hex, ej., "#f0f0f0"). Omita para sin relleno.
stroke_width: Grosor del borde en puntos (predeterminado: 1).
opacity: Opacidad de 0.0 (transparente) a 1.0 (opaco).

Propiedades de Line: Una línea se dibuja como un rectángulo con height: 0 (horizontal) o width: 0 (vertical).

x, y: Posición inicial en milímetros.
width: Longitud de una línea horizontal.
height: Longitud de una línea vertical. Establezca en 0 para líneas horizontales.
stroke_color: Color de la línea (hex).
stroke_width: Grosor de la línea en puntos.

# Rectángulo con borde y relleno
- type: "rect"
  x: 10
  y: 100
  width: 190
  height: 50
  stroke_color: "#000000"
  fill_color: "#f0f0f0"
  stroke_width: 1

# Línea horizontal
- type: "line"
  x: 10
  y: 200
  width: 190
  height: 0
  stroke_width: 2
  stroke_color: "#000000"

Referencia de configuración YAML

Ubicación del archivo

1. Configuración PAGE (Lienzo)

Gestión manual de recursos

2. FONTS

Gestión manual de recursos

3. MAPPING (Enlace de datos)

4. CALCULATIONS

Consistencia de sintaxis

5. LAYOUT (Elementos)

Sistema de coordenadas

Origen de coordenadas

Propiedades comunes

La propiedad visible

Text

Image

Gestión manual de recursos

Group Table (Dinámica)

Static Table (Fija)

Barcode

QR Code

Shapes (Rect / Line)

Solo edición manual de YAML

La propiedad `visible`