Variables

A variable is a named field in a design whose value is supplied at generation time. Binding an element to a variable is what makes a design a template instead of a fixed document: one layout covers every variation without forking files.

How binding works

Binding is per-element. You author an element with a unique name and representative sample content, then bind it with a single action — the element’s name becomes the variable name, and the bound field follows the element type (text → its content, image → its source, table → its cells):


[
  {
    "type": "add_element",
    "args": {
      "type": "text",
      "name": "customer_name",
      "position": { "x": 48, "y": 48 },
      "data": { "content": "Acme Corp" },
      "styles": { "fontSize": 24, "fontWeight": 700 }
    }
  },
  { "type": "bind_variable", "args": { "name": "customer_name" } }
]

At generation time the supplied value replaces the bound element’s content. The "Acme Corp" above is sample content — it’s what renders when no value is supplied, and it’s what the text box is measured from, so make samples look like real values.

You can see all of a design’s variables in the variables field of GET /api/v1/designs/:id.

Supplying values at generation time

When you generate, pass a data object whose keys are the variable names:


curl -X POST "https://api.imaginepdf.com/api/v1/designs/design_abc123/generate" \
  -H "X-API-Key: $IMAGINEPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "customer_name": "Globex Inc",
      "amount": "$1,000.00"
    }
  }'

Variables you do not supply render their design-time sample content. Supply every variable you expect to see filled in the output.

Table variables

Bind a table the same way — name it, bind it, and supply a 2-D array of strings (first row = header, if your table has one). The table’s rows grow or shrink to fit the data; new rows inherit the design’s last-row styling.


{
  "data": {
    "line_items": [
      ["Description", "Qty", "Amount"],
      ["Design work", "2", "$400.00"],
      ["Hosting", "1", "$25.00"]
    ]
  }
}

Batch: one row, one document

For batch generation the same idea scales: each row of your dataset is one data object, and ImaginePDF produces one PDF per row.


{
  "rows": [
    { "customer_name": "Acme Corp",  "amount": "$1,000.00" },
    { "customer_name": "Globex Inc", "amount": "$2,500.00" }
  ]
}

See Batch generation.

Images as variables

Image elements can be bound too — to swap a logo or a photo per document. The value you supply is an asset reference (assets:<id>) rather than a string. See Assets.