Creating custom Helpers

A Helper is a function that can be used in an expression.

In both Handlebars and OL Connect, a number of Helpers are predefined (see Using functions in expressions: Helpers), but you can also create your own Helpers. (See the Handlebars guide: https://handlebarsjs.com/guide/#custom-helpers.)

This topic explains how to create a custom Helper in OL Connect.

Let's say you want to create a custom Helper that returns the current date. The name of the Helper should be today, so that it can be used in an expression as follows:

Example: {{today}}

Here's how you do that.

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

    Control Scripts are executed first. See Control Scripts and The script flow: when scripts run.

  2. Enter a name for the script in the Name field. This name will appear on the Scripts pane. It doesn't have to be the same as the name of the Helper that can be used in expressions. One Control Script can register multiple Helpers.

  3. Write code that registers the Helper, using the Handlebars.registerHelper(name, helper) function .

    • name is the name of the Helper by which it should be called in expressions. Put the name in quotes.

    • helper is the code that should run when the Helper is called from an expression.

    Here is an example:

    Copy 
    Handlebars.registerHelper('today', function() {
    return new Date(); 
    });

  4. Click OK. The new script appears on the Scripts pane in the Control Scripts folder.

Now that the Helper is registered, the expression {{today}} in a template will return the current date.

In the same expression you could use a Helper that formats the date. For example: {{dateLong today}} will format the current date as a long date, e.g. February 23, 2022. (For a list of Format Helpers, see Format Helpers.)

If you'd like to format the value in the script itself, you can use the functions provided by the formatter object in standard Designer scripts; see formatter.

For example, this code registers a Helper that formats the output as a 'medium' date.

Copy 
Handlebars.registerHelper('today', function () {
let today = new Date();
return formatter.dateMedium( today )
})

 

Note: There are a few differences between the official Handlebars library and OL Connect. In OL Connect:

  • The blockHelperMissing and helperMissing hooks are not implemented.
  • Passing options.hash, options.helpers and options.partials arguments to Helpers is not supported. (options.data, options.fn and options.inverse are supported.)
  • Registering multiple Helpers with a single call to Handlebars.registerHelper() is not supported.

Examples of custom Helpers

Coloring a negative value

Values in your data could be positive or negative. Let's say you want a Helper that colors any negative values red. Here's the code for such a Helper.

Copy 
Handlebars.registerHelper('highlightNegative', function ( value ) {
let result = value
if( -1 === Math.sign(value) ) {
    result = '<span style="color:red">' + value + '</span>';
    }
return new Handlebars.SafeString(result);
})

The name of the Helper is highlightNegative. The Helper checks whether the value that it gets passed by an expression is negative, using a JavaScript function: Math.sign() (see the documentation of Mozilla). If it is, it wraps the value in a Span with a style attribute that has some CSS to color the value red.

Once you've added this Helper, it can be used in any expression that returns a number value.

Example: {{highlightNegative Total}}

This expression calls the Helper with the name of a data field, Total, that has a number. If the value of the data field is -15, the output of this expression will be -15.

Inserting a hyperlink

Let's assume you have hyperlinks in your data as well as texts to use as label for the hyperlinks. For example:

[
{
"url": "http://www.nu.nl",
"label": "nu.nl"
}
]

The following code registers a Helper called makeHyperlink that will turn these values into a hyperlink in the text.

Copy 
Handlebars.registerHelper('makeHyperlink', function () {
let result = `<a href="${this.url}">${this.label}</a>`;
return new Handlebars.SafeString( result );
})

In the template you would call the function in an expression.

Example: Go to {{makeHyperlink}}

HTML-escaping in a Helper

If a Helper needs to HTML-escape a string you can call Handlebars.escapeExpression() in that function.
For example, if you would want to HTML-escape the value of this.field, but not "<p>" or "</p>", you could write:
function() { return "<p>" + Handlebars.escapeExpression(this.field) + "</p>"; }

Note: As a rule of thumb, put as much content in the template as possible and let Helpers generate as little content as possible.