Use Custom Handlebars Helpers

The SuiteCommerce templating engine is powered by the Handlebars templating language. One of the benefits of Handlebars is that it enables you to include helper functions that perform simple logic in your templates.

Handlebars helpers are JavaScript functions. You give a function a name and a callback, and it processes your data as you want. Handlebars include a number of built-in helpers, which you can read more about in the Handlebars documentation. SuiteCommerce includes proprietary helpers that are required for many features to function. If you are working with a SuiteCommerce Advanced (SCA) implementation, you can find these proprietary helpers in the HandlebarsExtras module in the SCA source files.

This topic describes how you can write custom helpers that go beyond the built-in helpers offered by Handlebars and the proprietary ones available with SuiteCommerce bundles.

Read the following sections for more information and examples:

Considerations
Create a Simple Custom Helper
Create a Block Helper
Use Helpers for Debugging

Considerations

Before adding custom helpers, consider whether helpers are the best way to accomplish your goal. One of the primary objectives of SuiteCommerce website architecture is to keep the templates (presentation layer) separate from any deeper code logic. If you’re writing a pure Handlebars helper, ask yourself whether it should be a helper. If the necessary logic can reside in a view or a model, it likely should.

Another thing to keep in mind is whether you need a particular transformation to occur in the template. By creating a helper, you make the function you write available globally across templates. If a helper is only going to be used in one place, you might think about modifying the associated view’s context object so that the transformation occurs there instead.

Create a Simple Custom Helper

The registerHelper() method on the Handlebars module is the main mechanism needed to create a helper and it operates like this:

Handlebars.registerHelper('helperName', function(param1, param2, etc)
{
    // Your code
    // return your value
});

To create a helper in an existing extension, follow these steps:

In your extension, create a new module directory named, CustomHandlebarsHelpers. Include a JavaScript folder within this new module directory so that your new extension files resemble this example:
```
Workspace/
    MyExtension
        Modules/
           CustomHandlebarsHelpers/
              JavaScript/ 
```
In the JavaScript folder shown in the preceding example, create a JavaScript file named CustomHandlebarsHelpers.js.
In the CustomHandlebarsHelpers.js file, add Handlebars as a dependency.
In the CustomHandlebarsHelpers.js file, use Handlebars.registerHelper() to define a new helper.
1. Give your helper a unique name.
2. Define the parameters for the helper, which are the values you expect to pass to it.
3. In the callback, include the code to perform the transformation.
4. Return the value.

When complete, your code should resemble the following sample:

define('CustomHandlebarsHelpers', [
    'Handlebars'
], function (
    Handlebars
){
    'use strict';

    Handlebars.registerHelper('isTheBest', function (name) {
        return name + ' is the best!'
    });
});

Or this example if you use TypeScript:

/// <amd-module name="CustomHandlebarsHelpers"/>

import Handlebars = require('../../../Commons/Utilities/JavaScript/Handlebars');

Handlebars.registerHelper('isTheBest', function (name) {
    return name + ' is the best!'
});

Note:

The path to Handlebars depends on where your extension resides. Also, remember that your custom module does not need to return an object that includes a mountToApp property for Handlebars. You are calling the Handlebars module directly and using a built-in method to modify the Handlebars object.

Edit the manifest.json file to include the new CustomHandlebarsHelpers.js file. For more information, see Edit the Extension Manifest.

Test the Simple Helper

The best way to test a simple helper is in your browser’s developer console. First, start your local server and then, navigate to the local version of your Commerce website. For step-by-step instructions, see Test an Extension on a Local Server.

When you have your local Commerce website running in a browser, open the developer console. Access the simple helper you created by entering code like the following:

var Handlebars = require('Handlebars');
Handlebars.helpers.isTheBest('Pizza');

If the helper is working properly, the developer console returns:

> "Pizza is the best!"

If the helper you develop is more complex, you should test it in a template.

Create a Block Helper

Custom block helpers let you define your own iterators and conditionals. The following example shows how to create a custom helper to determine if a passed string starts with a particular set of characters.

Consider the following sample helper code:

Handlebars.registerHelper('startsWith', function (prefix, text, options) {
    if (text.indexOf(prefix) === 0) {
        return options.fn(this);
    }

    return options.inverse(this);
});

This helper includes a custom if/else block. This sample completes the following actions:

Registers the startsWith helper
Passes three parameters:
- The prefix characters you want to check the passed string for
- The text string you want to check
- A hash of options, which Handlebars handles for you, including determining the output to show in the template
When invoked, this code uses indexOf to see if the starting point of the prefix is at the start of the main string:
- If it is there, returns the template code for the truthy part of the condition
- If it is not there, returns the template code for the falsy part of the condition

Test the Block Helper

Due to the complexity of this helper, you should test in a template. After adding the helper to a template, deploy the extension that contains the template and then activate the extension as described in Deploy an Extension to NetSuite. After you deploy the extension, you can fetch it and test it locally, as described in Test an Extension on a Local Server

When you have your local Commerce website running in a browser, open the developer console. Test the block helper you created by entering code like the following:

{{#startsWith 'Ste' 'Steve'}}
    <p>Steve? That's a great name!</p>
{{else}}
    <p>Well, that name is pretty good, but it's not Steve</p>
{{/startsWith}}

If you are working with a template that has access to the current user’s profile data, you could replace the 'Steve' parameter with something like, model.fullname.

Refer to the Handlebars documentation for more details about Block Helpers.

Use Helpers for Debugging

You can use helpers when debugging to print the content of objects to the developer console or to the page.

More recent versions of SuiteCommerce and SCA have a built-in helper called, log. You can use the log helper as shown in the following samples:

To log the view’s context object: {{log this}}

Note:
In the preceding sample, this is contextual and so it will change value if, for example, you use it in an iterator or a block.
To log the model: {{log model}}

Also keep in mind that the templates provided in recent versions of SuiteCommerce and SCA list the properties that developers have sent to the templates. This means you can find the property names at the bottom of each template.