Custom Handlebars Helpers Creation in SuiteCommerce

Creating custom helpers in SuiteCommerce can significantly improve the flexibility and functionality of your templates. This guide details the steps needed to define a simple custom helper using the Handlebars library, which is an important part of SuiteCommerce development.

What is a Custom Helper?

Custom helpers allow developers to create reusable custom logic that can be invoked directly in Handlebars templates. This enhances template functionality without cluttering the main template code.

Steps to Create a Simple Custom Helper

To create your helper, use the registerHelper() method from the Handlebars module.

1. Set Up Your Module Directory

Begin by creating a directory for your custom helpers within your extension. Your directory structure should look like this:

Workspace/
    MyExtension
        Modules/
            CustomHandlebarsHelpers/
                JavaScript/

2. Create the JavaScript File

Inside the JavaScript folder, create a file named CustomHandlebarsHelpers.js.

3. Add Handlebars as a Dependency

Ensure that Handlebars is included as a dependency in your CustomHandlebarsHelpers.js file.

4. Define Your Custom Helper

Use the following template to register your helper:

Handlebars.registerHelper('helperName', "text-purple-400">function(param1, param2) {
    // replace with your code
    // "text-purple-400">return appropriate value
});

For instance, if you want a helper that appends a string to a given input, your code will look like this:

1"text-purple-400">define('CustomHandlebarsHelpers', [
2    'Handlebars'
3], "text-purple-400">function (
4    Handlebars
5){
6    'use strict';
7 
8    Handlebars.registerHelper('isTheBest', "text-purple-400">function (name) {
9        "text-purple-400">return name + ' is the best!';
10    });
11});

For TypeScript implementations, you might write:

1/// <amd-module name="CustomHandlebarsHelpers"/>
2 
3"text-purple-400">import Handlebars = "text-purple-400">require('../../../Commons/Utilities/JavaScript/Handlebars');
4 
5Handlebars.registerHelper('isTheBest', "text-purple-400">function (name) {
6    "text-purple-400">return name + ' is the best!';
7});

Note: The import path for Handlebars can vary based on your specific module setup. There is no need for your module to include a mountToApp property when utilizing Handlebars directly.

5. Update the manifest.json

Don’t forget to update your manifest.json file to include your new helper file as a resource. This step is crucial for ensuring your helper gets loaded with the extension.

Testing Your Custom Helper

To verify that your helper works as intended, you’ll need to use the browser's developer console:

1. Start your local server to run your Commerce website.
2. Open the developer console in your browser.
3. Run the following code:

"text-purple-400">var Handlebars = "text-purple-400">require('Handlebars');
Handlebars.helpers.isTheBest('Pizza');

If set up correctly, executing that code should yield:

"Pizza is the best!"

For more complex helpers, it is advised to test them directly within a Handlebars template to ensure they work as expected.

This systematic approach to creating custom Handlebars helpers can enhance your SuiteCommerce extension's capabilities, making your templates more powerful and user-friendly.