YAML Configuration Reference

A comprehensive guide for manually editing the template.yaml file, covering Layout, Mapping, and Logic.

This guide is intended for advanced users and developers who wish to edit the template.yaml file directly. This file acts as the "Single Source of Truth" for your profile, defining the PDF layout, data mapping, and calculation logic.

File Location

The configuration file is located in your profile directory:

%USERPROFILE%\.pdf_mail_engine\profiles\<YourProfileName>\template.yaml

1. PAGE Configuration (Canvas)

Defines the physical properties of the PDF canvas.

size: Standard sizes (A4, A3, B4, B5, LETTER, LEGAL).
orientation: PORTRAIT or LANDSCAPE.
margins: Global margins in millimeters.

Manual Asset Management

When you add background PDFs manually in the YAML file, the application does NOT automatically import the file into your profile folder.

You must manually copy the .pdf file into the profile directory.

Designer Default Path: assets/background/
Recommended: Use relative paths (e.g., ./background.pdf or assets/background/bg.pdf).

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

2. FONTS

Registers custom TrueType (.ttf) or OpenType (.otf) fonts.

Manual Asset Management

You must manually copy the font file into the profile directory.

Designer Default Path: assets/fonts/

FONTS:
  # FontName : Relative Path
  "MyCustomFont": "assets/fonts/MyFont-Bold.ttf"
  "CorporateFont": "Corporate-Regular.otf"

3. MAPPING (Data Binding)

Maps your CSV/Excel column headers to internal variable names used in the template.

Syntax: InternalKey: "CSV Column Header"

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

4. CALCULATIONS

Defines automatic calculations to run during data ingestion.

Syntax Consistency

Use {{ }} braces for variables. For consistency with text fields, it is recommended to wrap variable names in {{ }} braces, even in calculation formulas.

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

scope:
- item: calculated for every row (e.g., {{ quantity }} * {{ price }}).
- group: calculated for a group of rows (e.g., sum of totals).
expression: A mathematical expression. Supports math functions like floor(), ceil(), round().

CALCULATIONS:
  # Row-level calculation (e.g., Tax)
  - scope: "item"
    target: "tax_amount"
    expression: "floor({{ amount }} * 0.10)" # Use math functions

  # Add this to show where total_with_tax comes from
  - scope: "item"
    target: "total_with_tax"
    expression: "{{ amount }} + {{ tax_amount }}"

  # Group-level calculation (Sum of all rows in the invoice)
  - scope: "group"
    target: "grand_total"
    type: "sum" # 'sum' adds up values
    field: "total_with_tax"

5. LAYOUT (Elements)

The LAYOUT list defines every visual element on the PDF. Elements are drawn in order (later elements draw on top).

Common Properties

Most elements support these properties:

x, y: Position in millimeters (from bottom-left by default).
visible: Condition expression (e.g., {{ amount }} > 0).
position: absolute (default) or relative.

Text

Displays static text or dynamic variables using Jinja2 syntax {{ key }}.

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

Image

Embeds an image file.

Manual Asset Management

You must manually copy the image file into the profile directory.

Designer Default Path: assets/images/

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

Group Table (Dynamic)

Renders a dynamic table that iterates over your data rows (Detail/Line Items).

- type: "group_table"
  x: 20
  y: 180
  # Global Styles
  header_height: 8
  row_height: 6
  border_color: "#000000"
  grid_color: "#cccccc"
  alt_row_color: "#f0f0f0" # Zebra striping
  
  columns:
    - header: "Item"
      key: "item_name"
      width: 60
      align: "LEFT"
      
    - header: "Price"
      key: "unit_price"
      width: 30
      align: "RIGHT"
      format: "currency" # Formats with commas

Static Table (Fixed)

Renders a fixed grid where you define the rows manually. Useful for footers, bank details, or signature blocks.

- type: "static_table"
  x: 20
  y: 50
  width: 170 # Optional. Inferred from the sum of column widths if not specified
  
  columns:
    - width: 30
      header: "Label"
    - width: 140
      header: "Value"
  
  # Rows defined manually
  rows:
    - ["Bank Name", "Mizuho Bank"]
    - ["Account No", "{{ account_number }}"] # Can use variables
    - ["Note", "Please pay within 30 days"]

Barcode

Generates a 1D barcode.

Supported Types: CODE128, JAN (EAN13 mixed), EAN13, EAN8, CODE39, UPCA, NW-7 (Codabar), ITF.

- type: "barcode"
  value: "{{ invoice_no }}"
  x: 20
  y: 20
  width: 50        # Max Width (scales down if needed)
  height: 10       # Total Height
  
  barcode_type: "CODE128"
  bar_width: 1.0   # Thickness of bars
  bar_height: 10   # Height of bars
  
  # Human Readable Text
  human_readable: true
  hr_font: "Helvetica"
  hr_size: 10
  hr_color: "#000000"

QR Code

Generates a 2D QR code.

Error Correction Levels: L (7%), M (15%), Q (25%), H (30%).

- type: "qrcode"
  value: "https://example.com/inv/{{ invoice_no }}"
  x: 150
  y: 20
  width: 20       # Size (Aspect ratio fixed)
  
  qr_error_level: "M"
  qr_quiet_zone: true   # Include white margin
  
  color: "#000000"      # Foreground
  back_color: "#ffffff" # Background
  opacity: 1.0

Shapes (Rect / Line)

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

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