Handlebars expressions

Data in expressions

A handlebars expression is a {{, some contents, followed by a }}.
For example:
<p>Hello {{firstname}} {{lastname}}!</p>

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 (see Render the Handlebars template).

You can simply write the field or key name in the expression. A whitespace before and after the field or key name is accepted, e.g. {{ fullName }}.

Another, quick way to insert a simple expression is to drag and drop the field from the Data Model in the Handlebars template.

When you drag and drop a field into a Handlebars template, a call to a function that formats the value may be added automatically. This depends on the field type.
For example, dragging a currency field will produce: {{currency fieldName}} which outputs a number formatted as an amount of money.
You can remove the function or change it (see Formatting values).

When a data field of the type HTML String is dragged into a Handlebars snippet, the expression gets three curly brackets to ensure that HTML characters are not escaped (see HTML values).

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: Using logic in a Handlebars template: helpers.

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.

• @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 logic in a Handlebars template: helpers and the documentation of Handlebars.)

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

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

Formatting values

Functions that can be called from 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 field in uppercase.

The available functions are the same as those provided by the formatter object in standard Designer scripts; see formatter.
Note that the names of these functions are case sensitive. For example, "upperCase" works, but "uppercase" does not.

The values will be formatted according to the rules of the current locale. See Locale.

HTML values

The value returned by an {{expression}} is HTML-escaped. This means that those 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: {{{ ... }}}.

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