Documentation
Help CenterCommunityDevelopersAcademyStatus

Using helpers in message scripting

This section includes standard and custom helpers that you can use in message scripting

Suggest Edits

Using Handlebar helpers in message scripting

Use these basic Handlebar helpers in your message scripting template.

List of basic helpers

Message scripting uses several helpers to provide much of the function that is needed for flexible templates. The following list contains helpers that are currently supported.

The if helper is used to conditionally render a block of content.
The else helper is used to specify block of content that is returned if the expression returns a false value.
The helper is used as the inverse of the if helper.
The each helper is used to iterate over a list. Also known as looping.
For detailed documentation for these helpers, go to http://handlebarsjs.com/builtin_helpers.html.

Using custom helpers in message scripting

Message scripting provides a growing list of custom helpers. The following information identifies custom helpers that are supported.

List of custom helpers and their examples

#xif (Extended if)

Use the Extended if helper to compare a context field value to a constant string, number, or Boolean value that uses a subset of JavaScript operators. Extended if also works with {{else}} blocks.

📘

Note:

If you do not want the system to evaluate numbers and Boolean values as strings, use JSON context. The operators that are currently supported are “==”, “!=”, “>=”, “<=”, “>”, and “<“.

Example 1: xif / else xif / else

{{#xif 'Age == 18' }}
Vote for your first time!
{{else xif 'Age > 18' }}
Keep voting
{{else}}
Can't vote yet
{{/xif}}

Example 2: nested xif

📘

Note:

When using nested xif, the value being checked should be surrounded in double-quotes. Similarly, you should surround the statement in single quotes. Otherwise, the statement will not work.

{{#xif 'gender=="male"' }}
{{#xif 'age=>"18"' }}
Have you registered for the selective service?<br/>
{{/xif}}
{{/xif}}

capitalizeFirst

Capitalizes the first word of a field value or string constant.

Given {{capitalizeFirst myField}}with a context of{"myField":"some value"}
Result: Some value

capitalizeEach

Capitalizes each word of a field value or string constant.

Given {{capitalizeEach myField}}with a context of{"myField":"some value"}
Result: Some Value

upperCase

Capitalizes all letters of a field value or string constant.

Given {{upperCase myField}}with a context of{"myField":"some value"}

Result: SOME VALUE

lowerCase

Enters all letters of a field value or string constant in lowercase letters.

Given {{lowerCase myField}}with a context of{"myField":"SomE ValuE"}
Result: some value

set

Creates a new named value in the current context.

Given {{set "title" (upperCase myField) }}My title is{{title}}with a context of {"myField":"SomE ValuE"}
Result: My title is SOME VALUE

debug

The debug helper can be useful for testing and debugging a script by displaying the names and values in the current context of the script.

Given {{debug}}with a context of{"firstName":"foo","lastName":"bar"}

Results: Current context :{firstName=foo, lastName=bar}

Using loops in Handlebar helpers

See examples of how you can iterate over a list, also known as looping, by using the each basic helper.

Example of a loop

This example shows how to use loop scripting to display a hardware store’s inventory and pricing.

Given the following script

<html>
	<head>
		<title></title>
	</head>
	<body>Loop scripting example
		<br/>
{{#each items}}
    Name: {{itemName}}, Price: {{price}}
		<br/>
    {{else}}
    No items available.
		<br/>
{{/each}}
	</body>
</html>

With the following context

{"items": [
        {"itemName":"hammer","price":"10.49"},
        {"itemName":"screwdriver","price": "11.19"}]}

Result

<html>
	<head>
		<title></title>
	</head>
	<body>Loop scripting example
		<br/>
Name: hammer, Price: 10.49
		<br />
Name: screwdriver, Price: 11.19
		<br/>
	</body>
</html>

Example of Nested Loops

The below example illustrates the power of message scripting. The key is to have the right script context as the model for your scripting code.

Given the following script

<html>
	<head>
		<title></title>
	</head>
	<body>Nested loop scripting example
		<br/>
    {{#each departments }} 
    Department: {{name}}
		<br />
    {{#each items}}
        {{#if special}}
		<span style="color:#FF0000;">Sale !!</span>;
        {{/if special}}
        Name: {{itemName}}, Price: {{price}}
		<br />
        {{else}}
        No items available for this department.
		<br/>
    {{/each}}
    {{/each}}
	</body>
</html>

With the following context

{"departments": [
     {"name": "Hardware",
          "items": [
        {"itemName":"hammer","price":"10.49","special":"sale"},
        {"itemName":"screwdriver","price": "11.19","special":""}]},
     {"name": "Candy",
          "items":[
     {"itemName":"ButterBits","price":"3.49","special":"sale"}]},
     {"name": "Housewares", "items":[]}
    ]}

Result

<html>
	<head>
		<title></title>
	</head>
	<body>Nested loop scripting example
		<br />
Department: Hardware
		<br />
		<span style="color:#FF0000;">Sale !!</span>
Name: hammer, Price: 10.49
		<br />
Name: screwdriver, Price: 11.19
		<br />
Department: Candy
		<br />
		<span style="color:#FF0000;">Sale !!</span>
Name: Butter Bits, Price: 3.49
		<br />
Department: Housewares
		<br />
No items available for this department.
		<br/>
	</body>
</html>

Using comments in helpers

Text inside these mustaches {{!– –}} or {{! }} are comments that will not show in the rendered message. Any comments that contain }} or other scripting tokens should use the {{!– –}} syntax.

Updated almost 2 years ago