Knowledge Base

Every data source has a range of fields that can be used to merge into your image values. This can be simply merging the recipients name when using the 'Image Personalisation' data source or perhaps a tweet when using the 'Twitter' data source.

These merge tags can also be used for inserting dynamic images by populating the image URL. In the Twitter example this is used to allow you to insert the profile picture of the Twitter account.

With many data sources though you sometimes need to format the data. Perhaps you want to display the recipients name all in capitals, or perhaps you want to cap the number of words or characters merged in. Maybe you need to format the number of decimal places for a number or even perform a calculation on a price to show what a 30% saving would be.

Reignite uses Handlebars, a powerful scripting language to perform endless customisations on this merge data. This guide takes you through these scenarios as well as the basics of adding simple merge tags and previewing the results.

Adding a merge field to the canvas

Let’s start with a basic example where we simply want to add the value formatted exactly as its seen in the data source. In this instance we shall use the Twitter data source as an example.

First we add a text layer where we want to include the tweet.

Then we right click on this layer and select ‘Insert Merge Field’. 

This brings up our dialog with 2 options:

Pre-defined Field – these are the fields available in the data source

Customised Field – these are fields we have previously added customisation to we can add again or edit the customisation.

For this first example we are going to select the ‘Pre-defined Field’ option. From the dropdown menu we will then choose ‘Tweet’ and then ‘Insert Field’.

Switching to preview mode we can see the Tweet has been inserted.

Customising Merge Fields

However as Twitter is an angry place we want to instead show the Tweet in all capitals. To do this we follow the same process as last time of inserting a merge field, selecting ‘Pre-defined Field’, then choosing ‘Tweet’ but crucially we then choose ‘Customise Field’ instead of ‘Insert Field’.

This brings up a new dialog with the dropdown of the fields, and underneath this a box to give a friendly name for this new merge tag.

Next we have a list of pre-made customisations to choose from in different categories of Text, Maths and Misc. A full list and description of each is below.

Our chosen choice is ‘Transform’ we select by turning on the switch next to it. Then we select ‘Uppercase’ from the drop down menu.

Clicking next takes us to the final screen where you can edit the friendly merge name, and the box underneath allows advanced users to make custom edits to the transform. In this example we won’t touch that and will simply select ‘Insert Field’.

If we switch to preview we can see our tweet all in capitals.

Available Merge Field Customisations

Reignite uses Handlebars, a powerful template language to help you add transformations to data fields. All Handlebars helpers can be used, and a useful reference is here:

https://github.com/helpers/handlebars-helpers/blob/master/README.md

We have included a number of ready-made customisations to assist with non-technical users.

Text

Transform: Converts the text to all UPPERCASE or all lowercase characters

Ellipsis : Truncates text to the specified length, and appends it with an ellipsis, ( … ) 

Truncate: Truncates text to the specified number of characters.

Truncatewords: Truncate a string to have the specified number of words.

Math

Ceil: Get the Math.ceil() of the given value.

Floor: Get the Math.floor() of the given value.

Add: Returns the sum of the data source field value plus the number you enter.

Subtract: Returns the sum of the data source field value minus the number you enter.

Multiply: Returns the sum of the data source field value multiplied by the number you enter.

Divide: Returns the sum of the data source field value divided by the number you enter.

Round: Round the number in the data source field.

Miscellaneous

Replace: Replaces all occurrences of the value in box A within the data source field with what you enter in B

Date: This special format allows you to customise how a date field is displayed selecting from a range of options against each part of the date including Numeric, 2-digit, Narrow, Short, Long. See this article for further detail.

(https://support.prontoforms.com/hc/en-us/articles/360022212811-Handlebars-Date-and-Time-Formatting)

To Fixed: Sets the number format to specified number of decimal points

Add Commas: On numeric fields will add commas at thousands

Trim: Removes spaces from beginning and end of field

Using multiple customisations

One thing to note when choosing multiple transformations is the order they get processed in based upon the first transformation in the tag being run first.

Often this is not an issue but lets take this example:

We have a field where we want to multiply a value, but also format it to 2 decimal places.

### TAG WITH FORMAT THEN MULTIPLY

The problem in this approach is the tag will first change the number to 2 decimal points before the multiplication, therefore giving you an incorrect value.

So instead we manually change the tag to this:

### TAG WITH MULTIPLY THEN FORMAT

Writing your own customisations

You can use the full power of Handlebars with your own customisations of fields including if statements or any format helper. We recommend using the documentation provided by Handlebars:

https://github.com/helpers/handlebars-helpers/blob/master/README.md

Simply make your amends in the ‘Custom Code’ box in the merge field customisations dialog and use the preview mode to see if your customisation is successful.

Using multiple fields

There are times when you need to use multiple fields from the data source in the same customisation. An example of this is if you need to add two fields together to get a total. In this instance you will need to write your own Handlebars code in the ‘Custom code’ box. Field names to use in the code can be found in the fields dropdown when inserting a merge field.