Skip to content

3.2 Dataset Reference

This chapter is the exact behavioral reference for dataset parsing and execution. Use Dataset Format and Sources first if you are new to the model.

3.2.1 IDs and Naming

This section explains how table headers bind to SVG content.

Dataset headers are matched to SVG IDs.

For the Inkscape ID workflow (where to inspect and edit IDs), see Introduction -> How IDs connect data to graphics.

IDs must be unique and follow XML rules (letters first, no spaces).

3.2.2 Dataset Structure

Dataset structure defines where parsing starts and how sections are separated.

PnPInk supports two forms:

  • Marker mode (recommended, supports multiple datasets).
  • Shorthand mode (single dataset only).

For source selection (CSV vs Google Sheets and tab lookup), see Dataset Format and Sources.

Marker Mode (column A)

Marker mode is the robust format for production datasets and multi-section files.

A dataset marker exists only in column A and uses {{...}}. The marker row is also the header row. Headers start in column B.

Examples (equivalent):

{{t=card_bbox}}
{{template_bbox=card_bbox}}
{{card_bbox}}

Notes:

  • Only one main template bbox is supported per dataset marker.
  • Extra DSL tails are allowed after the marker (see Leading Cell below).

Main Template BBox and Z-Order

This is a core concept: one main bbox drives slot logic for the section.

The marker t=... defines the main template bbox for that dataset section. This main template controls:

  • slot planning (Layout{} / Page{}),
  • per-slot marks (Marks{}),
  • front/back slot pairing (@back),
  • page membership for page-anchored templates (@page selectors).

Placement order (Z-order) follows dataset row order. Later rows are rendered above earlier rows.

Shorthand Mode (single dataset)

Shorthand mode is a convenience form for small, single-section sheets.

If there is no marker row, the first non-empty, non-comment row is treated as the header row.

In shorthand mode, column A contains the template bbox id:

card_bbox, title, cost, art

This is equivalent to:

{{t=card_bbox}}, title, cost, art

3.2.3 Header Types

Header type determines whether a column edits fields or instantiates templates.

Headers in column B+ can be:

  1. Normal data fields: match SVG IDs and replace text or sources.
  2. Template columns: declare extra templates with {...}.

Normal Data Field Syntax

Use this syntax for the most common per-row updates (text, source, and defaults).

Headers can include modifiers:

title
art+
price[xml]
bg=default_bg
art=art_placeholder~i5

Rules:

  • id+ keeps the original anchor rect visible (otherwise anchors are hidden).
  • id[prop] sets the property (text or xml). Default is text.
  • id=... declares a default value or default Fit ops for that column.
  • id-* in headers expands to all matching IDs by prefix.
  • id1 id2 id3 in a single header applies the same cell value to all listed IDs.

Examples:

id=default_id
id=~i5
id=default_id~i5

Header Fan-Out and Wildcards

Use this when one dataset column must feed several placeholders.

Examples:

ph-1 ph-2 ph-3
id1

id1 is applied to all three placeholders.

Wildcard headers are also supported:

main_icon-*
Ic(heart-suit)

This applies the value to every placeholder whose ID starts with main_icon-. All normal header modifiers (+, [xml], =...) remain valid.

Template Column Syntax

Use template columns when you need extra template instances, back passes, or page-level elements.

Template columns declare template bbox IDs and modifiers:

{card_back @back}
{page_title @page}
{back_bg @page @back}

Supported modifiers:

  • @page page-anchored templates
  • @back back-pass templates

Template columns are rendered as additional instances; they do not replace the main template column logic.

3.2.4 Comments and Directives (#)

Comments are processed before any other operation. Rules are global (same behavior everywhere; no inside/outside distinction).

  • # at line start (first non-space char in column A): comment/directive row.
  • ## at line start: full comment row (not a directive).
  • #### at line start: EOF marker, stops parsing the rest of the file/sheet.
  • ## inside a cell: comments out the rest of that cell.
  • ### inside a row (not line start): comments out the rest of that cell and all cells to the right (rest of line).
  • Single # inside a cell is normal text (not a comment).

Header disabling still works:

  • ##header disables that column.
  • ###header disables that column and all columns to the right.

3.2.5 Leading Cell (column A in data rows)

Leading-cell directives are row-level controls, not regular data fields.

Column A in data rows can carry row-level DSL:

  • {A4 ...} page block
  • L{...} layout tail
  • M{...} marks tail
  • trailing copies number
  • optional hole patterns in [...]

Examples:

{A4 b=[-5]} L{p=3x3 g=2} M{mk_cut} 2
[3 - 2-]            -> 3 copies, then 1 hole, then 2 holes

This cell is not a normal dataset field; it controls row-level layout/flow. Its directives apply before regular field replacements in that row.

If a row uses only column-A controls and all payload cells (columns B+) are empty, PnPInk applies the controls but does not generate a card/instance for that row.

card_bbox,title,cost
{A4},,
,Fireball,3

3.2.6 @back -- Back-Side Templates (Back Pass)

Use @back for duplex output where back faces must align with front slot geometry.

A template column marked with @back is rendered only on back pages.

{card_back @back}

Back templates:

  • reuse the same slot sequence from the front layout,
  • mirror slot placement within the page for duplex alignment,
  • preserve row order as Z-order.
  • back pages are inserted right after each front page (interleaved).

If a dataset cell for an @back column is empty or contains - or 0, that back instance is skipped.

3.2.7 @page -- Page-Anchored Templates (One Per Page)

Use @page for elements that belong to the page frame, not to per-card slots.

A template column marked with @page is anchored to the page frame, not to the slot grid.

{page_title @page}

Page-anchored templates:

  • are positioned relative to the page frame after Page{} margins,
  • are rendered once per page,
  • use Fit/Anchor for placement.

Each dataset row provides a slot selector in the cell value (e.g. ~8[-5]). The slot determines which page the template belongs to; the rest is Fit/Anchor ops.

Selectors can be a single slot index, range, or list:

~1
~[1 3 5]
~[2..4]

If multiple rows target the same page, only the first is rendered (a warning is logged).

3.2.8 Combining @page and @back

Combining both modifiers is common for back-page backgrounds and page-level back labels.

{back_bg @page @back}

This places a page-anchored element on back pages, aligned to the front page sequence.

3.2.9 Advanced: Split Boards

This mode is activated automatically when template dimensions exceed target page inner size.

If the template is larger than the target page, the engine switches to split-board mode:

  • the template is cut into tiles,
  • each tile is placed on a page,
  • layout and marks are applied to the tile bounds.