Handlebars templates

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: {{ ... }}.

Example: <p>Hello {{firstname}}!</p>

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.

In OL Connect, a Handlebars template may be included in a section (which itself functions as a Handlebars template) or in another Handlebars template.
In the Handlebars library, such Handlebars templates are referred to as partials.

Why use a Handlebars template?

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 snippets.

  • With Handlebars templates you can easily load content with expressions into your template dynamically, based on data.

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

    Handlebars templates can include other Handlebars templates - see Using Handlebars templates.

    Inline partials are supported as well. See the two examples at https://docs.w3cub.com/handlebars/partials#inline-partials.

Tip: To keep an overview you could group the Handlebars templates in a subfolder of the Snippets folder on the Resources pane.

Note: 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.

Note: There is no need to register a Handlebars template as a partial, like in the original Handlebars library. OL Connect automatically registers all Handlebars templates in the Snippets folder, so that they can be referenced in expressions by name, without path and extension.

Using Handlebars templates

To include a Handlebars template - a 'partial' - in either a section or another Handlebars template, write an expression that refers to it by name:

{{+partialname}}

Note: If the name of the partial contains a space, the space needs to be escaped. Either surround the name with quotes or replace the space with %20. For example, a partial called “par tial.hbs” can be referenced as follows: {{+par%20tial}} or {{+('par tial')}}.

The name can be:

  • The name of an .hbs snippet in the template's Snippets folder.

    Example: {{+Snippet1}}

    {{+snippets/Snippet1.hbs}} would also work, but the path and extension can be omitted.

  • The name of an .hbs 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:

    Example: "file:///C:\\Users\\Administrator\\Desktop\\Partial1.hbs"

    or forward slashes:

    Example: "file:///C:/Users/Administrator/Desktop/Partial1.hbs"

  • The name of a remote .hbs snippet (starting with http:// or https://). It could also be a URL that retrieves a Handlebars template from an endpoint.

    Example: {{+http://localhost:1880/policies?p=travel}}

Passing data

You could pass data to the partial using one or more hash arguments.

Example: {{+myPartial test=123}}

See Hash arguments.

Expressions inside a partial are resolved using the record, unless a custom context is passed to the partial. For example, if a field in your data has an address object, that object could be passed as follows:

Example: {{+myPartial address}}

When a partial is missing

If there is no partial with the specified name, Handlebars can generate some other content, called failover content. Failover content can be specified using block syntax. The expression that calls the partial is the start of a block. An expression with a closing tag and the name of the partial signals the end of the block. The content between these expressions will be used if the called partial is missing.

Example: {{#+ myPartial }} Failover content {{/myPartial}}

The expression in this example will render "Failover content" if no "myPartial" partial is found.

Loading Handlebars templates dynamically

There are several ways to load Handlebars templates - aka 'partials' - dynamically, based on data.

  1. You could use a Block Helper (see Using functions in expressions: Helpers).

    Tip: Partials can include other partials. To keep the template clean and clutter-free it's best to put the Block Helper itself in a partial as well.

  2. You could dynamically select a partial by using a sub expression between parentheses. The sub expression should evaluate to the name of a partial.

    Example: {{+ (whichPartial) }}

    • If whichPartial is a data field that returns the name of a partial, the template renders the partial whose name is found in the data field.

    • whichPartial could also be the name of a function. Note that to use a function in this way, it must be registered as a Helper. See Creating custom Helpers.

  3. Handlebars templates can also be loaded dynamically in a script. This requires the Handlebars templates to be rendered before they are added to a section. See Using Handlebars templates in a script.

  4. Instead of loading a different partial you could load the same partial and pass different data to it using one or more hash arguments. See Hash arguments.