Handlebars API

This topic lists the functions of Handlebars that are supported in Designer scripts. It also lists features that are unsupported in OL Connect.

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

Function Description
compile('template')

Compiles the specified Handlebars template* into a function that can be called with data**. For example:

const template = Handlebars.compile('snippets/Template1.hbs');

const result = template(record);

Note: Passing options is not supported in OL Connect.
render('template', data)

Renders a specified Handlebars template* by compiling the specified Handlebars template into a function and immediately calling that function with data**. 

Handlebars.render( "snippets/Template.hbs" )
is identical to: 
const compiledTemplate = Handlebars.compile( "snippets/Template.hbs" ) 

compiledTemplate( record )

If data is passed, that data is used to render the template.

If no data is passed, the current record is used to render the template.

The result of this function is HTML.

See also: Handlebars templates.

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.

registerHelper('name', helper)

Registers a function as Helper with the specified name.

Here is an example:

Copy 
Handlebars.registerHelper('today', function() { return new Date(); });

See: Creating custom Helpers.

Note: Registering multiple Helpers with a single call to registerHelper() is not supported.

escapeExpression()

HTML-escapes the supplied string. 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;.

See also: HTML values.

This function does the same as escapeHTML(), which was introduced in OL Connect 2022.1 and is now deprecated.

* template

In all these functions, 'template' can be:

  • the name of an .hbs snippet in the template (for example: snippets/Snippet 1.hbs

  • the name of an .hbs snippet on disk (starting with file:///)

  • the name of a remote .hbs snippet (starting with http:// or https://)

  • a string that contains HTML and Handlebars expressions.

With a snippet on disk, the complete syntax is: file://<host>/<path>. If the host is "localhost", it can be omitted, resulting in file:///<path> - note the three forward slashes after file:.
In the remainder of the path you can either use escaped backward slashes:
"file:///C:\\Users\\Administrator\\Desktop\\Handlebars_LoadFile.hbs"
or forward slashes:
"file:///C:/Users/Administrator/Desktop/Handlebars_LoadFile.hbs"

Note: It is not possible to use loadhtml() in Handlebars functions. HTML with Handlebars expressions is not necessarily valid HTML. Processing it with an HTML parser might break both the Handlebars expressions and the HTML.

** data

The data can be the current record or part of it, or another JavaScript object.

it is also possible to pass the record or part of it along with other data, since JavaScript objects may contain multiple objects. Here is an example.
The following script loads JSON and then passes that JSON and the current record to a Handlebars template.

Copy 
const myJson = loadjson('snippets/myJson.json');
Handlebars.render(myHandlebarsTemplate, { json:myJson, record:record })

Assuming the json in this example has a key called key1 and the record has a field called field1, expressions in the template could look like this: {{json.key1}} {{record.field1}}.

Unsupported features

The following features are not supported in Handlebars templates in OL Connect: 

  • The SafeString class. It is not needed since the result of a block helper is not HTML-escaped in OL Connect.

  • Inline escapes.

  • Raw block helpers.

  • Passing options when compiling a Handlebars template.

The following Handlebars helpers features are not supported in OL Connect.

  • In the log helper, only the info error level is supported.

  • The data variable @key. OL Connect only supports iterating over arrays and tables, not over arbitrary objects. (@first, @last, @index and @root are supported.)

  • Registering multiple helpers with a single call.

  • The blockHelperMissing and helperMissing hooks.

  • Passing options.helpers and options.partials arguments to helpers. (options.hash, options.data, options.fn and options.inverse are supported.)