Using Handlebars templates in a script

Handlebars expressions in an HTML snippet do not get replaced with values if the snippet is loaded through a script. Handlebars templates (also called Partials) 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 explained in this topic.

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

Inserting a Handlebars template using a script

It takes only two lines of code to replace the expressions in a Handlebars template with values and add the result 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 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.

   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.

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.

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.

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.

With Handlebars templates there are multiple ways to do this; see XXX.

This is an example of a script that dynamically loads Handlebars templates:

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