pdfMachine Merge formatting examples

Liquid Templating Language

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. pdfMachine merge also has some custom filters (not part of Liquid specification) for dates, numbers, currency and new line handling. These are described in the examples below.

Examples on how to format merge fields:



Examples of formatted merge fields can also be found in the Test Profile - Word Formatting.

How to use dates in merge fields

Examples of formatted dates can also be found in the Test Profile - Word Formatting.

The liquid filter "date" can be used to format dates in pdfMachine merge fields.

Formatting date and time

The .NET Format strings for date formatting are used by pdfMachine merge, details of these can be found here.

Commonly used date formats are:

input output
{{ invoice_date | date:"d MMM yyyy"}} 1 Jun 2015
{{ invoice_date | date: "dd MMMM yyyy"}} 01 June 2015
{{ invoice_date | date: "MM/dd/yy"}} 06/01/15
{{ start_time | date: "h:mmtt"}} 9:00AM

Current date and time

As well as the Liquid filters for dates, pdfMachine merge also has a special merge field called datetimenow.
A merge field of {{ datetimenow }} does not need a column in the data source, instead it will automatically insert the current date and time.
A filter of dateplusdays is also available to allow you to display a number of days from the current date.
{{ datetimenow | dateplusdays : 30 }} takes the current time, adds 30 days and then outputs the date.

             {{ datetimenow| date : "d MMM yyyy"}}

             23 Jun 2015

             {{ datetimenow | dateplusdays : 30| date : "d MMM yyyy"}}

             23 Jun 2015

In the above example you can see how more than one filter can be used. The current date and time is first filtered to add 30 days, then filtered to format the output.

How to format currency merge fields

Examples of formatted currency fields can also be found in the Test Profile - Word Formatting.

To format a numeric merge field called "amount" as currency, you can use the "money" filter:

             {{ amount | money }}

             $25.00

Or you can use the "money_no_cents" filter:

             {{ amount | money_no_cents }}

             $25

Or you can format the amount particular to a currency, choosing from a culture listed here :

             {{ amt | number_culture : "C","ja-JP" }}

            ¥25

How to format number merge fields

Examples of formatted number fields can also be found in the Test Profile - Word Formatting.

To format a numeric merge field you can use the "number" filter which formats a number according to csharp's number formatting, both standard formats and custom formats. You also use the "number_culture" filter to format a number according to a culture listed here.

To format positive numbers, negative numbers and zero differently you can use conditional formatting. You can specify up to three different sections of your format string at once, separating them with semicolons. If you specify two format string sections, the first is used for positive and zero values while the second is used for negative values; if you use three sections, the first is used for positive values, the second for negative values, and the third for zero values.

Commonly used numeric formats are:

input output
{{ num | number :"N2"}} 1,152.00
{{ num | number :"N0"}} 1,152
{{ num | number_culture :"ru-RU"}} 1 152,00
{{ num | "N0":"ru-RU"}} 1 152
{{ num | number :"P"}} 52%
{{ num | number:"#0.00;(#0.00)"}} 52.00 for positive values, (52.00) for negative values

How to prevent blank lines from a blank merge field

Examples of using the WordNewLine filter can also be found in the Test Profile - Word Formatting.

Sometimes you only want a new line to appear after a merge field if there is something in the merge field. For example, an address block may not always have content for address line 1

Address Line 1 present Address Line 1 missing

Mr Joe Smith
Unit 1
5 Railway St
Mentone
VIC 3925
Australia

Mr Joe Smith

5 Railway St
Mentone
VIC 3925
Australia

When using a Word template then any Word paragraph markers or new lines you place in your template will always be output. To have a new line only inserted after a non-blank merge field you can use the WordNewLine filter instead of a paragraph marker.

{{Salutation}} {{first name}} {{last_name}}
{{address_line_1 | WordNewLine}}{{address_line_2 | WordNewLine}}{{city | WordNewLine}}
{{State}} {{postcode}}
{{country}}

will output

Mr Joe Smith
5 Railway St
Mentone
VIC 3925
Australia

How to format text using pdfMachine merge

Examples of formatted text merge fields can also be found in the Test Profile - Word Formatting.

An example of using text formatting is to ensure that names are output captialized regardless of whether they are or not in the data source
{{ name | capitalize }} capitalize words in the input sentence.