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:
- Recipient data
- Purchase history
- JSON arrays
- Arithmetic operators
- Symplify entities
- Regular expression
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 and operators are not case sensitive, you can e.g. write contact.firstname as well as contact.FirstName. Examples may have camel casing but that is simply to better visualize the example itself.)
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}}{{/capitalize}} Martin
{{lower contact.firstName}} martin
{{upper contact.firstName}} MARTIN
Psst! If you want a fallback for missing data, check out the Print function!
| 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:
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.
Day of the week
You can also use localizedDate to render the day of the week:
{{localizedDate "EEEE" "fr-FR" contact.dateOfBirth}}
will on a Tuesday return mardi.
| 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 |
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 use 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. 2024-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 2024-02-07 the above example would render:
February
For switching dates, you can refer to:
- y = year
- M = month
- d = day
| top |
When
The when helper is similar to switch and compare but is suitable for simpler operations where you want to match one specific value.
{{#when contact.level "equals" "gold"}}
For gold members, our sale starts on January 2.
{{else}}
Our sale starts on January 5.
{{/when}}
You can use when with different operators:
Text
-
equals
case sensitive -
startsWith
case sensitive -
contains
case sensitive
You can put "not" infront of all of above:
{{#when contact.level "notEquals" "VIP"}}
Do this to become a VIP member!
{{/when}}
You can also end all of above with "ignoreCase" to disregard the casing of the value:
{{#when contact.level "equalsIgnoreCase" "VIP"}}
You are a VIP member!
{{/when}}
Numbers
-
==
number is exactly to -
<=
number less than or equal to -
>=
number greater than or equal to -
<
number less than -
>
number greater than
{{#when contact.points ">=" 500}}
You are a gold member!
{{/when}}
You could also use two when in a row to create a span:
{{#when contact.points ">=" 1}}{{#when contact.points "<=" 250}} Membership: Silver{{/when}}
{{/when}} {{#when contact.points ">=" 251}}{{#when contact.points "<=" 500}} Membership: Gold{{/when}}
{{/when}}
You can use it with Purchase history data as well and for example render information about a purchase:
{{#when ph.last.paymentOption "equals" "VISA"}}{{#when ph.last.totalPrice ">" 400}} You have earned a bonus with your latest purchase! {{/when}}{{/when}}
Or with DataDocs:
{{#when payment "equals" "accepted"}} Paid and ready to go!{{/when}}
If you want to print a fallback if a value is empty you add an else and write your message:
{{#when contact.points}} Current points: {{contact.points}} {{else}} You have no points - yet!{{/when}}
If you don't want to print anything at all if a value is empty you can simply leave else blank:
{{#when contact.points}} Current points: {{contact.points}} {{else}} {{/when}}
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:
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.
On contact attribute data
{{#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)
On datadocs
If we have the following array in a document called orderItems:
"orderItems": [
{
"ticketType": "Adult",
"quantity": 2,
"price": 40
},
{
"ticketType": "Kid",
"quantity": 1,
"price": 10
},
{
"ticketType": "Student",
"quantity": 1,
"price": 15
}
]
We can render this data like this:
{{#documents}}
Your order:
{{#each orderItems}}{{ticketType}} x {{quantity}} = {{price}} €
{{/each}}{{/documents}}
Result:
Your order:
Adult x 2 = 40 €
Kid x 1 = 10 €
Student x 1 = 15 €
| 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:
{{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:
{{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.originalId}} - 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!