Configuration YAML

Ce guide est destiné aux utilisateurs avancés et développeurs souhaitant éditer directement le fichier template.yaml. Ce fichier constitue la « source unique de vérité » de votre profil, définissant la mise en page PDF, le mappage de données et la logique de calcul.

Emplacement du fichier

Le fichier de configuration se trouve dans le répertoire de votre profil au sein de l'espace de travail :

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

L'emplacement par défaut de l'espace de travail est le dossier PDFMailEngine_Workspace dans votre répertoire Documents. Vous pouvez modifier l'emplacement depuis les paramètres de l'application.

1. Configuration PAGE (Canevas)

Définit les propriétés physiques du canevas PDF.

• size : Tailles standard (A3, A4, A5, B4, B5, LETTER, LEGAL).
• orientation : PORTRAIT ou LANDSCAPE.
• margins : Marges globales en millimètres.

PAGE:
  size: "A4"
  orientation: "PORTRAIT"
  margins:
    top: 20
    bottom: 20
    left: 20
    right: 20
  background: "assets/background/stationery.pdf" # PDF d'arrière-plan optionnel

2. FONTS (Polices)

Enregistre des polices personnalisées TrueType (.ttf) ou OpenType (.otf).

FONTS:
  # NomPolice : Chemin relatif
  "MyCustomFont": "assets/fonts/MyFont-Bold.ttf"
  "CorporateFont": "Corporate-Regular.otf"

3. MAPPING (Liaison de données)

Mappe les en-têtes de colonnes de votre CSV/Excel aux noms de variables internes utilisés dans le modèle.

Syntaxe : CléInterne: "En-tête de colonne CSV"

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

4. CALCULATIONS (Calculs)

Définit les calculs automatiques exécutés lors de l'ingestion des données.

• scope :
  • item : calculé pour chaque ligne (ex : {{ quantity }} * {{ price }}).
  • group : calculé pour un groupe de lignes (ex : sum des totaux).
• expression : Une expression mathématique. Supporte les fonctions math comme floor(), ceil(), round().

CALCULATIONS:
  # Calcul au niveau de la ligne (ex : Taxe)
  - scope: "item"
    target: "tax_amount"
    expression: "floor({{ amount }} * 0.10)" # Utilisation des fonctions math

  # Ajout pour montrer l'origine de total_with_tax
  - scope: "item"
    target: "total_with_tax"
    expression: "{{ amount }} + {{ tax_amount }}"

  # Calcul au niveau du groupe (Somme de toutes les lignes de la facture)
  - scope: "group"
    target: "grand_total"
    type: "sum" # 'sum' additionne les valeurs
    field: "total_with_tax"

5. LAYOUT (Éléments)

La liste LAYOUT définit chaque élément visuel du PDF. Les éléments sont dessinés dans l'ordre (les éléments suivants sont dessinés au-dessus).

Système de coordonnées

Propriétés communes

La plupart des éléments supportent ces propriétés :

• x, y : Position en millimètres.
• visible : Une expression conditionnelle contrôlant l'affichage de l'élément (voir ci-dessous).
• position : absolute (par défaut) ou relative.

La propriété visible

La propriété visible accepte une expression Python évaluée par rapport à la ligne de données courante. Si l'expression est évaluée à False (ou une valeur fausse), l'élément est masqué.

Fonctions intégrées disponibles : int(), float(), str(), len()

# Afficher uniquement si le montant est positif
- type: "text"
  value: "Total : {{ amount }}"
  visible: "{{ amount }} > 0"
  x: 20
  y: 250

# Afficher uniquement si un champ n'est pas vide
- type: "text"
  value: "Note : {{ note }}"
  visible: "len(str({{ note }})) > 0"
  x: 20
  y: 240

# Combiner plusieurs conditions
- type: "text"
  value: "Remise appliquée"
  visible: "{{ discount_rate }} > 0 and {{ amount }} >= 10000"
  x: 20
  y: 230

Text (Texte)

Affiche du texte statique ou des variables dynamiques avec la syntaxe Jinja2 {{ key }}.

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

Image

Intègre un fichier image.

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

Tableau de groupe (Dynamique)

Rend un tableau dynamique qui itère sur vos lignes de données (détails/articles).

- type: "group_table"
  x: 20
  y: 180
  # Styles globaux
  header_height: 8
  row_height: 6
  border_color: "#000000"
  grid_color: "#cccccc"
  alt_row_color: "#f0f0f0" # Bandes alternées

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

    - header: "Prix"
      key: "unit_price"
      width: 30
      align: "RIGHT"
      format: "currency" # Formatage avec séparateurs

Tableau statique (Fixe)

Rend une grille fixe où vous définissez les lignes manuellement. Utile pour les pieds de page, coordonnées bancaires ou blocs de signature.

- type: "static_table"
  x: 20
  y: 50
  width: 170 # Optionnel. Déduit de la somme des largeurs de colonnes si non spécifié

  columns:
    - width: 30
      header: "Libellé"
    - width: 140
      header: "Valeur"

  # Lignes définies manuellement
  rows:
    - ["Banque", "Banque Exemple"]
    - ["N° de compte", "{{ account_number }}"] # Peut utiliser des variables
    - ["Note", "Merci de régler sous 30 jours"]

Code-barres

Génère un code-barres 1D.

Types supportés : CODE128, JAN (EAN13 mixte), EAN13, EAN8, CODE39, UPCA, NW-7 (Codabar), ITF.

- type: "barcode"
  value: "{{ invoice_no }}"
  x: 20
  y: 20
  width: 50        # Largeur max (réduit si nécessaire)
  height: 10       # Hauteur totale

  barcode_type: "CODE128"
  bar_width: 1.0   # Épaisseur des barres
  bar_height: 10   # Hauteur des barres

  # Texte lisible
  human_readable: true
  hr_font: "Helvetica"
  hr_size: 10
  hr_color: "#000000"

QR Code

Génère un QR code 2D.

Niveaux de correction d'erreur : L (7 %), M (15 %), Q (25 %), H (30 %).

- type: "qrcode"
  value: "https://example.com/inv/{{ invoice_no }}"
  x: 150
  y: 20
  width: 20       # Taille (rapport d'aspect fixe)

  qr_error_level: "M"
  qr_quiet_zone: true   # Inclure la marge blanche

  color: "#000000"      # Premier plan
  back_color: "#ffffff" # Arrière-plan
  opacity: 1.0

Formes (Rect / Line)

Propriétés Rect (Rectangle) :

• x, y : Position en millimètres.
• width, height : Dimensions en millimètres.
• stroke_color : Couleur de la bordure (hex, ex : "#000000").
• fill_color : Couleur de remplissage (hex, ex : "#f0f0f0"). Omettre pour aucun remplissage.
• stroke_width : Épaisseur de la bordure en points (par défaut : 1).
• opacity : Opacité de 0.0 (transparent) à 1.0 (opaque).

Propriétés Line (Ligne) : Une ligne est dessinée comme un rectangle avec height: 0 (horizontale) ou width: 0 (verticale).

• x, y : Position de départ en millimètres.
• width : Longueur d'une ligne horizontale.
• height : Longueur d'une ligne verticale. Mettre à 0 pour les lignes horizontales.
• stroke_color : Couleur de la ligne (hex).
• stroke_width : Épaisseur de la ligne en points.

# Rectangle avec bordure et remplissage
- type: "rect"
  x: 10
  y: 100
  width: 190
  height: 50
  stroke_color: "#000000"
  fill_color: "#f0f0f0"
  stroke_width: 1

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