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 the Helper. It returns the current date. (This Helper is provided by OL Connect.) 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".

You could also create custom Helpers, for example, a Helper that returns tomorrow's date. To learn how to create this and other custom Helpers, see Creating custom Helpers.

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.

counter

Some types of documents must contain a sequential number. Think of labels and raffle tickets. The counter helper generates sequential numbers that update for each record in the main data set.

The helper can take the following parameters. Note that all parameters are optional. If a parameter is omitted, the default value is used.

• start: The starting number. Default value: 1.

• step: The increment for the counting sequence. Default value: 1.

• pad: The number of digits the counter will have. If this number is larger than the current counter value, the padding character will be added to the left of the counter value, until its width is equal to the set value. Default value: 0 (no padding).

• padChar: The character to use for padding. Default value: '0'.

Example:

Tip: If you need to write a custom counter, this How-to will get you started: Handlebars helper: counter.

Date: today

OL Connect provides a Helper that returns the current date: today.

As parameter it accepts a locale: a language code followed by a 2-letter country code (de-DE, zh-CN, fr-CA, fr-FR, etc), as defined by the international standards ISO-639-1 and ISO 3166.

In addition, you can use a format Helper to format the date; see Date and time Helpers.

Example: {{dateShort today "en-US"}}

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 Helpers

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

Helpers that work with numbers:

• 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

Helpers that work with text strings:

• concat - merges two or more string values into a single string and returns the result.

• 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.*'}}

How to use these Helpers

These Helpers 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'.

Note: In OL Connect (as opposed to the original Handlebars library), numbers in Handlebars expressions do not need to be surrounded by quotes. For example, to calculate 1+2 you can write (add 1 2) instead of (add "1" "2").

Block Helpers

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

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

With Block Helpers it is possible to use conditions and create loops in an expression, for example to display content only if a field has a certain value.

Handlebars offers a number of built-in Block Helpers. 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.

  Note: Instead of creating table rows with #each, it is highly recommended that you use the built-in Dynamic Table feature.

• #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.

Note: Good to know when you are using #if or #unless: 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.

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: Since content provided by a Block Helper is not HTML-escaped in OL Connect, Handlebars' SafeString class is not needed and therefore not supported.

Variations with {{else}}: else if

Handlebars does not have a helper for case or switch statements. Instead, you can combine else with another helper. For example: {{else if <condition>}}.

{{#if eq policy "a"}}
    Policy A
{{else if eq policy "b"}}
    Policy B
{{else if eq policy "c"}}
    Policy C
{{else}}
    Policy D
{{/if}}

The syntax is: {{else <helper> <args>}}.

The helper that follows else will usually be if, but you can use any helper. For example, you can use unless to invert the condition: {{else unless <condition>}}, or even use a custom helper.

Where to use Block Helpers

It is recommended to only use Block Helpers in a Handlebars snippet (see Handlebars templates).

This is because in the Designer, sections are edited with an HTML editor which will interpret special characters as HTML, like the / in a Block Helper such as {{if}} ... {{/if}}.

HTML mixed with Handlebars expressions is not necessarily valid HTML. Processing it with an HTML parser - like the editor in which sections are written - might break both the Handlebars expressions and the HTML. This happens, for example, when #each (a Handlebars Helper) is used to create table rows.
Consider creating a Handlebars template whenever you find yourself switching to Source view to insert expressions and HTML. The Handlebars template editor is a plain text editor, not an HTML parser.

Data variables

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

Tip: In Dynamic Tables it is possible to target the first or last row, or to show the index number of a row, using data variables. For examples, see Cells with expressions.

Note: 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.

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.

{{#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'.

<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.

{{#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}}