Helpers

This section describes the available Handlebars helpers and their usage.

SubExpressions

Handlebars offers support for subExpressions, which allows you to invoke multiple helpers within a single mustache, and pass in the results of inner helper invocations as arguments to outer helpers. SubExpressions are delimited by parentheses.

{{outer-helper (inner-helper "abc") "def"}}

In this case, inner-helper will get invoked with the string argument 'abc', and whatever the inner-helper function returns will get passed in as the first argument to outer-helper (and 'def' will get passed in as the second argument to outer-helper).

Helpers

#if

You can use the if helper to conditionally render a block. If its argument returns false, undefined, null, "", 0, or [], the component will not render the block.

When using a block expression, you can specify an optional template section to run if the expression returns a false value. The section, marked by else is called an "else section".

Example if logic

<div class="entry">
  {{#if author}}
    <h1>{{firstName}} {{lastName}}</h1>
  {{else}}
    <h1>Anonymous</h1>
  {{/if}}
</div>

with input

{
  "author": true,
  "firstName": "Mike",
  "lastName": "Kat"
}

will output

<div class="entry">
  <h1>Mike Kat</h1>
</div>

#unless

You can use the unless helper as the inverse of the if helper. Its block will be rendered if the expression returns a falsy value. template

<div class="entry">
  {{#unless license}}
    <h3 class="warning">WARNING: This entry does not have a license!</h3>
  {{/unless}}
</div>

If looking up license under the current context returns a falsy value, Handlebars will render the warning. Otherwise, it will render nothing.

#xif

You can use xif for comparing logical expressions with multiple values. You can only use one expression per xif. To combine expressions you can define them nested.

Example:

{{#xif v1 "==" v2}}
  <div>V1 and V2 are equal</div>
{{/xif}}

You can also use the regular {{else}} section with xif.

Example:

{{#xif v1 "==" v2}}
  <div>V1 and V2 are equal</div>
{{else}}
  <div>V1 and V2 are not equal</div>
{{/xif}}

Other supported operators are

Equal (==)
Not equal (!=)
Greater than (>)
Greater than or equal (>=)
Less than (<)
Less than or equal (<=)
Logical AND (&&)
Logical OR (||)

note

Operators only work when they are between ' '.

To combine expressions you can define them nested.

#each

You can iterate over a list or an object using the built-in each helper. Inside the block, you can use this to reference the element being iterated over. The get the index, use @index or use @key instead when iterating objects.

Example each operator

<ul class="people_list">
  {{#each people}}
    <li>{{this}}</li>
  {{/each}}
</ul>

log

This feature has been disabled.

substring

Returns a sub-portion of a string.

Requires passing two parameters from and to.

Example template:

{{firstName}}{{substring lastName from=0 to=2}}

with input:

{
  "firstName": "Mike",
  "lastName": "Kat"
}

The value Kat will be cut to just Ka. will output:

Mike Ka

first and last

Returns the first or last element of an array.

The helpers have an optional parameter key, that allows you to specify a key to retrieve, in case the array contains objects.

Example template:

{{last addresses key="street"}}

with input:

{
  "firstName": "Mike",
  "lastName": "Kat",
  "addresses": [{"street": "Brooklyn road", "number": 10}, {"street": "Main street", "number": 35}]
}

The value of street in the last element of the addresses array is taken. will output:

Main street

join

Joins the values in an array and outputs them as a string.

The helper has an optional parameter key that allows you to specify a key to use when joining, in case the array contains objects. The separator parameter can be used to specify the separator, it defaults to ,.

Example template:

{{join addresses key="street" separator="/"}}

with input:

{
    firstName: "Mike",
    lastName: "Kat",
    addresses: [{street: "Brooklyn road": number: 10}, {street: "Main street": number: 35}]
}

The value of street in the last element of the addresses array is taken. will output:

Brooklyn road/Main street

stringify:

Returns a stringified version of the input. Use this helper when the input is anything other than a string or number. For example, when the input is an object, array, or boolean.

Syntax: {{stringify input}}

Short-hand syntax: {{$ input}}

note

When using Handlebars in the Template Engine and Parse JSON is enabled, it is recommended to use the stringify helper to avoid parsing errors.

md5:

Converts the string to MD5.

sha1:

Converts the string to SHA1.

sha256:

Converts the string to SHA256.

sha512:

Converts the string to SHA512.

toLowerCase:

Converts the string to lowercase.

toUpperCase:

Converts the string to the upper case.

trim:

Removes whitespace from both sides of the string.

toExt:

Returns the extension of the file name.

$root:

Returns the JSON stringified version of the whole incoming message. It should be used in combination with the HTML escaping syntax.

date:

returns an ISO date string. Mandatory when using Parse JSON option.