pdfMachine 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

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

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

ten dollars and twenty cents

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.

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.

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

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:

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:

• 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:

In the email body:

The actual email sent looks like this: 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:

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