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.
The attributes
Section titled “The 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.
Passing data
Section titled “Passing data”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', },})from lpdf import RenderOptions
pdf = engine.render(xml, RenderOptions(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',}))import io.lpdf.RenderOptions;import java.util.List;import java.util.Map;
byte[] pdf = engine.render(xml, new RenderOptions().data(Map.of( "invoice_number", "INV-2026-001", "customer", Map.of("name", "Acme Inc", "address", "123 Main St"), "items", List.of( Map.of("description", "Consulting", "price", "$1,200.00"), Map.of("description", "Support", "price", "$400.00") ), "total", "$1,600.00")));Data that is JSON text already, such as a file’s or a request body’s, goes to the engine as it is with dataJson(…) in place of data(…).
using Lpdf.Engine;
var data = new { invoice_number = "INV-2026-001", customer = new { name = "Acme Inc", address = "123 Main St" }, items = new[] { new { description = "Consulting", price = "$1,200.00" }, new { description = "Support", price = "$400.00" }, }, total = "$1,600.00",};
var pdf = engine.Render(xml, new RenderOptions { Data = data });use Lpdf\Engine\RenderOptions;
$pdf = $engine->render($xml, new RenderOptions(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.pdfA .md file takes --data too, for fields beside those of its front matter, as A .md file says.
data-value — inject a scalar
Section titled “data-value — inject a scalar”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>data-source — loop over an array
Section titled “data-source — loop over an array”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.
Attributes from data
Section titled “Attributes from data”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.linkstill needs anhrefandimgstill needs aname. - A value is a string, and it is checked as the attribute is:
data-colortakes a color (hex,cmyk(),rgb()orhsl()), a name from thecolorsof the tokens, or a spot color of thespots, alone or as a tint (brand 30%), anddata-backgroundanddata-fillalso takegradient: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 asdata-color="item.status": unknown color token: 'chartreuse'. - An image is picked, not loaded.
data-namechooses among the images the document declares inassetsand 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. Aspanhas no data attributes, and a table of contents section refuses these five.
Combining attributes
Section titled “Combining attributes”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>Values under a prefix
Section titled “Values under a prefix”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.
$toc — the table of contents
Section titled “$toc — the table of contents”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>