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.

now:

Outputs the current date and time.

The helper accepts optional parameters: format: A string used to specify a format using Luxon. locale: A locale string (for example en, nl) used for localized formatting.

If no format is provided, the helper outputs an ISO 8601 string. If no locale is provided, the default system locale is used.

Example template:

{{now}}

Example template using a format and locale:

{{now format="yyyy-MM-dd HH:mm" locale="nl"}}