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.

Handlebars templates look like regular text with embedded Handlebars expressions. A handlebars expression is a {{, some contents, followed by a }}. For example:
<p>Hello {{firstname}} {{lastname}}!</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 this special type of snippets.

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

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 them can be found in the topic: Handlebars expressions.

Using a Handlebars template in a section

Although Handlebars templates contain HTML text, they cannot be inserted into the content of a section directly. The following steps need to be taken in order to replace Handlebars expressions with values and then add the content of a Handlebars template to a section.

Render the Handlebars template

First the template needs to be rendered, i.e. converted into HTML, replacing the expressions with values. This can be done with one line of code in a standard Designer script. Create a standard script and call the function:
Handlebars.render(template, data).

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

The template can be:

• the name of a Handlebars template (.hbs) in the template
• the name of a Handlebars template (.hbs) on disk (file:///)
• the name of a remote Handlebars template (.hbs) (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"

The data can be the current record or part of it, or a JavaScript object.
If no data is passed, the current record will be used.

Add the HTML to a section

Finally, the rendered HTML can be added to the content of a section.
For example: results.replaceWith( html )

Alternative: compile and call the template

The render() function actually does two things:

1. Compile the Handlebars template into a function
   

   Handlebars templates need to be compiled first. 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. For example:

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

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

See also: Handlebars API.

Using Handlebars templates: examples

Rendering a Handlebars template repeatedly

A Handlebars template is dynamic by nature. It is converted (compiled) to a JavaScript function. The Designer script that calls that function must pass data to it, and the result of the function will depend on that data. If the script calls that same function repeatedly, each time with different data - for example from a detail table -, the result of each call will be a different piece of HTML.

For example, this script loops over a detail table, each time passing different data to the same (compiled) Handlebars template.

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:

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