Handlebar Placeholders
Carma supports handlebars as method for using placeholders in email, 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.
Carma also offers a way to create snippets (or macros) for your created and often used handlebars.
To dig into handling Snippets, please read here!
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.
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 “first name” would look like:
{{contact.firstName}}
and adding this into the email content would replace the placeholder with the actual data in the field “FirstName” of the recipient/contact.
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
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 change i.e. 1979-08-03 to simply August 3 by writing
{{date "MMMM d" contact.dateOfBirth}}
The different options are:
| Format | Example result |
| M | 8 |
| MM | 08 |
| MMM | Aug |
| MMMM | August |
| d | 3 |
| dd | 03 |
| yy | 79 |
| yyyy | 1979 |
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.
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}}”>
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.
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 euqal to “iP”)
or
Android phone charger (if the attribute bonusLevel value is euqal to “AN”)
or
Windows phone charger (if the attribute bonusLevel value is euqal to “Wi”)
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)
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.
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 transacation 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:
| OriginalID | TransactionDate | ProductCategory |
| 123 | 2017-09-13 | fruit |
| 123 | 2017-11-20 | vegetable |
| 123 | 2017-10-14 | candy |
If we add this handlebar:
{{ph.first.ProductCategory}}
it will render fruit.
{{ph.last.ProductCategory}}
will render vegetable.
{{ph.last.transactionDate}}
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 will be useful if you for example want to render the complete list of purchased items on a microsite 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 Carma 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”).
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:
{"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 dataAsArray}}
{{Product}} ({{Price}}) <br>
{{/each}}
{{/jsonRender}}
Result:
Your order:
Bold Robusta (150 SEK)
Silky Arabica (120 SEK)
Aritmetic operators
You can change the output value of your number and date values by using aritmetic operators.
Numbers
In the examples below our recipient has the following data:
| value1 | value2 |
| 10 | 5 |
{{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
Dates
In the examples below our recipient has the following data:
| StartDate |
| 2018-05-22 |
{{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 in mm/dd/yyyy format
example renders 05/24/2018
Other
{{random 1 1000}}
set a random number between 1 – 1000
System related entities
{{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.
{{message.abslice}} (‘A’, ‘B’, ‘C’ eller ‘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.
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!