Handlebars templates

Since version 2022.1, OL Connect has a special kind of snippets called Handlebars templates. Just like other types of snippets (see Snippets), Handlebars templates are stored in the Snippets folder on the Resources pane, but their file name ends in .hbs.

Handlebars templates look like regular text with embedded Handlebars expressions. A Handlebars expression is some contents enclosed by double curly braces: {{ ... }}. For example: <p>Hello {{firstname}}!</p>

Why use a Handlebars template?

As of version 2022.2, you can use Handlebars expressions in all sections (see Handlebars in OL Connect and Variable data in text: expressions.). Nevertheless, in a number of cases it is better or even unavoidable to work with Handlebars templates.

  • If you want to load snippets with expressions dynamically through a script, this is a reason to use Handlebars templates. Expressions in an HTML snippet do not get replaced with values if the snippet is loaded through a script. Handlebars templates can be loaded through a script. They need to be rendered before they are added to a section. When a Handlebars template is rendered, the expressions are replaced with values from input data of your choice. How to do this is one of the things that is explained in this topic.

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

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.

Creating a Handlebars template

To create a new, empty Handlebars template:

  1. On the Resources pane, right-click the Snippets folder and select New Snippet.

  2. Select the type of snippet that you want to create: Handlebars template.

  3. Give the snippet a name.

  4. Double-click the new file to open it in the Designer and fill it with HTML text and Handlebars expressions.

The editor for Handlebars snippets does not have a Design view. HTML with Handlebars expressions is not necessarily valid HTML. Processing it with an HTML parser might break both the Handlebars expressions and the HTML.

More about expressions and the functions that you can use in expressions can be found in the topics Handlebars expressions and Using functions in expressions: Helpers.

Using a Handlebars template in a section

There are two ways to insert a Handlebars template in a section.

1. With an expression

In the section, write an expression that refers to the Handlebars template by name:
{{+ partialname}}.

The following expressions load the same Handlebars template from the Snippets folder:

  • {{+ snippets/mySnippet.hbs}}

  • {{+ mySnippet}}

Note: The original Handlebars expression to insert a Handlebars template in another Handlebars template uses a > (greather than) character. In OL Connect sections (since version 2023.1) this character must be replaced with +.

Relative paths (starting with snippets/) and arbitrary URLs (starting with file:// or http:// or https://) are supported.
The file name can be:

  • the name of an .hbs snippet in the template (for example: {{+ snippets/Snippet1.hbs}} or {{+ snippets/Snippet1.hbs}}

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

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

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"

2. Through a script

It only takes two lines of code to replace the expressions in a Handlebars template with values and add the result to a section.

If you are new to scripting in the Designer, first read: Writing your own scripts.

  1. On the Scripts pane, click on the black triangle next to the New button and select Standard Script.

  2. Give the script a name.

  3. Enter the selector that identifies the elements in the template for which the script should run. (See: Selectors in OL Connect.) For example, #Snippet1 refers to an element that has the ID Snippet1.

  4. Write a line of code that calls the function Handlebars.render(template, data).

    • The template can be the name of a Handlebars template (.hbs) stored in the template, on disk, or remotely (http:// or https://).

      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"

    • The data can be the current record or part of it, or a JavaScript object (which may include the record or part of it - see Handlebars API for an example).
      If no data is passed, the current record will be used.

    Example:
    var html = Handlebars.render( "snippets/policy-info.hbs", record );

    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.

  5. Write a line of code that adds the rendered HTML to the content of the section. The following script replaces the elements to which the script applies with the contents of the Handlebars template.

    Example: results.replaceWith( html )

  6. Save the script. Make sure that there is at least one element in the section that matches the selector of the script.

Alternative: compile and call the template

The render() function actually does two things:

  1. Compile the Handlebars template into a function

    When a Handlebars template is compiled, it is actually compiled into a JavaScript function.

  2. Call the function to replace expressions with data

    The second step is to call the resulting function, passing in some data. The function will replace the expressions with values from the data and will then return HTML.

Instead of calling Handlebars.render() you could call Handlebars.compile() and then call the resulting function.

Example: var myFunction = Handlebars.compile( "snippets/policy-info.hbs", record);
let html = myFunction( record );
results.replaceWith( html )

Handlebars sample code from an online source will use the two separate steps since Handlebars.render() is only available in OL Connect.

See also: Handlebars API.

Loading Handlebars templates dynamically

To load partials dynamically, based on data, you could use a Block Helper in the section, such as {{if}} ... {{/if}} (see Block Helpers and the examples in this topic).

It is also possible to dynamically select a Handlebars template by using a sub expression between parentheses. The sub expression should evaluate to the name of a partial.
For example, if whichPartial is a function that returns the name of a partial, {{+(whichPartial)}} in a Handlebars template calls whichPartial and then renders the partial whose name is returned by this function. Note that to use a function in this way, it must be registered as a Helper; see Creating custom Helpers.

Last but not least, Handlebars templates can be loaded dynamically in a script. With JavaScript it may be easier to set up the right conditions. Just make sure that the templates are rendered before they are added to the template.

Adding Handlebars templates through script: examples

Rendering a Handlebars template repeatedly

This script loops over a detail table called Policies, each time passing different data to the same Handlebars template.

Copy 
let policies = record.tables.Policies;
let html = '';
for( var i = 0; i < policies.length; i++) {
html += Handlebars.render( 'snippets/policy.hbs', policies[i] );
}
results.replaceWith( html );

Selecting a Handlebars template based on a data field

An approach that is also used with HTML snippets is to use the value of a data field in the current record to determine the name of the Handlebars template to use.

This is an example:

Copy 
let html = ''
let policydata = record.tables.Policy
for (var i=0; i < policydata.length; i++) {    
    let templateName = 'snippets/' + policydata[i].fields['snippetName'] + '.hbs'     
    html += Handlebars.render( templateName, policydata[i] )
}
results.replaceWith( html );