Skip to content
LpdfDocsv0.36-r1119.4

Lpdf is pre-release. The XML schema and SDK APIs can change between releases.

Data Binding

Data binding lets you separate document structure from content. Pass a data object alongside your document XML, then reference values with data-* attributes.

Attribute Where valid Effect
data-value text and barcode in the layout, including inside a region; text-at and barcode-at in a layer Replaces the text content, or the data a barcode encodes, with the value at the given dot-path
data-source Any layout element Dot-path to an array — repeats this element once per item; inside the loop, paths are relative to the current item
data-if Any layout element; a layer, text-at, img-at and barcode-at Renders the element only when the value at the path is truthy
data-if-not Any layout element; a layer, text-at, img-at and barcode-at Renders the element only when the value at the path is falsy
data-href, data-name, data-color, data-background, data-fill Where the attribute without data- is valid; see Attributes from data Sets that attribute from the value at the path

Data binding applies to the layout, to regions and to layers. A data-value on a link or an img has no effect: they take their target and their image from data-href and data-name. The shapes of a layer take no data attributes, and neither does a span.

A layer reads single values, so data-source is not allowed on its elements: every copy would sit in the same place, and a list from data belongs in the layout. An array item can be read by its index, such as signers[0].name. A layer drawn on several pages shows the same values on each. Text that comes from data, and so can be any length, belongs in the layout: in a layer, a longer text loses its end without a warning.

The data is a plain object (a dictionary in Python, maps, lists and records in Java, any object in C#, an array or object in PHP) that the SDK sends to the engine as JSON. It is an option of the render call, and it applies only when you render XML.

const pdf = await engine.render(xml, {
data: {
invoice_number: 'INV-2026-001',
customer: { name: 'Acme Inc', address: '123 Main St' },
items: [
{ description: 'Consulting', price: '$1,200.00' },
{ description: 'Support', price: '$400.00' },
],
total: '$1,600.00',
},
})

On the command line, lpdf convert reads the same object from a JSON file:

lpdf convert --input document.xml --data data.json --output document.pdf

A .md file takes --data too, for fields beside those of its front matter, as A .md file says.

Replaces the element’s text content with the value at the dot-path. A number or a boolean is written as text. An object, an array, or a path with no value gives empty text.

<!-- static -->
<text>INV-2026-001</text>
<!-- data-driven -->
<text data-value="invoice_number">INV-2026-001</text>

The literal content (INV-2026-001) is what renders when you pass no data, and it keeps the XML readable on its own. When you do pass data and the path has no value, the text is empty.

Nested paths use dot notation, and [n] picks an array item:

<text data-value="customer.name">Acme Inc</text>
<text data-value="items[0].description">First item</text>

Repeats the element once per item. Inside the loop, paths are relative to the current item.

<column data-source="items" gap="xs">
<row>
<text data-value="description">Item</text>
<text data-value="price" width="fill" align="right">$0.00</text>
</row>
</column>

Works on any layout element — column, tr, frame, etc. If the path is missing or is not an array, the element is left out.

Each item is a copy of the element, held until the PDF is written. For tens of thousands of items, such as the rows of a ledger or the lines of a log, bulk on the table, list, grid or column lays them out a page at a time: see Bulk Records.

Two prefixes reach outside the current item: a path that starts with / is read from the root of the data, and each ../ goes up one loop level.

<column data-source="items">
<text data-value="/invoice_number">INV-2026-001</text>
</column>

data-if / data-if-not — conditional rendering

Section titled “data-if / data-if-not — conditional rendering”
<!-- render only when customer.isPremium is truthy -->
<frame data-if="customer.isPremium" padding="xs" background="#ffd700" radius="xs">
<text align="center">★ Premium Customer</text>
</frame>
<!-- render only when customer.isPremium is falsy -->
<frame data-if-not="customer.isPremium" padding="xs" background="#f0f0f0" radius="xs">
<text align="center">Standard Customer</text>
</frame>

A value is falsy when it is missing, null, false, 0, an empty string, an empty array, or an empty object. Everything else is truthy. That includes the string "false", so pass a real boolean, not a string.

data-value fills the words of a text. The other things a row of data should decide, such as where a link goes, which picture an item has or the color of a status, are attributes, and each one that can read the data has a data- form: the name of the attribute with data- in front. It takes a dot-path, with the same loop scopes, / and ../ as data-value.

Attribute On Sets
data-href link href, the link’s destination
data-name img, img-at name, which of the images declared in assets is drawn
data-color text, text-at, the boxes (column, row, grid, frame, td), divider, barcode, barcode-at color
data-background the boxes (column, row, grid, frame, td), barcode, barcode-at background
data-fill shape fill
<column data-source="products" gap="s">
<link href="https://example.com" data-href="url">
<row gap="s">
<img name="photo" data-name="image" width="48pt"/>
<text data-value="name" data-color="statusColor" color="#333333">Product</text>
</row>
</link>
<shape type="rect" width="60pt" height="6pt" fill="#999999" data-fill="statusColor"/>
</column>

With this data, the first product links to its page, shows the photo image and is green. The second shows the logo image and keeps the grey and the dark text that the XML wrote, because it has no statusColor:

{
"products": [
{ "name": "Oak chair", "url": "https://example.com/oak-chair", "image": "photo", "statusColor": "#2e7d32" },
{ "name": "Pine desk", "url": "https://example.com/pine-desk", "image": "logo" }
]
}
  • The attribute without data- stays. It is the value used when no data is passed, and when the path has no value or the value is an empty string. link still needs an href and img still needs a name.
  • A value is a string, and it is checked as the attribute is: data-color takes a color (hex, cmyk(), rgb() or hsl()), a name from the colors of the tokens, or a spot color of the spots, alone or as a tint (brand 30%), and data-background and data-fill also take gradient:name. A number, a boolean, an object or an array is an error, and so is a color that is not one. The error names the attribute and the path, such as data-color="item.status": unknown color token: 'chartreuse'.
  • An image is picked, not loaded. data-name chooses among the images the document declares in assets and your code loaded before the render. The data can’t bring a new image: declare and load one for each image the data may name (a builder loop, or a few lines of XML). A name that is not declared is an error that names the path.
  • Not everywhere. An element without the attribute refuses the data- form when the document is read. A span has no data attributes, and a table of contents section refuses these five.

data-if and data-if-not are checked first, then data-source repeats the element. Both read their path from outside the loop, so a condition on the looped element cannot look at the current item.

<!-- loop over items, but only when there are any -->
<tr data-source="items" data-if="items">
<td><text data-value="description">Item</text></td>
<td><text data-value="amount" align="right">$0.00</text></td>
</tr>

To skip some items, put the condition on an element inside the loop. There it reads from the current item:

<!-- loop over items, skip those with zero quantity -->
<column data-source="items" gap="xs">
<row data-if="qty">
<text data-value="description">Item</text>
<text data-value="qty" width="fill" align="right">0</text>
</row>
</column>

A path may start with a prefix and a colon, invoice:seller.name, to read data that is bound under that prefix beside yours. LCrossIndustryInvoice binds the values of an invoice that way, under the prefix its map names, so a template shows which values come from the invoice, and your data keeps all its keys. A path without a prefix reads your data, and inside a loop the current item.

<column gap="xs">
<text data-value="invoice:seller.name">Seller</text>
<table cols="1fr">
<tr data-source="invoice:lines">
<td><text data-value="name">Item</text></td>
</tr>
</table>
<text data-if="note" data-value="note">A note</text>
</column>

When nothing is bound under a prefix, as in a render that has no invoice, the element stays as the document wrote it, with its own text, whatever the attribute: a data-source shows its element once, unbound, and a data-if keeps its element. A plain render with your data shows a template’s invoice: placeholders that way, and so does a render with no data at all, such as the VS Code preview.

In a section with type="toc", the data also holds $toc: one item per bookmark, with its label, level and page, the number its page prints. The engine adds it, so it is there even when you pass no data. See Table of Contents.

<column data-source="$toc">
<row>
<text data-value="label">Entry</text>
<text data-value="page" width="fill" align="right">0</text>
</row>
</column>