Handlebars templates

In OL Connect, Handlebars templates are a special kind of snippets. 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 is the name of a JavaScript library that implements a templating language (see https://handlebarsjs.com/). It uses a template and an input object to generate output.

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

When the template is rendered, these expressions are replaced with values from an input object.

The Handlebars library is integrated in OL Connect Designer. This means that you can use Handlebars expressions in all sections (as of version 2022.2), as well as in a special type of snippets called "Handlebars templates" (as of version 2022.1).

The big advantage of using Handlebars snippets in OL Connect is that only one or two very simple Designer scripts are needed to replace a potentially large number of expressions with values and insert the content in a section. This is especially beneficial for OL Connect templates with many snippets and variable data that would otherwise require a large number of scripts.

Working with Handlebars templates involves a little bit of scripting. If you are new to scripting in the Designer, first read: Writing your own scripts.

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

Although Handlebars templates contain HTML text, they cannot be inserted into the content of a section as they are. The expressions would not be replaced with data.
What it takes is a short script that replaces the Handlebars expressions with values and then adds the content of the Handlebars template to a section.

  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 will identify elements in the template for which the script should run. (See: Selectors in OL Connect.)

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

    • The template can be:

      1. the name of a Handlebars template (.hbs) in the template
      2. the name of a Handlebars template (.hbs) on disk (file:///)
      3. the name of a remote Handlebars template (.hbs) (http:// or https://)
      4. 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"

    • 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 );

  5. Write a line of code that adds the rendered HTML to the content of the section.

    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.

Using Handlebars templates: examples

Rendering a Handlebars template repeatedly

This script loops over a detail table, 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 );