Handlebars templating language provides a way to create a custom layout for emails in Journey Hub. Handlebars can be used in both HTML and Listrak Composer.
📖 Use Handlebars to display data from a custom event payload. Listrak's Managed Integrations uses webhooks to send data from your marketing partners to Listrak to enhance your email and SMS campaigns.
What are Handlebars?
Handlebars is a form of templating language that is used to generate dynamic HTML. Handlebars can be used to generate email HTML or website HTML where variables are replaced with dynamic data.
Components of Handlebar Language
Learn more below about the elements of the templating language that can be used in your Listrak emails.
Basic Expressions
Expressions are the building blocks of the Handlebars language.
The most basic expression is the dynamic variable enclosed in two pairs of curly brackets. A contact's value will replace the expression when the email is sent.
{{Sku}}
Non-escaped Expressions
Expressions are HTML-escaped by default. This will convert a value such as & into &. If a value should not be escaped, the expression should be enclosed in three pairs of curly brackets (e.g. full website URL or product title that contains special characters).
{{{ProductLinkURL}}}
Helpers
Helpers allow Handlebars to execute simple logic procedures or help format data. The Helpers below can be used in HTML and Composer.
Helper Tag | Description | Code Example |
IfCond | Compare two different values | {{IfCond SalePrice 0}}
|
ForAll | Evaluate all items included in an array (e.g. items as the array name)
Parameters: Property: Property to loop through, must be an array.
Sort: Sort all items by the property.
Take: Only take (show) n number of items
Skip: Skip (don't show) n number of items | {{ForAll "ArrayName"}}Sort by product title
Sort by item price: most expensive first
|
FormatCurrency | Format a string, integer, or decimal as currency.
Parameters: Value: Raw value to be formatted.
Format: Currency format ('USD', 'FRCA', 'GBP', 'EURO')
Decimals: Number of decimals to show
Default value: Value show if data is invalid or null | Formatting using price as source
Formatting using price as source, displayed in US dollars with 2 decimal points Formatting using price as source, displayed in US dollars with 2 decimal points. No price is displayed if the value is null.
|
Looping
Looping allows the template to display multiple values from an array of items. Looping is commonly used when a list of items needs to be displayed. For example, items in a wishlist, a customer's cart, or a customer's order. Looping is created using the ForAll helper discussed above.
💡 The appearance of data displayed by the handlebars can be customized using standard email HTML styling. For example, you can add tables, specify font colors, font weights, and alignment.
{{ForAll Items}}
<tr>
<td style="padding-top:12px;">
<table role="presentation" cellpadding="0" cellspacing="0" border="0" width="100%">
<tr>
<td style="width:72px;" class="stack">
<img class="item-img" src="{{ItemImageUri}}" alt="{{ItemTitle}}" width="64" height="64" style="display:block;">
</td>
<td class="stack" style="padding-left:10px;">
<div class="text" style="font-weight:bold; color:#111827;">{{ItemTitle}}</div>
<div class="small" style="margin-top:2px;">SKU: {{ProductCode}} · Part #: {{ProductPartNo}} · {{ProductID}}</div>
<div class="small" style="margin-top:6px;">
Status: {{ItemStatus}} (ID: {{ItemStatusId}})<br>
Ship status: {{ItemShippingStatus}} · <a href="{{ItemTrackingUrl}}" target="_blank" style="color:#111827;text-decoration:underline;">Track</a>
</div>
</td>
</tr>
</table>
</td>
<td class="right">{{ItemQuantity}}</td>
<td class="right">{{ItemPrice}}</td>
<td class="right">{{ItemSubtotal}}</td>
</tr>
{{/ForAll}}
Implementing Handlebars in the Listrak Platform
Setting up the Custom Event
Before you can design an email using handlebars, you need to define the source of your data. Listrak's Managed Integrations allow you to harness loyalty or other data via webhooks in Listrak's Custom Events.
Custom Events can be created under Automations > Journey Hub Custom Events.
You must create at least one property.
If passing a JSON object, pass the stringified version as a string type.
💡 Easily stringify data with the JSON Formatter.
Include all dynamic properties in the custom event either as part of the JSON or as an individual property.
⚠️ Properties included in a JSON object cannot be used in a Custom Event Decision Split. If you plan to create separate logic paths, ensure the variable that defines the logic is an individual property.
Create the custom event. Ensure the checkbox is enabled so the event can be used to trigger a Journey.
Passing Custom Event Data
You can use Listrak's Cross Channel API to pass data to Listrak and iterate the individual data for each participant.
The way that the data is passed via API will impact how you will reference the data in the expression used in the handlebar code block.
Simple Expressions
When a simple expression of a single property and data point is passed over, the name of the property is used in the expression.
For example, to reference the order amount, the expression would become {{OrderAmount}}.
"OrderAmount": "993.99",
"OrderAmountShipping": "0.00",
"OrderAmountTax": "0.00",
"OrderAmountCoupon": "0.00",
"OrderAmountGiftCard": "0.00",
"OrderAmountTotal": "993.99",
"GrandTotalExcludingShipping": 993.99,
Nested Expressions
When data is nested within an property (e.g. OrderCustomer, below) the expression includes the name of both the property and specific field.
For example, to reference customer first name, the expression would become {{OrderCustomer.CustomerFirstName}}.
"OrderCustomer": {
"CustomerFirstName": "Bogus",
"CustomerLastName": "Gateway",
"CustomerEmail": "[email protected]",
"CustomerCity": "Muldrow",
"CustomerStateProvince": "Oklahoma",
"CustomerPostalCode": "74948",
"CustomerCountry": "United States",
"CustomerPhone": "",
"CustomerAddress1": "98547 South 4750 Road",
"CustomerAddress2": ""
}
Array Data in Expressions
When sending an array of data, for example all Wishlist items, the expression will use the name of the data as the key. In the example below the key for the array is "Items," but will be based on the array you pass in the API call.
For example, to reference the items below, the expression would become {{ForAll "Items"}}. Don't forget to include the closing {{/ForAll}} when creating the code block.
"Items": [
{
"ItemID": "14966764601580",
"ItemShippingTracking": "",
"ItemShippingService": "",
"ItemTrackingUrl": "",
"ItemShippingStatusId": 99,
},
{
"ItemID": "14966764634348",
"ItemShippingTracking": "",
"ItemShippingService": "",
"ItemTrackingUrl": "",
"ItemShippingStatusId": 99,
},
{
"ItemID": "14966764667116",
"ItemShippingTracking": "",
"ItemShippingService": "",
"ItemTrackingUrl": "",
"ItemShippingStatusId": 99,
}
]
Using Handlebars Code in a Journey
Once you have created your custom event and determined the naming convention for your expressions, you are ready to build your journey.
Create a new custom event journey. Learn more about creating a custom event journey.
Add an email element to the canvas of your custom event journey.
Set your properties in the element panel.
Give your message a name.
Select the list associated with the message.
⚠️ A contact will only receive a message if subscribed to the list. If the program associated with your custom event does not subscribe a contact, you can use the data management step to subscribe contacts.
Click Edit Message to add the handlebar template code:
If using HTML, add the handlebars code to your existing HTML code.
If using Composer:
Drag a custom HTML element to the desired location on the canvas.
Paste the handlebars template into the custom HTML panel.
Create the handlebars code block based on the custom event.
The block type will be Custom and the source will vary based on the name of your event property.
[[HB BlockType="Custom" Source="Custom.NameofCustomEventProperty"]]
Add the expression(s) for the dynamic data you would like to display for each user.
Add any styling elements such as font color, font size, and adding table structures.
Finalize additional message content. Other content can be built in the Composer interface or in the HTML tab of the message builder.
⚠️ The handlebars content will not display when previewing a message. Activate the journey in test mode and trigger the custom event to send the a message to your personal inbox to see the rendering of the message with the information included in the custom event.