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 Helper that returns tomorrow's date. The name of the Helper should be tomorrow, so that it can be used in an expression as follows:

Example: {{tomorrow}}

Tip: OL Connect provides a Helper that returns the current date: {{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.

      Tip: To make it easy to identify your own Helpers, you can start the name with a special character such as an underscore.

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

    Here is an example:

    Copy 
    Handlebars.registerHelper('tomorrow', function() {
        var tomorrow = new Date();
        tomorrow.setDate(tomorrow.getDate() + 1);
        return tomorrow;
    });

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

Now that the Helper is registered, the expression {{tomorrow}} in a template will return tomorrow's date.

In the same expression you could use a Helper that formats the date. For example: {{dateLong tomorrow}} will format the 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('tomorrow', function() {
    var tomorrow = new Date();
    tomorrow.setDate(tomorrow.getDate() + 1);
    return formatter.dateMedium( tomorrow );
});

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

Examples of custom Helpers

Format as currency or display "N/A"

You may want to format the value of a particular data field as a currency, or display N/A if it is not a positive value. Here's code that registers a Helper that only works for a data field called Total.

Copy 
Handlebars.registerHelper('checkValue', function(){

    let dataValue = parseFloat( record.fields.Total )
    let returnValue = 'N/A'
    
    if( dataValue > 0) {
        return formatter.currency( dataValue )
    } 
    
    return returnValue
})

The expression {{checkValue}} formats the value of the field Total. It cannot be used to format any other fields.

The same Helper could be written in a way that it can be used with any (numeric) data field.

Copy 
Handlebars.registerHelper('checkValue', function( val ){

    let dataValue = parseFloat( val )
    let returnValue = 'N/A'
    
    if( dataValue > 0) {
        return formatter.currency( dataValue )
    } 
    
    return returnValue
})

The expression that formats the value of the field Total would now be: {{checkValue Total}}. To use this Helper with other numeric data fields, simply replace Total with the name of the other data field.

If you only want to get "N/A" if the value is 0 or 0.0, and format both positive and negative values with a currency symbol, the code could check if the value is falsy:

Copy 
Handlebars.registerHelper('checkValue', function( val ){
    if(!val) {
        return 'n/a'
    } else {
        return formatter.currency( val )
    }
}

This code outputs the string ‘n/a’ if the value is falsy; otherwise it outputs the value, formatted as a currency.

The code can be made even shorter by using the conditional (ternary) operator, which is a short alternative to an if...else statement.

Copy 
return val ? formatter.currency( val ) : 'n/a'

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}}

Targeting the first and/or last item

A Helper can find the first item, last item and the index of the current item in an array via the options object. If a Helper is registered with options as the last parameter, the options object is automatically passed to the Helper when it is called.

This is an example of a Helper that uses options.data.first to display the first item in an array.

Copy 
Handlebars.registerHelper("showLabel", function( label, options ) {
    let myLabel = ""
    if (options.data.first) {    
        myLabel = "<b>" + this.label + "</b>";
    }
    return new Handlebars.SafeString(myLabel);
});

In a Dynamic Table, this Helper could be called from an expression in a cell.

Example: {{showLabel ../year}}

The above example passes the field year (from the main record) to the Helper. The The current detail table and the options object are passed to it automatically.

Note: In a Dynamic Table with expressions you can access these data variables in Block Helpers directly with @first, @last and @index.
Example: {{#if @first}}{{../year}}{{/if}}
See Editing cells in a Dynamic Table.

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.