Handlebars rundown

Symplify supports handlebars as method for using placeholders in your content, custom tracking and dynamic HTTP requests to name a few examples.

This article will show some examples for the structure of how to create a data placeholder based upon handlebar code. Heads up, this is a nitty gritty one and contains:


Symplify also offers a way to create snippets (or macros) for your created and often used handlebars.
Learn more about Snippets.

​Handlebars and snippets are great tools to visualize and actually transform data to match you communication needs.

Please note that all handlebars working in message content are also working in links and in tracking, however remember that when in links the result value will be URL-encoded.

(Handlebars are not case sensitive, you can e.g. write contact.firstname as well as contact.FirstName.)

Recipient data related

If you want to connect to a recipient attribute value you must type contact. which specifies the recipient and attributename which specifies the specific attribute connected to your recipient/contact. i.e. the recipient first name.

All handlebars must start and end with curly brackets, 

start: {{ and end: }},

So an example of making a placeholder for the recipient data field first name would look like:

{{contact.firstName}}

and adding this into your delivery content would replace the placeholder with the actual data in the field FirstName of the recipient.

 

Functions with recipient data (contact+attributename)

You can transform your recipient data by using different functions.

 

Change the letter casing

{{capitalize contact.firstName}} Martin
{{lower contact.firstName}} martin
{{upper contact.firstName}} MARTIN

top

 

Modify date format

Correct date format for an attribute value is yyyy-MM-dd (i.e. {{contact.dateOfBirth}} will return 1979-08-03) but that doesn’t always match the way you want to visualize a date in your communication. With handlebars you can easily modify your dates.

By adding a format string to your date handlebar you can modify the date output:

{{date "d MM. yyyy" contact.dateOfBirth}}

will return i.e. 3 Aug. 1979 from the original value 1979-08-03, and:

{{date "MMMM d" contact.dateOfBirth}}

will return August 3.

The different options are:
 handlebars01.png

Default language is English but you can change to your language by adding localizedDate and the language code like sv-SE (Swedish), or de-DE (German), i.e.

{{localizedDate "dd MMMM yyyy" "fr-FR" contact.dateOfBirth}}

will return 3 août 1979.

View all supported language codes.

top

 

Modify Url-encode

All handlebars working in message content are also working in links and in tracking, but in these cases the rendered result value must be URL-encoded.

{{urlEncode contact.firstName}}

<a href="{{noEncode contact.linkTarget}}">

<a href="{{contact.linkTarget}}">

top

 

Print

By using the print function you can i.e. add a fallback if a recipient attribute value is empty.

Hi {{print contact.firstName "dear customer"}}

will return i.e. Hi Martin or if the attribute value is empty Hi dear customer.

You can also combine print with other functionality such as changing the letter output:

HI {{#upper}}{{print contact.firstName "dear customer"}}{{/upper}}

will return i.e. HI MARTIN or if the attribute value is empty HI DEAR CUSTOMER.

top

 

Switch and compare

You can use switch to change the output of your data. This can be useful if you for example import short codes for your products but want to write the complete product name in your message.

In below example, the handlebar code is looking for different values in recipient attribute: product_title_code and depending on which one of the different potential values such as: iP or AN or Wi you have as a recipient, you will get a corresponding rendered value in your message; in below case, info of what charger that suits your phone brand.

{{#switch contact.product_title_code}}{{#compare "==" 'iP'}}Apple iPhone charger{{/compare}}{{#compare "==" 'AN'}}Android phone charger{{/compare}}{{#compare "==" 'Wi'}}Windows phone charger{{/compare}}{{#default}}Default value{{/default}}{{/switch}}

​Above example will render:
Apple iPhone charger (if the attribute product_title_code value is equal to iP)
or
Android phone charger (if the attribute product_title_code value is equal to AN)
or
Windows phone charger (if the attribute product_title_code value is equal to Wi)

 

But the attribute value doesn't need to be complete match, you could also transform values that begins with something specific:​

{{#switch contact.status}} {{#stringcompare "startsWithIgnoreCase" "pro"}}professional{{/stringcompare}} {{#default}}creative mind{{/default}} {{/switch}}

Above example would render:
professional for all contacts with attribute values starting with "pro", for example pro_sewer, pro_painter or pro_knitter and creative mind for all others.

 

You could also switch to compare your data and changes the output if i.e. a value is greater than a given value.

Level: {{#switch contact.bonusPoints}}{{#compare ">" 100}}Goldmember{{/compare}}{{#compare "<" 100}}Silvermember{{/compare}}{{#default}}New{{/default}}{{/switch}}

Above example will render
Level: Goldmember (if the attribute bonusPoints value is greater than 100)
or
Level: Silvermember (if the attribute bonusPoints value is less than 100)

top

 

Compare operators

Greater than: >
How to use:

{{#compare ">" 100}}

Result: Matches if value is greater than 100.

Lesser than: <
How to use:

{{#compare "<" 100}}

Result: Matches if value is lesser than 100.

Equals: ==
How to use:

{{#compare "==" 100}}

Result: Matches if value is equal to 100.

​PLEASE NOTE: This can both compare strings and numbers. When comparing strings, case is ignored.

Modular: %
How to use:

{{#compare "%" 4 0}}

Result: Matches if value is dividable by 4 with rest 0.

All compare operators can be negatory with prefix !
How to use:

{{#compare "!=" 100}}

Result: Matches if the value is not 100.

You could also predefine attribute content you want pick out and transform.

In below example where we're using {{message.sendtime}}. This handlebar alone would render a raw date and time (i.e. 2019-02-07T08:55:30.587). But by specifying M for month you can pick up the month and render it differently:​

{{#switchOnExpression "{{date 'M' message.sendtime}}"}}
{{#compare "==" '1'}}January{{/compare}}
{{#compare "==" '2'}}February{{/compare}}
{{#compare "==" '3'}}March{{/compare}}
[and so on...]
{{/switchOnExpression}}

If todays date is 2019-02-07 the above example would render:

February

 

For switching dates, you can refer to:

  • y = year
  • M = month
  • d = day
top

 

Anniversary

The anniversary helper allows you to render content when a date attribute matches todays month and day.

(If there is no anniversary match for a contact, the helper will not return any data.)

 

To render content for any annual event:

{{#ifAnniversary contact.date}} Time flies! You've already been a member for {{anniversary contact.date}} {{#ifAnniversary contact.date 1}}year{{else}}years{{/ifAnniversary}}!{{/ifAnniversary}}

Will return e.g.: Time flies! You've already been a member for 2 years.

 

You can also set a start or end value for when your helper should generate content, or what content.

{{#ifAnniversary contact.date 1}}

Will only render if the date is exactly 1 year ago.

E.g. If todays date is 2022-01-01 above will match 2021-01-01

{{#ifAnniversary contact.date 1}}
Time flies! You have already been a member for a whole year!
{{/ifAnniversary}}

 

And you can add an end value to create a span of years:

{{#ifAnniversary contact.date 2 5}}...

Will only render if the date is 2 to 5 years ago.

E.g. If todays date is 2022-01-01 above will match 2020/2019/2017/2016-01-01.

 

As you can see in the first example, start and end values can also be used for deciding any content in the placeholder:

...{{#ifAnniversary contact.date 1}}year{{else}}years{{/ifAnniversary}}

This will render the text "year" if there is a 1 year anniversary and "years" if there is something else.

 

top

Purchase History data and Handlebars

You can use handlebars to render purchase history data in your communication. Please note that you in some cases need segments to target the correct row in your history database.

​All your purchase history columns (both static and custom) can be used by adding the name of the column to your handlebar. The static Purchase History columns are:

  • transactionDate
  • ItemPrice
  • ItemCount
  • TotalPrice

To render the latest purchase transaction date for a customer you can simply write:

{{ph.last.transactionDate}}

 

There are at the moment three handlebars available for your Purchase History column data for message content use:

first/last order row

Example: “Are you happy with your coffee machine?”

first/last order row based on a segment

Example: “Are you running out of beans?”

all order rows

Example: “This is your order history”

First/last order row

The handlebar {{ph.first.YourPHcolumn}} will grab the oldest value, based on the TransactionDate, from the selected Purchase history column.

The handlebar {{ph.last.YourPHcolumn}} will grab the newest value, based on the TransactionDate, from the selected Purchase history column.

For example, this is the Purchase history data we have:

placeholder-01.png

If we add this handlebar:

{{ph.first.ProductCategory}}

it will render fruit.

{{ph.last.ProductCategory}}

it will render vegetable.

{{ph.last.transactionDate}}

it will render 2017-11-20.

First/last order row based on a segment

You can create a Purchase history segment to target a specific customer history event. The segment can be used as a master or content segment.

The handlebar {{ph.firstInSegment.YourPHcolumn}} will grab the oldest value, based on the TransactionDate, from the selected Purchase history column that matches your segment.

The handlebar {{ph.lastInSegment.YourPHcolumn}} will grab the newest value, based on the TransactionDate, from the selected Purchase history column that matches your segment.

For example, we create a segment for all our customers who bought something in the product category “coffee beans” three weeks ago. Then we can send them a message saying:

Hey {{contact.firstName}}, are you running out of {{ph.lastInSegment.ProductName}}?

Depending on the Purchase history data in the ProductName column this will render differently for our coffee beans customers:

Hey Bruce, are you running out of Silky Arabica?
or
Hey Lady Gaga, are you running out of Bold Robusta?

All order rows

If you want to render the complete purchase history for a customer you can do so by using {{ph.all}}. By using the syntax below you can choose what columns to include. The order of your items will be from first row to last row based on TransactionDate.

{{#each ph.all}} {{this.YourPHcolumn}} {{/each}}

This could be useful if you for example want to render the complete list of purchased items on a Dynamic web profile page.

 

You can also render all purchase rows matching a specific segment.

{{#each ph.allInSegment}} {{this.YourPHcolumn}} {{/each}}

Please note! If no purchase history rule is found it will work as Symplify will render all purchase history for your selected column.

This will be useful if you for example want to render purchases in a specific period of time or product category.

Transform your Purchase history data

It is also possible to combine above handlebars with existing handlebars functions for dates or text.

{{date 'd MMM. yyyy' ph.last.transactionDate}}

will render 3 Nov. 2017 (from the original “2017-11-03”)

or

{{capitalize ph.last.ProductName}}

will render Silky arabica (from the original “silky arabica”).

top

 

JSON arrays

When sending i.e. order confirmations you can save a JSON array in an attribute and use handlebars to render the data in your message.

{{#jsonRender contact.attributeName}} {{#each dataAsArray}} {{.}} {{/each}} {{/jsonRender}}

If we have the following array in a recipient attribute called LastOrder:

{
"Products":[
{
"Product":"Bold Robusta",
"Price":"150 SEK"
},
{
"Product":"Silky Arabica",
"Price":"120 SEK"
}
]
}

We can render this data like this:

Your order:
{{#jsonRender contact.LastOrder}}
{{#each Products}}
{{Product}} ({{Price}})<br>
{{/each}}
{{/jsonRender}}

Result:

Your order:
Bold Robusta (150 SEK)
Silky Arabica (120 SEK)

top

 

Arithmetic operators

You can change the output value of your number and date values by using arithmetic operators.

top

Numbers

In the examples below our recipient has the following data:

placeholder-02.png

{{add contact.value1 contact.value2}}

adding values in attributes value1 and value2
example renders 15

{{subtract contact.value1 contact.value2}}

subtracts values in attributes value1 and value2
example renders 5

{{multiply contact.value1 contact.value2}}

multiplying values in attributes value1 and value2
example renders 50

{{divide contact.value1 contact.value2}}

dividing values in attributes value1 and value2
example renders 2

top

 

Changing dates

In the examples below our recipient has the following data:

placeholder-03.png

{{dateAdd contact.StartDate 2 "DAYS"}}

adding 2 days
example renders 2018-05-24

{{dateAdd contact.StartDate 2 "WEEKS"}}

adding 2 weeks
example renders 2018-06-05

{{dateAdd contact.StartDate 2 "MONTHS"}}

adding 2 months
example renders 2018-07-22

{{dateAdd contact.StartDate 2 "YEARS"}}

adding 2 years
example renders 2020-05-22

{{dateAdd contact.StartDate 2 "DAYS" "MM/dd/YYYY"}}

add 2 days and transforming the output to mm/dd/yyyy format
example renders 05/24/2018

 

Other

{{random 1 1000}}

sets a random number between 1 – 1000

top

 

Symplify entities

You can also use entities created by Symplify to render data:

{{contactdb.id}} - recipient list ID

{{contactdb.name}} - recipient list name

{{contact.id}} - a recipients OriginalID

{{message.id}} - the system ID of the message

{{message.guid}} -

{{message.sendtime}} - returns the sent time stamp in full ISO8601-format, i.e yyyy-MM-dd’T’HH:mm:ss.SSS (i.e 2014-06-25T15:30:24.123).


For other formats, use the date functionality or the switch.

{{message.abslice}} ('A', 'B', 'C' or 'D') If the message is sent as a part of an AB(CD) test.

PLEASE NOTE: If the actual message happens to be part of the winning version, the slice from the winning version will be returned.

{{campaign.id}} - the DeliveryID of the Email

{{campaign.name}} - the name of the Email

{{campaign.segmentid}} - master segment rule ID. PLEASE NOTE: If you get -1 (minus one) no master rule exists as with Transactional send outs.

{{campaign.segmentname}} – master segment rule name

​{{project.id}} - the ID of the Project

{{project.name}} - the name of the Project​

{{link.id}} - the ID of the link

{{link.name}} - the name of the link​

{{link.categories}} - a comma separated string containing all categories added to the link

{{link.segmentid}} - the ID of the segment added to the block which contains the link when content segmentation

​{{link.segmentname}} - the name of the segment added to the block which contains the link

​{{link.clicktime}} - returns the time of the link click in full ISO8601-format, i.e yyyy-MM-dd’T’HH:mm:ss.SSS (i.e 2014-06-25T15:30:24.123).


For other formats, use the date functionality.

top

 

Regular expression functionality

Regular expression functionality is available using the syntax:

{{#regex valueToMatchIn regexPattern}}

​Custom text and matched values using {{match.1}}, {{match.2}}, etc.

{{/regex}}

valueToMatchIn can be a model-attribute like contact.firstName or a hard-coded string “Hello world”.

regexPattern uses Java SE 7. Documentation at:

https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html

Practical example:

{{#regex ‘Hello World!’ ‘(.+) [World](.)’}}

{{match.1}} Universe{{match.1}}

{{/regex}}

Results in: Hello Universe!

 

Substring functionality is available using the syntax

{{#substring beginIndex endIndex}}
value
{{/substring}}

or short

{{substring beginIndex endIndex value}}

beginIndex is base 0 and endIndex is non-inclusive.

Practical example:

for context:
myValue = "This is my Hello World! string"
{{substring 11 23 myValue}}

Results in:
Hello World!

Was this article helpful?
0 out of 0 found this helpful