Configurazione YAML

Guida completa per la modifica manuale del file template.yaml: layout, mappatura e logica.

Questa guida è destinata a utenti avanzati e sviluppatori che desiderano modificare direttamente il file template.yaml. Questo file funge da "unica fonte di verità" per il profilo, definendo il layout PDF, la mappatura dati e la logica di calcolo.

Posizione del file

Il file di configurazione si trova nella directory del profilo all'interno del workspace:

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

La posizione predefinita del workspace è la cartella PDFMailEngine_Workspace nella directory Documenti. È possibile modificare la posizione del workspace dalle impostazioni dell'applicazione.

1. Configurazione PAGE (Canvas)

Definisce le proprietà fisiche del canvas PDF.

size: Dimensioni standard (A3, A4, A5, B4, B5, LETTER, LEGAL).
orientation: PORTRAIT o LANDSCAPE.
margins: Margini globali in millimetri.

Gestione manuale degli asset

Quando si aggiungono PDF di sfondo manualmente nel file YAML, l'applicazione NON importa automaticamente il file nella cartella del profilo.

È necessario copiare manualmente il file .pdf nella directory del profilo.

Percorso predefinito del Designer: assets/background/
Consigliato: Utilizzare percorsi relativi (es. ./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 di sfondo opzionale

2. FONTS

Registra font TrueType (.ttf) o OpenType (.otf) personalizzati.

Gestione manuale degli asset

È necessario copiare manualmente il file del font nella directory del profilo.

Percorso predefinito del Designer: assets/fonts/

FONTS:
  # NomeFont : Percorso relativo
  "MyCustomFont": "assets/fonts/MyFont-Bold.ttf"
  "CorporateFont": "Corporate-Regular.otf"

3. MAPPING (associazione dati)

Mappa le intestazioni delle colonne CSV/Excel ai nomi delle variabili interne utilizzate nel modello.

Sintassi: ChiaveInterna: "Intestazione Colonna CSV"

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

4. CALCULATIONS

Definisce i calcoli automatici da eseguire durante l'acquisizione dei dati.

Coerenza della sintassi

Utilizzare le parentesi {{ }} per le variabili. Per coerenza con i campi di testo, si raccomanda di racchiudere i nomi delle variabili tra {{ }}, anche nelle formule di calcolo.

Standard: {{ quantity }} * {{ price }}

scope:
- item: calcolato per ogni riga (es. {{ quantity }} * {{ price }}).
- group: calcolato per un gruppo di righe (es. sum dei totali).
expression: Un'espressione matematica. Supporta funzioni math come floor(), ceil(), round().

CALCULATIONS:
  # Calcolo a livello di riga (es. IVA)
  - scope: "item"
    target: "tax_amount"
    expression: "floor({{ amount }} * 0.10)" # Utilizza funzioni math

  # Aggiunto per mostrare la provenienza di total_with_tax
  - scope: "item"
    target: "total_with_tax"
    expression: "{{ amount }} + {{ tax_amount }}"

  # Calcolo a livello di gruppo (somma di tutte le righe della fattura)
  - scope: "group"
    target: "grand_total"
    type: "sum" # 'sum' somma i valori
    field: "total_with_tax"

5. LAYOUT (elementi)

L'elenco LAYOUT definisce ogni elemento visivo sul PDF. Gli elementi vengono disegnati in ordine (gli elementi successivi vengono disegnati sopra).

Sistema di coordinate

Origine delle coordinate

I modelli creati dal Designer utilizzano un sistema di coordinate con origine in alto a sinistra (Y=0 è la parte superiore della pagina). Quando si modifica il YAML manualmente con la chiave PAGE, il sistema di coordinate predefinito è con origine in basso a sinistra (Y=0 è la parte inferiore della pagina).

Il sistema di coordinate viene determinato automaticamente: i modelli che utilizzano la chiave canvas (formato Designer) usano l'origine in alto a sinistra, mentre quelli con la chiave PAGE usano l'origine in basso a sinistra.

Proprietà comuni

La maggior parte degli elementi supporta queste proprietà:

x, y: Posizione in millimetri.
visible: Un'espressione condizionale che controlla se l'elemento viene renderizzato (veda sotto).
position: absolute (predefinito) o relative.

La proprietà `visible`

La proprietà visible accetta un'espressione Python valutata rispetto alla riga dati corrente. Se l'espressione restituisce False (o un valore falso), l'elemento viene nascosto.

Funzioni integrate disponibili: int(), float(), str(), len()

# Mostra solo quando l'importo è positivo
- type: "text"
  value: "Totale: {{ amount }}"
  visible: "{{ amount }} > 0"
  x: 20
  y: 250

# Mostra solo quando un campo non è vuoto
- type: "text"
  value: "Nota: {{ note }}"
  visible: "len(str({{ note }})) > 0"
  x: 20
  y: 240

# Combinazione di condizioni multiple
- type: "text"
  value: "Sconto Applicato"
  visible: "{{ discount_rate }} > 0 and {{ amount }} >= 10000"
  x: 20
  y: 230

Text (Testo)

Visualizza testo statico o variabili dinamiche utilizzando la sintassi Jinja2 {{ key }}.

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

Image (Immagine)

Incorpora un file immagine.

Gestione manuale degli asset

È necessario copiare manualmente il file immagine nella directory del profilo.

Percorso predefinito del Designer: assets/images/

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

Group Table (tabella di dettaglio)

Renderizza una tabella dinamica che itera sulle righe dati (dettagli/voci).

- type: "group_table"
  x: 20
  y: 180
  # Stili globali
  header_height: 8
  row_height: 6
  border_color: "#000000"
  grid_color: "#cccccc"
  alt_row_color: "#f0f0f0" # Righe alternate

  columns:
    - header: "Item"
      key: "item_name"
      width: 60
      align: "LEFT"

    - header: "Price"
      key: "unit_price"
      width: 30
      align: "RIGHT"
      format: "currency" # Formattazione con separatori

Static Table (tabella statica)

Renderizza una griglia fissa dove le righe vengono definite manualmente. Utile per piè di pagina, coordinate bancarie o blocchi firma.

- type: "static_table"
  x: 20
  y: 50
  width: 170 # Opzionale. Inferito dalla somma delle larghezze delle colonne se non specificato

  columns:
    - width: 30
      header: "Label"
    - width: 140
      header: "Value"

  # Righe definite manualmente
  rows:
    - ["Banca", "Banca Intesa"]
    - ["N. Conto", "{{ account_number }}"] # Variabili utilizzabili
    - ["Nota", "Pagamento entro 30 giorni"]

Barcode (codice a barre)

Genera un codice a barre 1D.

Tipi supportati: CODE128, JAN (EAN13 misto), EAN13, EAN8, CODE39, UPCA, NW-7 (Codabar), ITF.

- type: "barcode"
  value: "{{ invoice_no }}"
  x: 20
  y: 20
  width: 50        # Larghezza massima (ridimensionata se necessario)
  height: 10       # Altezza totale

  barcode_type: "CODE128"
  bar_width: 1.0   # Spessore delle barre
  bar_height: 10   # Altezza delle barre

  # Testo leggibile
  human_readable: true
  hr_font: "Helvetica"
  hr_size: 10
  hr_color: "#000000"

QR Code (codice QR)

Genera un codice QR 2D.

Livelli di correzione errore: L (7%), M (15%), Q (25%), H (30%).

- type: "qrcode"
  value: "https://example.com/inv/{{ invoice_no }}"
  x: 150
  y: 20
  width: 20       # Dimensione (rapporto d'aspetto fisso)

  qr_error_level: "M"
  qr_quiet_zone: true   # Include margine bianco

  color: "#000000"      # Primo piano
  back_color: "#ffffff" # Sfondo
  opacity: 1.0

Shapes (forme - Rect / Line)

Solo modifica YAML manuale

Gli elementi forma (rect e line) non possono essere aggiunti tramite l'interfaccia Designer. Sono disponibili solo quando si modifica direttamente il file YAML.

Proprietà Rect (rettangolo):

x, y: Posizione in millimetri.
width, height: Dimensioni in millimetri.
stroke_color: Colore del bordo (esadecimale, es. "#000000").
fill_color: Colore di riempimento (esadecimale, es. "#f0f0f0"). Omettere per nessun riempimento.
stroke_width: Spessore del bordo in punti (predefinito: 1).
opacity: Opacità da 0.0 (trasparente) a 1.0 (opaco).

Proprietà Line (linea): Una linea viene disegnata come rettangolo con height: 0 (orizzontale) o width: 0 (verticale).

x, y: Posizione iniziale in millimetri.
width: Lunghezza di una linea orizzontale.
height: Lunghezza di una linea verticale. Impostare a 0 per linee orizzontali.
stroke_color: Colore della linea (esadecimale).
stroke_width: Spessore della linea in punti.

# Rettangolo con bordo e riempimento
- type: "rect"
  x: 10
  y: 100
  width: 190
  height: 50
  stroke_color: "#000000"
  fill_color: "#f0f0f0"
  stroke_width: 1

# Linea orizzontale
- type: "line"
  x: 10
  y: 200
  width: 190
  height: 0
  stroke_width: 2
  stroke_color: "#000000"

Configurazione YAML

Posizione del file

1. Configurazione PAGE (Canvas)

Gestione manuale degli asset

2. FONTS

Gestione manuale degli asset

3. MAPPING (associazione dati)

4. CALCULATIONS

Coerenza della sintassi

5. LAYOUT (elementi)

Sistema di coordinate

Origine delle coordinate

Proprietà comuni

La proprietà visible

Text (Testo)

Image (Immagine)

Gestione manuale degli asset

Group Table (tabella di dettaglio)

Static Table (tabella statica)

Barcode (codice a barre)

QR Code (codice QR)

Shapes (forme - Rect / Line)

Solo modifica YAML manuale

La proprietà `visible`