Defining and using dynamic data

Defining test data

The first step in using dynamic data is to actually define it. This is done in the Test data tab of the Template editor.

In this tab, you can define the data your Template will be expecting when generating a Document. This serves two functions:

• It helps you define the structure you want to use for your data

• It provides test data you can play with when building you Template

Data in PDFMonkey, be it test data for a Template or the payload of a Document, is expressed using the JSON syntax.

We'll take the example of an e-commerce order. You could imagine something like this:

{
  "orderId": 1234,
  "orderStatus": "pending",
  "invoiceId": null,
  "client": {
    "civility": "Mr",
    "fullName": "Peter Parker",
    "isNewClient": true
  },
  "lineItems": [
    { "product": "Super strong silk",     "quantity": 100, "price": 123.45 },
    { "product": "Electronic components", "quantity": 12,  "price": 12.34 }
  ]
}

Let's take a look at what we have.

We got some order-related data with orderId and orderStatus. They use different type of data, an integer and a string.

We then get an invoiceId that is null to indicate an empty value. Given our order is pending it does not have an invoice yet, legit.

Things start to get interesting when we get to client as it's a nested structure (usually referred to as "object") containing its own data. You'll notice a new type of data for isNewClient which is a boolean, a value that can be true or false.

And finally we get lineItems that is a list (usually referred to as an "array") of, surprise, line items represented by object with properties for product, quantity and price.

Do you need to nest your data?

You don't have to use a nested structure if you don't like or need it. Here the client details could be defined as clientCivility, clientFullName and clientIsNewClient

Using your test data in the Template

Once you have defined your test data, you call it within your Template using Liquid.

Given the data we defined above, our HTML could start with something like this:

<p>Order num. {{orderId}} is currently {{orderStatus}}.</p>
<p>Client: {{client.civility}} {{client.fullName}}.</p>

As you can see we can reference our data items directly and use a dot (.) to access nested elements. This code would generate the following HTML output:

<p>Order num. 1234 is currently pending.</p>
<p>Client: Mr Peter Parker</p>

In the following guides, we'll learn how to display content according to some condition or how to go over our line items list and display it properly.

Related pages

Naming variables