pdfMachine Merge Fields

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}}

Where to use merge fields.

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

  • Contents of dynamically generated PDFs from Word,Excel,PowerPoint or HTML templates
  • Email Recipients (to, cc and bcc)
  • Email Subject
  • Email Body
  • Attachment name
  • Stamps
  • Passwords
  • Path/name to static attachments
  • Contents of HTML stationery
  • Conditions for when a PDF is attached

You cannot use a merge field to specify the path to the data source or to Word,Excel,PowerPoint or HTML templates. If you want to use a different template based on the content of a merge field then see the section on conditional attachments.

Formatting Merge fields

Rules

  • Formatting is specified in the pdfMachine merge profile or template. Formatting is not taken from the Excel or CSV data source.
  • If you use pdfMachine merge to convert a Word Mail Merge document the Word mail merge rules for formatting is not retained. Once the template has been converted all Word mail merge fields are removed from the template. Any formatting must be applied using pdfMachine merge filters.
  • Text that replaces merge fields in a template retain the formatting of the merge field text in the template (eg bold, font). Right to left formatting should be applied in the Word template to merge fields that will contain right to left text (eg arabic text). The formatting must be applied to the whole merge field including the double braces.
  • Filters can be used with merge fields to format the final text. To use a filter place the pipe symbol (|) after the merge field name and then the filter name. For example to apply the date filter to the merge field birth_date use : {{ birth_date | date:"d MMM yyyy"}}
  • pdfMachine merge uses Liquid filters and tags. The standard filters and tags are supported as mentioned in Liquid For Designers and DotLiquid For Designers. Liquid allows you to apply formatting, perform loops, conditionals etc based on the values from your datasource. Commonly used filters are documented on this page. Additional filters that are specific for pdfMachine merge are documented on this page. Conditionals and loops are documented here

Liquid Filters

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 and tags (not part of Liquid specification) for dates, numbers, currency, uri component encoding, images, barcodes, repeating rows in Microsoft Word and new line handling in Microsoft Word. These are described in the examples below

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

Liquid 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

Commonly used filters are documented on this page. Liquid filters can be found in the Liquid documentation


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 "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.

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
Seperator is culture independent, escaped by single quote character: {{ 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 a number as words

e.g. if amount equals 10.20
{{ amount | money_as_words }}

ten dollars and twenty cents

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

Prepending text

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
oranges, apples
oranges, apples, bananas

Preventing blank lines

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.

How to dynamically insert an image in a Word template

The insert_image filter allows you to insert a specific image - defined by a merge field - into a Word template. This will result in a personalized image in each attachment. You must specify the width of the image in points. The height will be scaled appropriately. This filter should only be used in Word templates.

The image can be obtained from file or from a url. You can use the entire path in the merge field or just a portion of the path with the prepend filter.

You can use this filter to insert generated barcodes from your preferred barcode generator, however if you are satisfied to use the Broadgun Software barcode server the barcode filter is simpler.

 A short video tutorial is available. Note that the source of the image is a path in the data source. It could just as easily have been a portion of the path in the data source a url. Watch here.

Input : {{imagePath|insert_image: 144}}
Output:

Input : {{imageFile | prepend: "c:\images\" |insert_image: 144}}
Output:

Input : {{imagepath | insert_image: 144, imagelink}}
Output:

Input : {{ webaddress | uri_encode | prepend: "https://broadgun.com/barcode/?bcid=qrcode&text=" | insert_image: 50 }}
Output:



How to dynamically insert a barcode in a Word template

The barcode filter allows you to insert a personalized barcode - defined by a merge field - into a Word template. This will result in a personalized barcode in each attachment. You must first specify the type of barcode and then the width of the image in points. You can optionally specify the height of the image in points. If not specified, the height will default to the width.

If the content of the merge field is a url then that url will be a hyperlink on the image in the PDF. You can also (optionally) specify a url as an extra parameter. If you do this then you must put in the width and height parameters first. When you specify a url as a parameter then your barcode will get the merge field content as the text when the barcode scanned however when the barcode is clicked the navigation will go to the specified url. For example, you may have a barcode with the serial number as the text and the url to the store as the hyperlink.

The content of the merge field will be the text used to generate the barcode. This filter should only be used in Word templates.

The barcode filter generates the barcode from the Broadgun Software barcode server. You can use the insert_image filter to generate barcodes from an alternative barcode server. The barcode filter uses the insert_image filter with the Broadgun Software barcode server url (as shown in the example below).

 A short video tutorial is available. Watch here.

Input : {{webaddress |barcode: "qrcode", 50 }}
Output:

Input : {{item_number |barcode: "code128", 200, 50 }}
Output:

Input : {{item_number |barcode: "ean13", 106, 79, webaddress }}
Output:

How to email PDFs for signature capture using pdfMachine sign here and the "sign_here" filter.

  • Place the sign_here filter in a template document. e.g. {{ name | sign_here }}
    The will result in a signature capture field being inserted at this position in the document, with "name" being the merge field containing the name or role of the person to sign the document.
  • The sign_here filter triggers the generated PDF to be uploaded to the pdfMachine sign here website.
  • The uploaded PDF is encrypted and saved on the pdfMachine sign here site, with a signature capture field.
  • A link to the uploaded document is placed in the email body, using the custom liquid tag {% sign_here_list %}.
  • When an email recipient clicks on email body link then can read and sign the document .
  • When a document is signed you are optionally notified via email with a link to the signed document.

sign_here usage

sign_here: email, timestampFormat, languageCode

where:
  • email
    Optional. A string containing the email address that will recieve notifications when a document is signed.
  • timestampFormat
    Optional. A string defining the appearance of the timestamp below the signature. The default is "YYYY-MM-DD HH:mm:ss". If an empty string is provided, no visual timestamp will appear on the resulting PDF document.
  • languageCode
    Optional. A two character string defining the language the pdfMachine sign here website will use. The default is English. Supported languages are:
    English - "en", Spanish - "es", French - "fr", Italian - "it", German - "de", Russian - "ru"

Example Usage

In the template document:

This is the agreement between Rick Smith and Some Guy Corporation.

Blah blah blah….

I agree to the terms.

{{ name | sign_here: "some-guy@someemail.com", "DD/MMM/YYYY MM:hh:ss", "en" }}

In the email body:

Dear {{name}}, Please click on the following link to review then sign the agreement: {% sign_here_list %} Regards, Some Guy
The actual email sent looks like this:

Dear Rick Smith,

Please click on the following link to review then sign the agreement:

agreement.pdf

Regards, Some Guy
When the email recipient clicks on the link, they see a web page that looks like:


When the email recipient signs, they can download the signed PDF. A link to the signed PDF is emailed to "some-guy@someemail.com". The signed PDF looks like:

group_by filter

This filter works on arrays of objects. It takes an property name as a parameter. All the objects with the same value for this property name are grouped together in an array. The result is an array of arrays.

e.g.
            Input:

                {% assign groups = _rows | group_by: "cid" %}
                {% for group in groups %}
                    {{group[0].cid}}  {{group[0].name}}
                {% endfor %}

            Output:
                    1   Apples
                    2   Apples