Docs
EN
English Español
Sign up

Data field bindings and formatting

A data field binding connects an element in your template to a field in its data schema. When ShipPDF previews or generates the document, it replaces the binding with the field’s value. You can then format that value without changing the source data.

For example, a Text element can combine a label with two bindings:

Invoice {{invoice.number}} · Total {{invoice.total}}

With INV-1042 and 1250 in the data, the generated text could be Invoice INV-1042 · Total $1,250.00 after currency formatting is applied to invoice.total.

Bind a field

Open a template and select Data Fields in the inspector. You can create a binding in either of these ways:

  • Drag a field onto a Text element or table header.
  • Edit the value of a Text, QR Code, or Barcode element, type {{, and choose a field from the menu.

Inside Text, each binding appears as a field pill. Static text and several field pills can share the same Text element. Select a pill to change the formatting for that occurrence of the field.

The field picker only shows fields that are valid at the selected location. This prevents a field from being bound outside the Loop or Table row where its value exists.

Bindings by element

ElementHow the binding is used
TextInsert one or more field pills alongside static text. Each occurrence can have its own formatting and bold, italic, or underline styling.
TableChoose a Collection as the table source, then bind columns to fields from each collection item. The same field can also be used in summaries and formulas where supported.
ImageSelect From data field and bind a String field containing an image URL. A selected static image can act as the fallback when the field has no value.
QR CodeCombine static text with a field, or bind a field containing the complete text or URL to encode.
BarcodeCombine static text with a field, or bind a field containing the value to encode. The resolved value must meet the requirements of the selected barcode format.
LoopChoose a Collection or List as the Loop source. Bind the elements inside it to fields from the current item.

Understand binding scope

Fields at the root of the data schema are available throughout the document. A Collection creates an item scope when it is used by a Table or Loop. Inside that scope, bind to the fields of the current row or item.

Given this schema:

invoice                  Object
|-- number               String
`-- items                Collection
    |-- description      String
    |-- quantity         Number
    `-- unit_price       Number

invoice.number is a root binding. When a Loop or Table uses invoice.items, its content can bind to description, quantity, and unit_price for the current item. A nested Collection must first be entered with another Loop before its item fields become available.

Headers and footers also provide Page number and Total pages fields. Use them to produce text such as Page 2 of 6 across explicit and overflow pages.

Format a field value

Select a field pill in a Text value, or open the bound field’s settings in the inspector. Choose a Format, then configure the options shown for that field type.

Formatting belongs to that occurrence of the binding. The same number can appear as a plain quantity in one place and as currency in another. Formatting changes only the rendered text; it does not change the schema, Default Data, or request JSON.

Field typeAvailable formatting
StringKeep the value as entered, convert it to uppercase or lowercase, and add a prefix or suffix.
NumberUse a locale-aware number, currency, or percentage. Select the locale and 0–6 decimal places; currency also accepts an ISO currency code such as USD or MYR.
BooleanSet the labels shown for true and false, such as Paid and Unpaid.
Date or Date/TimeSelect a locale and date pattern, or enter a custom pattern.
ListChoose the separator between items, then format each item according to the List’s primitive type.

Number examples

Source valueFormatOutput
1234.5Number, en-US, 2 decimals1,234.50
1234.5Currency, en-US, USD, 2 decimals$1,234.50
0.125Percentage, en-US, 1 decimal12.5%

Percentage formatting treats the source as a fraction, so send 0.25 to display 25%.

Date patterns

ShipPDF includes common patterns such as yyyy-MM-dd, dd/MM/yyyy, MMM d, yyyy, and d MMMM yyyy. For a custom pattern, use these tokens:

PartTokens
Yearyyyy, yy
MonthMMMM, MMM, MM, M
Daydd, d
WeekdayEEEE, EEE

Wrap literal words in single quotes. With the en-GB locale, the value "2026-10-02" and pattern d MMMM yyyy display as 2 October 2026.

List formatting

Choose a comma, semicolon, new line, space, no separator, or a custom separator. You can also format each item. For example, a List of strings containing draft and sent can use uppercase text and a semicolon separator to display DRAFT; SENT.

Preview and validate bindings

Use Preview PDF to check bindings with the template’s Default Data. Before publishing, also test data that contains long text, empty Collections, large numbers, and missing optional values.

The editor reports invalid bindings when a field has been removed, is outside the current scope, or uses formatting that no longer matches its type. Revisit the affected bindings after renaming fields, changing field types, or changing the source of a Loop or Table.

When generating a document, keep JSON values in their schema types. Send numbers as JSON numbers, booleans as true or false, and Collections or Lists as arrays. A missing optional value can use Default Data; an explicit null does not restore the default and may fail schema validation.

Next steps