Using functions in expressions: Helpers

Note: The information in this Online Help focuses on the implementation of Handlebars in OL Connect. For general information about Handlebars and how to use it, see the following web sites: https://handlebarsjs.com/ and https://devdocs.io/handlebars.

Functions that can be used in a Handlebars expression are called Helpers.

Example: {{dateLong DueDate}}

In this example, dateLong is the name of one of the Format Helpers in OLConnect, and DueDate is the name of a data field. When the template is merged with data, this expression returns the value of the DueDate field, formatted as a long date, e.g. "February 23, 2022".

Anything that follows a Helper in an expression is passed to the Helper as a parameter.
The parameter doesn't have to be a data field. It can also be another Helper that returns a value. This is called a subexpression.

Example: {{dateLong today}}

In this example, today is the name of a Helper that returns the current date. The current date is then passed to dateLong, so that this expression returns the current date formatted as a long date, e.g. "February 23, 2022".

Note that today is not a Helper that is provided by OL Connect; it is a custom Helper. To learn how to create this and other custom Helpers, see Creating custom Helpers.

Subexpressions are delimited by parentheses.

{{#if eq a b}}.

{{#if (eq a b)}} but now those parentheses are optional.

Note: Expressions are evaluated from right to left.

Subexpressions can, but don't have to be, delimited by parentheses. For example, {{#if eq a b}} and {{#if (eq a b)}} are both valid.

Formatting

OL Connect provides a number of Helpers to format the value that is the result of an expression. For a list, see Format Helpers.

Logic

OL Connect has a number of additional Helpers that allow for the use of logic in expressions.

  • eq (equal), neq (not equal) - tests two values for equality

  • gt (greater than), gte (greater than or equal), lt (lower than), lte (lower than or equal) - compares two number values

  • not, or, and - logical operators

  • add - adds two number values

  • sub - subtracts two number values

  • mul - multiplies two number values

  • div - divides two number values

  • startsWith - tests if a string starts with a certain prefix

  • endsWith - tests if a string ends with a certain suffix

  • matches - tests if a string matches a regular expression

    Note: The matches helper tries to match the entire input string. This means that expressions like {{matches 'contains a fox' 'fox'}} will return false. To get matches to look for substrings and have the expression return true, the regular expression must have .* before and after the substring: {{matches 'contains a fox' '.*fox.*'}}

These can be used as expression (returns the result).

Example: <p>Recurs every month: {{eq 'Monthly' recurrence}}</p>

This expression returns "true" if the value of the data field recurrence is 'Monthly'.

They can also be used in subexpressions, for example of a Block Helper.

Example: <p> {{#if (eq 'Monthly' recurrence)}} Recurs every month {{/if}} </p>

This Block Helper outputs "Recurs every month" if the value of the data field recurrence is 'Monthly'.

Block Helpers

Block Helpers are a special kind of Helpers. They look like this:

{{#helperName arguments}} ... {{/helperName}}

Handlebars offers a number of built-in Block Helpers that let you use logic in templates. They are documented on Handlebars' website: https://handlebarsjs.com/guide/builtin-helpers.html.

Of those Helpers, the following are supported in OL Connect:

  • #if: Conditionally renders a block. An optional {{else}} section inside the block will display when the condition is not true.

  • #unless: Renders a block if the expression returns a falsy value (i.e. a value that is considered false when encountered in a Boolean context). An optional {{else}} section inside the block will display when the condition is true.

  • #each: Allows to iterate over a list. An optional {{else}} section inside the block will display when the list is empty.

  • #with: Can be used to work directly with the passed object or object property. An optional {{else}} section will display only when the passed value is empty.

In Block Helpers, the data variables @first, @last, @index can be used; see https://handlebarsjs.com/api-reference/data-variables.html.

Unlike in the original Handlebars library, content provided by a Block Helper is not automatically HTML-escaped in OL Connect. Blocks are typically used to generate HTML, so it is assumed that the result consists of well-formed HTML.

Note: If Block Helpers are used in a section, editing in Preview mode is not supported. Any changes made in Preview mode are reverted when you switch back to Design mode.

Note: An empty array is considered falsy (i.e. evaluated as false). This is normally not the case in JavaScript, but the Handlebars library makes an exception.

The data variable @key is not supported in OL Connect. OL Connect only supports iterating over arrays and tables, not over arbitrary objects.
Navigating to a parent scope with something like @../index is also not supported.

Since content provided by a Block Helper is not HTML-escaped in OL Connect, Handlebars' SafeString class is not needed and therefore not supported.

Examples of Block Helpers

#if

The following #if block will output a table row with two cells if the data field named O_L10095 is not false, undefined, null, 0, an empty string, or an empty array.

Copy 
{{#if O_L10095}}
<tr>    
    <td>Collective insurance</td>    
    <td>{{O_L10095}}</td>
</tr>
{{/if}}

#unless and #each

The following Handlebars template outputs a row with a header and a variable number of clause descriptions, based on a detail table called 'Clause', unless there are no clauses, in which case the row gets a header and one cell that displays the text 'None'.

Copy 
<table class="policy-table">
<tbody>
{{#unless Clause}}
<tr>    
    <th class="h3">Clause(s)</th>     
    <td>None</td>
</tr>
{{else}}    
    {{#each Clause}}    
    <tr>        
        <th class="h3">{{#if @first}}Clause(s){{/if}}</th>        
        <td>{{Descr}}</td>    
    </tr>    
    {{/each}}
{{/unless}} 
</tbody>
</table>

#with and #each

This #with block calls a custom Helper (see Creating custom Helpers) that returns an object with the properties: object, amount, coverage and premium. The object's properties are accessed directly inside the block. The #with block is executed for each of the records in a detail table called insurance_coverage.

Copy 
{{#each insurance_coverage}}     
    {{#with (getObjectAndCoverage)}}     
    <tr>         
        <td>{{object}}</td>        
        <td class="curr">€</td>            
        <td>{{amount}}</td>         
        <td>{{coverage}}</td>         
        <td class="curr">€</td>         
        <td>{{premium}}</td>    
    </tr>    
    {{/with}} 
{{/each}}