Variables

Cassiopeia provides support for templating / variable replacing. This allows you to place variables in your documents and replace them with actual values when generating a PDF. This is very helpful when generating serial letters or invoices.

Syntax

Variables are defined using the {{$variable_name}} syntax in your document. The content between the braces is the variable name. For example, {{$foo}} is a variable named foo.

Variables can be used in any part of your document, including headlines, tables etc. You just can't mix formations within a variable.

Replacing variables

When generating a PDF, you can replace the variables with actual values. This can be done by passing the values as JSON object within the request:

{
  "templates": ["..."],
  "variables": {
    "foo": "bar",
    "test": "42"
  }
}

This example will replace all occurrences of {{$foo}} with bar and {{$test}} with 42.

Troubleshooting

It may occur, that a variable is not replaced. This nearly always has to do with formatting changes within the variable text in the document.

You have to know, that DOCX and ODT files are persisted as XML which is processed as plain text by Cassiopeia. <w:t>{{$variableName}}</w:t> can easily be found and processed. But if you have a formatting change within the variable, like <w:t>{{<w:b>$variable</w:b>Name}}</w:t>, the variable can't be found and replaced by Cassiopeia.

You can fix this by removing the formatting change within the variable via the "Clear Formatting" function.

If that doesn't help too (tables sometimes make problems), you can use a field:

In Word

• Insert > Field > Fill MERGEFIELD {{$variableName}}
• You have to remove manually the « and »

In LibreOffice

• Insert > Field > More Fields ... > Variables > User Field
• Set Format to Text
• Fill Name and Value with variableName (without any $ or {{ or }})