Using dot liquid within pdfMachine merge

- to format merge fields or create line items.

pdfMachine merge supports full liquid templating language in HTML templates and the email body, and also has partial support for liquid (liquid filters only) in Microsoft Word/Excel/PowerPoint document templates.

Liquid allows you to apply formatting, perform loops, conditionals etc based on the values from your datasource. The standard filters and tags are supported as mentioned here Liquid For Designers and here DotLiquid For Designers.

Note: To use Liquid Templating Tags in the email body the email body editor should always be in "Source" mode. The "wysiwig" mode will not preserve the Liquid Tags.

Using filters to format merge fields

Filters are simple methods that modify the output of numbers, strings, variables and objects. They are placed within an output tag {{ }} and are denoted by a pipe character |. eg

The capitalize filter will cause the contents of the "name" cell from the data source to be capitalized.

            Input:
                 
{{ name | capitalize }}
Output:
John Smith

Examples of merge field formatting can be found here.

Specific examples :

Examples can also be found in the "Test Profile - Word Template with formatting examples" profile which installs with pdfMachine merge.

Looping (line items) and Conditionals

Conditional output can be done using Liquid tags in a HTML template. Looping through rows to make line items appear can be done using any of the following methods in a HTML template

To loop through rows and create line items in a Word template read here.

Tags are the programming logic that tell templates what to do. Tags are wrapped in: {% %} characters.

Repeat tag

Works with HTML templates. Repeats the current table row, list item or div.

This can be used when the "Rows to emails method" is set to "one or more rows generates an email", which has the effect of grouping the rows based on a merge field, usually the email address.

Note in the example the merge field names must be prefixed with "row."

            Input:
                             
Name Amount
{%repeat%}{{row.name}} {{row.amount}}
Output:
Name     Amount
Dave     1230
Dave     1000

This is a shortcut for the Liquid 'for' loop. Specifically, the Liquid tag "{% for row in _rows %}" is placed in the parent tr, li or div tag.The Liquid for loop does not work well for visual html editors when used around table rows, so this is the preferred option.

Liquid Tags - looping

Liquid also contains tags which support looping. Rows from the data source can become line items in the email or PDF.

These line items (liquid arrays) can be displayed using javascript or liquid looping tags

If there is a column in the data source called description, it is available as {{description}}
Where there are line items (multiple rows with the same email address) in the data source, the multiple rows are passed in as an array in a variable called description_array.  This is accessed as {{ description_array[0] }}, {{description_array[1] }} etc.

eg. Using the Liquid for tag :
{% for desc in desc_array) %} html here {% endfor -%} which repeats the enclosed html for each of the elements of desc_array.  Note: Use forloop.index0 for the current index.
{% cycle 'rows':'LightGreyBackground', 'DarkGreyBackground' %} to alternate row colors in a table.

For an example of using the above in a template:
Click here to see an example HTML merge template using liquid.
Click here to see an example of the PDF generated.
When you install pdfMachine merge, a profile is setup with this demo invoice template, which you try out and customize to your requirements.

Review the example profile here to see how to set up a profile with line items using Javascript.

When using HTML templates, for best results you will need to set certain print options in Internet Explorer

  • Turn off Internet Explorer print headers and footers by File | Page Setup and change them all to "empty"
  • Turn on background colors for printing by File | Page Setup, tick "Print Background Colors and Images"

If you need help or more information on this feature please contact

Liquid Tags - conditionals

Liquid also contains tags which support conditionals eg. if statements

eg. The following will only output if there is data in the "name" cell in the data source:

            Input:
                 
{% if name %} Hello {{ name }} {% endif %}
Output:
Hello John