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 resolved using the current record with which a template is merged. In other words, the input object is the current record. (See Variable data in text: expressions.)

  • Expressions in a Dynamic Table are resolved using the detail record associated with the closest table row. (Nested tables are supported, so a single dynamic table can use multiple detail tables.) See Dynamic Table.

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

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.

Template properties

A template's file properties are accessible in an expression via @properties.

Example: @properties.description

For a list of file properties see File Properties dialog.

Custom file properties are accessed via @properties.custom.

Example: @properties.custom.Name1

A section's meta properties

The @meta helper for Handlebars gives access to information stored in the section's meta property (see meta).

Use . to access fields in the meta property.

Example: {{@meta.title}}

Note: If a meta entry is added by a Standard Script, it cannot be accessed in a Handlebars expression, since Handlebars expressions are evaluated before Standard Scripts run.

Note: A section's meta property is not accessible to Handlebars expressions in a Handlebars template that is rendered using a Control Script (see Inserting a Handlebars template using a script). Use a Standard Script instead.

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.

Using logic in expressions

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. See Block Helpers.

OL Connect has a number of additional Helpers that allow for the use of logic in expressions. See Logic 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).

The first thing to do if an expression doesn't seem to be evaluated in a section, is to check whether evaluating Handlebars expressions is enabled for that section.

Note: In templates made with OL Connect 2022.1 or older, Handlebars expressions are not evaluated by default. To enable expressions in a section, right-click the section in the Resources pane, select Properties and check the option Evaluate Handlebars expressions.

Logging

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

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

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

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.