pdfMachine Merge Fields

A merge field is a placeholder that will be replaced by a corresponding cell from the data source during themerge. A merge field is indicated by a set of double curly braces containing the column name from the data source. They can also have formatting instructions (read here)

{{age}}

Column names that have spaces in them must have the spaces replaced with underscores in the merge fields:

{{first_name}}

Where to use merge fields.

Merge fields within pdfMachine merge can be used and formatted for most outputs from pdfMachine merge.

  • Email Recipients (to, cc and bcc)
  • Email Subject
  • Email Body
  • Attachment name
  • Path/name to static attachments
  • Contents of dynamically generated PDF
  • Stamps
  • Passwords
  • Contents of HTML stationery

You cannot use a merge field to specify the path to the data source or the template.

Formatting Merge fields

Rules

  • Formatting is specified in the email body in the profile.
  • Formatting is specified in the template for the attached PDF.
  • Formatting is not taken from the Excel or CSV data source.
  • Formatting is not taken from any Word Mail Merge fields that are converted when importing a Word Mail Merge document. Once converted Word mail merge fields are removed from the template.
  • Merge fields in a template take on the format of the text in the template (eg bold, font). The formatting must be applied to the whole merge field including the double braces.
  • Filters (described below) can then be applied for further formatting.

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

Text Formatting

Mail merge fields will take on the formatting that is used on them in the template. For example if you have a mail merge field that you want to appear in italics, you can put the whole mail merge instruction (including the surrounding braces) in italics.

{{AccountNo}} will appear as A00001

The liquid filter "captialize" can be used to ensure that words (eg names) are output captialized regardless of how they appear in the data source

{{ name | capitalize }} would appear as John even if the data source held john.

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

Liquid Templating Language

pdfMachine merge supports full liquid templating language in HTML templates and in the email body, and also has partial support for 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, uri component encoding and new line handling. These are described in the examples below.

How to use dates in merge fields

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

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.

Plus or minus days

A filter of dateplusdays is available. It will display a number of days before or after the specified date.

For example {{ datetimenow | dateplusdays : 30 }} takes the current time, adds 30 days and then outputs the date.

Input Output

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

8 Nov 2018

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

8 Nov 2018

Multiple filters on a merge field

You can apply more than one filter to a merge field by using the pipe symbol |.

For example if you want to get the current date and time and then format it you can use two filters. The current date and time is first filtered to add 30 days, then filtered to format the output.

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

23 Jun 2015

How to format currency merge fields

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

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 - the number after the letter C indicates the number of decimal places that will be shown:

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

            ¥25.00

             {{ amt | number_culture : "C0","en-US" }}

            $25

How to format number merge fields

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 : "C0", :"es-ES"}} 1 152,00
{{ num | | number_culture : "N0", "es-MX"}} 1 152
{{ num | number :"P0"}} 52%
{{ num | number :"P2"}} 52.00%
{{ num | number:"#0.00;(#0.00)"}} 52.00 for positive values, (52.00) for negative values

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

Handling blank merge fields in a Microsoft Word template

Word templates will output every character that is not in a merge field “as is”. Sometimes this results in extra blank lines. If you have a merge field that is followed by a new line or paragraph character you may only want that new line to occur when there is something in the merge field.

The address block is a good example of this. The contents of lines in an address block are sometimes empty, eg for a unit address or building name. It is preferable not to have a blank line.

In the following example the merge fields for the address block should take a line each. Some merge fields will be empty eg address_1. A new line is only required when the merge field is present.

Full Address Addresses with an empty "address_1"

Joe Smith
Unit 1
5 Railway Ave
Georgeton, ZA 59680
USA

Joe Smith

5 Railway Ave
Georgeton, ZA 59680
USA

Joe Smith
5 Railway Ave
Georgeton, ZA 59680
USA

To prevent the blank line use the WordNewLine filter instead of Word line breaks.

Input Output

{{Salutation}} {{first name}} {{last_name}}
{{address_1|WordNewLine}}{{address_2|WordNewLine}}{{city}} {{state}} {{postcode}}{{State}} {{postcode}}
{{country}}

Mr Joe Smith
5 Railway St
Mentone
VIC 3965
Australia

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

How to put page numbers in a HTML Template

$page and $maxpage are special variables that are used with HTML templates. They are converted to the "current page" and the "maximum number of pages" in the PDF document. e.g. you might create a HTML stationery file with the text "$page of $maxpage".

Input Output

             Page $page of $maxpage

Page 2 of 5

How to encode special characters as a URI component

If you are using a merge field in a url you may need to use the "uri_encode" filter to encode the user entered components so that they are not misinterpreted on the server.

For example, if you used a url such as http://www.broadgun.com/test?names={{names|uri_encode}} with a merge field "names" of "Jack & Jill" you would need the uri_encode component to force the merge field to be encoded and therefore interpreted correctly by the server.