Handlebars expressions

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.

Data in expressions

A handlebars expression is some contents enclosed by double curly braces: {{...}}.
For example: Hello {{firstname}}!

In its most simple form the contents of the expression refer to a data field. They will be replaced with the value of that field if it exists in the data that is passed to the template.

  • Expressions in sections are always resolved using the current record with which a template is merged. In other words, the input object is the current record.

  • In the case of Handlebars snippets, you determine in a script with which data the snippet will be merged. See Handlebars templates for instructions.

Expressions are inserted in sections and Handlebars templates the same way; see Variable data in text: expressions.

It is possible to use logic in an expression, for example to display content only if a field has a certain value. How this is done is described in another topic: Block Helpers.

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

Accessing data at different levels

A field or key name without a . or / is assumed to refer to a field or table at the root of the data with which the template is rendered. There are a number of ways to access data that is not located at the root.

  • With . or / you can navigate down into the record or object. For example: {{Cars.Brand}} and {{Cars/Brand}} refer to the same field.
    Note that to access an item in a detail table or array directly, you also have to navigate down. For example: Cars.Brand.Models[0] refers to the first item in Models. Alternatively you can write: Cars.Brand.Models.0

  • @root represents the top level of the data.
    If a template is rendered with the current record or part of it, @root refers to the root of the current record.
    With a JavaScript object, @root refers to the root level of the data that was passed to the Handlebars template.

  • The built-in helpers #each and #with dive into an object-property, giving you direct access to its properties. (See Using functions in expressions: Helpers and the documentation of Handlebars.)

  • Use ../ to navigate one level up. This is particularly useful in #each and #with blocks.

    Note: If a Handlebars template is rendered with part of the current record, the template still has access to the entire record and can navigate up and outside of that part, to a higher level in the current record.
    If a JavaScript object is passed, the template only has access to the passed data, and it does not have access to the current record.

Note: Navigating to a parent scope with something like @../index is not supported.

Formatting values

Functions that can be used in a Handlebars expression are called "Helpers". OL Connect provides a number of Helpers to format the value that is the result of an expression. For example: {{upperCase FirstName }} returns the value of the FirstName data field in uppercase.

The available functions are listed in the topic: Format Helpers.

HTML values

The value returned by an expression is HTML-escaped. This means that characters that have a special function in HTML: & < > \" ' ` = are replaced with HTML character references. For example: & will be changed into &amp;.

Take this expression: <span>{{foo}}</span>.
If the field foo contains a '>' and you don't HTML-escape it, this would produce invalid HTML: <span>...>...</span>.
After HTML-escaping, it becomes valid HTML: <span>&gt;</span>.

If the result of an expression should not be HTML-escaped, the expression must be enclosed in three curly brackets: {{{ ... }}}. Characters with a special function in HTML will then be interpreted as HTML. For example, the value "<b>Name</b>" will be displayed as Name.

When an HTML field is dragged into a Handlebars template it is automatically enclosed in three curly brackets.

Note: Content provided by 'block helpers' - expressions in the form {{#helperName arguments}}...{{/helperName}} - is not automatically HTML-escaped. See Using functions in expressions: Helpers.

Testing expressions

To test whether expressions give the expected result, simply switch to Preview mode in the Workspace. You could also do a Preflight to test with multiple records (see Doing a Preflight).

Logging

Values can be logged with an expression that uses the log Helper. For examples see Handlebars' documentation.

Note: In OL Connect it isn't possible to set a log level for the Helper. The log level is always 'info'.

Log messages will appear in the Messages pane (see Preflight Results and Messages).

Escaping Handlebars expressions

Handlebars content may be escaped - i.e. displayed as is, without evaluating the expression - by prefixing it with \ (a backslash). For example: \{{FieldName}} will show up in the output as {{FieldName}}, instead of being replaced with the value of the data field FieldName.

Raw blocks - Handlebars expressions with four curly braces at the start and end - are not supported.