A merge field is a placeholder that will be replaced by the contents of the corresponding cell from the data source during the merge. 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}}
Merge fields within pdfMachine merge can be used and formatted for most outputs from pdfMachine merge.
You cannot use a merge field to specify the path to the data source or to Word,Excel,PowerPoint or HTML templates.
Examples can also be found in the "Test Profile - Word Template with formatting examples" profile which installs with pdfMachine merge.
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 "capitalize" can be used to ensure that words (eg names) are
output
capitalized
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.
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.
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 |
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
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
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.
Use the filter 'prepend_if' to insert text before the merge field when the merge field is not empty.
| Input | Possible Outputs |
|---|---|
|
{{item1}}{{item2 | prepend_if: ", "}}{{item3 | prepend_if: ", "}} |
oranges |
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 |
Joe Smith |
Joe Smith |
To prevent the blank line use the WordNewLine filter instead of Word line breaks.
| Input | Output |
|---|---|
|
{{Salutation}} {{first name}} {{last_name}} |
Mr Joe Smith |
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.
$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 |
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.