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 within the workspace:

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

The default workspace location is the PDFMailEngine_Workspace folder inside your Documents directory. You can change the workspace location from the application settings.

1. PAGE Configuration (Canvas)

Defines the physical properties of the PDF canvas.

size: Standard sizes (A3, A4, A5, 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).

Coordinate System

Coordinate Origin

Templates created by the Designer use a top-left coordinate system (Y=0 is the top of the page). When editing YAML manually with the PAGE key, the default coordinate system is bottom-left (Y=0 is the bottom of the page).

The coordinate system is determined automatically: templates using the canvas key (Designer format) use top-left, while templates using the PAGE key use bottom-left.

Common Properties

Most elements support these properties:

x, y: Position in millimeters.
visible: A condition expression that controls whether the element is rendered (see below).
position: absolute (default) or relative.

The `visible` Property

The visible property accepts a Python expression that is evaluated against the current data row. If the expression evaluates to False (or a falsy value), the element is hidden.

Available built-in functions: int(), float(), str(), len()

# Show only when amount is positive
- type: "text"
  value: "Total: {{ amount }}"
  visible: "{{ amount }} > 0"
  x: 20
  y: 250

# Show only when a field is not empty
- type: "text"
  value: "Note: {{ note }}"
  visible: "len(str({{ note }})) > 0"
  x: 20
  y: 240

# Combine multiple conditions
- type: "text"
  value: "Discount Applied"
  visible: "{{ discount_rate }} > 0 and {{ amount }} >= 10000"
  x: 20
  y: 230

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)

YAML Manual Editing Only

Shape elements (rect and line) cannot be added through the Designer UI. They are only available when editing the YAML file directly.

Rect properties:

x, y: Position in millimeters.
width, height: Dimensions in millimeters.
stroke_color: Border color (hex, e.g., "#000000").
fill_color: Fill color (hex, e.g., "#f0f0f0"). Omit for no fill.
stroke_width: Border thickness in points (default: 1).
opacity: Opacity from 0.0 (transparent) to 1.0 (opaque).

Line properties: A line is drawn as a rectangle with height: 0 (horizontal) or width: 0 (vertical).

x, y: Start position in millimeters.
width: Length of a horizontal line.
height: Length of a vertical line. Set to 0 for horizontal lines.
stroke_color: Line color (hex).
stroke_width: Line thickness in points.

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

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

YAML Configuration Reference

File Location

1. PAGE Configuration (Canvas)

Manual Asset Management

2. FONTS

Manual Asset Management

3. MAPPING (Data Binding)

4. CALCULATIONS

Syntax Consistency

5. LAYOUT (Elements)

Coordinate System

Coordinate Origin

Common Properties

The visible Property

Text

Image

Manual Asset Management

Group Table (Dynamic)

Static Table (Fixed)

Barcode

QR Code

Shapes (Rect / Line)

YAML Manual Editing Only

The `visible` Property