Introduction to HandleBars

How to personalise messages on CrossEngage using HandleBars.

About Handlebars

Handlebars is a popular language for personalising content and building reusable HTML template blocks. CrossEngage uses HandleBars to allow you to easily personalise content by allowing you to access user attributes, event data, voucher data or product information within messages.

Read more about the HandleBars framework and its built-in helpers here.

Syntax Example

Let's look at a simple example of displaying a users' first name within a message:

Hello {{user.[traits.firstName]}}, how are you doing today?

This will render the template upon message dispatch as follows:

Hello Sarah, how are you doing today?

During message dispatch, CrossEngage will now automatically render the first name of each user that will receive the message.

Note on Syntax:

Handlebars HTML-escapes the equals sign. Therefore, if your Handlebar includes an equals sign, this will return '&#x3.' If you don’t want Handlebars to escape a value, use three curly brackets on each side of the Handlebar (e.g. if ‘traits.favouriteProduct' has an id value of 123cacdsf=asd, you can use the following: {{{traits.favouriteProduct}}})

Customising Templates

Customising templates using HandleBars is dependent on the integration you use to dispatch a message. Some integration providers allow you to either create and host templates on their side or send HTML messages programatically. When integration providers allow you to do both, CrossEngage will give you the option to either choose a template from the provider or create one in CrossEngage.

Using an External Template

When choosing to use an external template and wanting to add personalisation, you first need to ensure that you have already set up pre-defined placeholders on the template. Placeholders will allow you to easily insert personalisation in your template as you will fill each placeholder with the chosen personalised data. The syntax for placeholders is defined by each integration, for example, in SendGrid, your HTML template may look like the below when wanting to include a user's first name:

<div>
<p>Hi %FIRSTNAME%.</p>
</div>

Always use expressive names for placeholders as this will allow you to easily recognise and choose the right personalisation to use in CrossEngage at a glance.

To fill this placeholder with the right personalisation in CrossEngage, you can either choose to use:

Attribute
HandleBars
Attribute
HandleBars

Using a CrossEngage Template

When creating a template in CrossEngage, you can type HandleBars syntax directly within your template and CrossEngage will render it upon dispatch. For example:

<div>
<p>Hi {{user.[traits.firstName]}}.</p>
</div>

Types of Data That Can Be Accessed

User Data

To access user profile data within a message, you should use the following syntax:

{{user.[traits.***]}}

*** is the placeholder which must be replaced with the name of the user attribute that you would like to access. e.g. firstName, email, phone.

For example, to display a user's email, you should use the following syntax:

{{user.[traits.email]}}

Once the message is rendered, it displays the following in the section where it is used in the message:

john.doe@crossengage.io

Event Data

To access data regarding historical events and journey steps, consult the following documentation:

Product Data

You can access product data either from:

  • The product feed

  • A completed order event

  • Other events

Product Feed Information

To search and extract information from the product feed, you should use the #findProduct helper function:

Voucher Data

You can access data from any voucher pool created on CrossEngage and send a personalised voucher to each user upon message dispatch using the #voucherPool helper function: