Layout Reference (YAML/Python)

The Layout Template defines the visual structure of your document: fonts, page size, and the position of every element. It focuses purely on presentation.

1. Global Settings

Define your fonts and page size at the top of the file.

# layout.yaml
PAGE:
  size: "A4"             # A4, A3, LETTER, etc.
  orientation: "PORTRAIT"

FONTS:
  MyFont: "assets/fonts/NotoSansJP-Regular.ttf"
  MyFont-Bold: "assets/fonts/NotoSansJP-Bold.ttf"

DEFAULT_FONT: "MyFont"

2. Layout Elements

The LAYOUT list contains the visual widgets. Coordinates start from the bottom-left (0,0).

Text

  - type: "text"
    value: "Invoice #{{invoice_id}}"  # Use {{ }} for variables
    x: "100mm"
    y: "250mm"
    font: "MyFont-Bold"
    size: 20
    align: "CENTER"

Lines & Shapes

  - type: "line"
    x1: "10mm"
    y1: "200mm"
    x2: "200mm"
    y2: "200mm"
    width: 1

Dynamic Images (QR/Stamp)

  - type: "image"
    path: "{{qr_code_path}}"   # Variable from Mapping Plugin
    x: "180mm"
    y: "260mm"
    width: "20mm"
    height: "20mm"

3. Dynamic Tables

The items_table widget automatically handles lists of varying length (e.g., invoice items) and supports pagination.

  - type: "items_table"
    x: "15mm"
    y: "150mm"               # Starts here and grows downwards
    col_widths: ["80mm", "30mm", "30mm", "40mm"]
    headers: ["Description", "Qty", "Price", "Amount"]
    data_keys: ["desc", "qty", "price", "amount"]
    styles:
      - ["GRID", [0,0], [-1,-1], 0.5, "#000000"]
      - ["ALIGN", [1,0], [-1,-1], "RIGHT"]

Choice of Format: While YAML is recommended for most users, developers can use a layout.py file to define these same structures using Python dictionaries and ReportLab objects for maximum control.