YAML-Konfigurationsreferenz

Diese Anleitung richtet sich an fortgeschrittene Benutzer und Entwickler, die die Datei template.yaml direkt bearbeiten möchten. Diese Datei dient als „Single Source of Truth" für Ihr Profil und definiert das PDF-Layout, das Datenmapping und die Berechnungslogik.

Dateispeicherort

Die Konfigurationsdatei befindet sich in Ihrem Profilverzeichnis innerhalb des Arbeitsbereichs:

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

Der Standard-Arbeitsbereich befindet sich im Ordner PDFMailEngine_Workspace in Ihrem Dokumentenverzeichnis. Sie können den Arbeitsbereich über die Anwendungseinstellungen ändern.

1. PAGE-Konfiguration (Leinwand)

Definiert die physischen Eigenschaften der PDF-Leinwand.

• size: Standardgrößen (A3, A4, A5, B4, B5, LETTER, LEGAL).
• orientation: PORTRAIT oder LANDSCAPE.
• margins: Globale Ränder in Millimetern.

PAGE:
  size: "A4"
  orientation: "PORTRAIT"
  margins:
    top: 20
    bottom: 20
    left: 20
    right: 20
  background: "assets/background/stationery.pdf" # Optionales Hintergrund-PDF

2. FONTS (Schriftarten)

Registriert benutzerdefinierte TrueType- (.ttf) oder OpenType-Schriftarten (.otf).

FONTS:
  # Schriftname : Relativer Pfad
  "MyCustomFont": "assets/fonts/MyFont-Bold.ttf"
  "CorporateFont": "Corporate-Regular.otf"

3. MAPPING (Datenbindung)

Ordnet Ihre CSV/Excel-Spaltenüberschriften den internen Variablennamen zu, die in der Vorlage verwendet werden.

Syntax: InternerSchlüssel: "CSV-Spaltenüberschrift"

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

4. CALCULATIONS (Berechnungen)

Definiert automatische Berechnungen, die während der Datenverarbeitung ausgeführt werden.

• scope:
  • item: Wird für jede Zeile berechnet (z. B. {{ quantity }} * {{ price }}).
  • group: Wird für eine Gruppe von Zeilen berechnet (z. B. sum von Summen).
• expression: Ein mathematischer Ausdruck. Unterstützt math-Funktionen wie floor(), ceil(), round().

CALCULATIONS:
  # Zeilenebene-Berechnung (z. B. Steuer)
  - scope: "item"
    target: "tax_amount"
    expression: "floor({{ amount }} * 0.10)" # Math-Funktionen verwenden

  # Herkunft von total_with_tax verdeutlichen
  - scope: "item"
    target: "total_with_tax"
    expression: "{{ amount }} + {{ tax_amount }}"

  # Gruppenebene-Berechnung (Summe aller Zeilen der Rechnung)
  - scope: "group"
    target: "grand_total"
    type: "sum" # 'sum' addiert Werte
    field: "total_with_tax"

5. LAYOUT (Elemente)

Die LAYOUT-Liste definiert jedes visuelle Element auf dem PDF. Elemente werden in Reihenfolge gezeichnet (spätere Elemente werden über früheren dargestellt).

Koordinatensystem

Allgemeine Eigenschaften

Die meisten Elemente unterstützen diese Eigenschaften:

• x, y: Position in Millimetern.
• visible: Ein Bedingungsausdruck, der steuert, ob das Element gerendert wird (siehe unten).
• position: absolute (Standard) oder relative.

Die visible-Eigenschaft

Die visible-Eigenschaft akzeptiert einen Python-Ausdruck, der gegen die aktuelle Datenzeile ausgewertet wird. Wenn der Ausdruck False (oder einen falschen Wert) ergibt, wird das Element ausgeblendet.

Verfügbare eingebaute Funktionen: int(), float(), str(), len()

# Nur anzeigen, wenn der Betrag positiv ist
- type: "text"
  value: "Gesamt: {{ amount }}"
  visible: "{{ amount }} > 0"
  x: 20
  y: 250

# Nur anzeigen, wenn ein Feld nicht leer ist
- type: "text"
  value: "Hinweis: {{ note }}"
  visible: "len(str({{ note }})) > 0"
  x: 20
  y: 240

# Mehrere Bedingungen kombinieren
- type: "text"
  value: "Rabatt angewendet"
  visible: "{{ discount_rate }} > 0 and {{ amount }} >= 10000"
  x: 20
  y: 230

Text

Zeigt statischen Text oder dynamische Variablen mit Jinja2-Syntax {{ key }} an.

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

Bild

Bettet eine Bilddatei ein.

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

Gruppentabelle (Dynamisch)

Rendert eine dynamische Tabelle, die über Ihre Datenzeilen (Detail-/Positionszeilen) iteriert.

- type: "group_table"
  x: 20
  y: 180
  # Globale Stile
  header_height: 8
  row_height: 6
  border_color: "#000000"
  grid_color: "#cccccc"
  alt_row_color: "#f0f0f0" # Zebrastreifen

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

    - header: "Preis"
      key: "unit_price"
      width: 30
      align: "RIGHT"
      format: "currency" # Formatiert mit Tausendertrennzeichen

Statische Tabelle (Fest)

Rendert ein festes Raster, in dem Sie die Zeilen manuell definieren. Nützlich für Fußzeilen, Bankverbindungen oder Unterschriftenblöcke.

- type: "static_table"
  x: 20
  y: 50
  width: 170 # Optional. Wird aus der Summe der Spaltenbreiten abgeleitet, wenn nicht angegeben

  columns:
    - width: 30
      header: "Bezeichnung"
    - width: 140
      header: "Wert"

  # Manuell definierte Zeilen
  rows:
    - ["Bankname", "Deutsche Bank"]
    - ["Kontonr.", "{{ account_number }}"] # Variablen verwendbar
    - ["Hinweis", "Bitte innerhalb von 30 Tagen überweisen"]

Barcode

Generiert einen 1D-Barcode.

Unterstützte Typen: CODE128, JAN (EAN13 gemischt), EAN13, EAN8, CODE39, UPCA, NW-7 (Codabar), ITF.

- type: "barcode"
  value: "{{ invoice_no }}"
  x: 20
  y: 20
  width: 50        # Maximale Breite (wird bei Bedarf verkleinert)
  height: 10       # Gesamthöhe

  barcode_type: "CODE128"
  bar_width: 1.0   # Balkenstärke
  bar_height: 10   # Balkenhöhe

  # Lesbarer Text
  human_readable: true
  hr_font: "Helvetica"
  hr_size: 10
  hr_color: "#000000"

QR-Code

Generiert einen 2D-QR-Code.

Fehlerkorrekturlevel: L (7 %), M (15 %), Q (25 %), H (30 %).

- type: "qrcode"
  value: "https://example.com/inv/{{ invoice_no }}"
  x: 150
  y: 20
  width: 20       # Größe (Seitenverhältnis fest)

  qr_error_level: "M"
  qr_quiet_zone: true   # Weißen Rand einschließen

  color: "#000000"      # Vordergrund
  back_color: "#ffffff" # Hintergrund
  opacity: 1.0

Formen (Rect / Line)

Rect-Eigenschaften (Rechteck):

• x, y: Position in Millimetern.
• width, height: Abmessungen in Millimetern.
• stroke_color: Rahmenfarbe (Hex, z. B. "#000000").
• fill_color: Füllfarbe (Hex, z. B. "#f0f0f0"). Weglassen für keine Füllung.
• stroke_width: Rahmenstärke in Punkt (Standard: 1).
• opacity: Deckkraft von 0.0 (transparent) bis 1.0 (undurchsichtig).

Line-Eigenschaften (Linie): Eine Linie wird als Rechteck mit height: 0 (horizontal) oder width: 0 (vertikal) gezeichnet.

• x, y: Startposition in Millimetern.
• width: Länge einer horizontalen Linie.
• height: Länge einer vertikalen Linie. Auf 0 setzen für horizontale Linien.
• stroke_color: Linienfarbe (Hex).
• stroke_width: Linienstärke in Punkt.

# Rechteck mit Rahmen und Füllung
- type: "rect"
  x: 10
  y: 100
  width: 190
  height: 50
  stroke_color: "#000000"
  fill_color: "#f0f0f0"
  stroke_width: 1

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