Handlebars

Overview

The Handlebars library, located in ./sidecar/lib/handlebars/, is a JavaScript library that lets Sugar create semantic templates. Handlebars help render content for layouts, views, and fields for Sidecar. Using Handlebars, you can make modifications to the display of content such as adding HTML or CSS.

For more information on the Handlebars library, please refer to their website at http://handlebarsjs.com.

Templates

The Handlebars templates are stored in the filesystem as .hbs files. These files are stored along with the view, layout, and field metadata and are loaded according to the inheritance you have selected in your controller. To view the list of available templates, or to see if a custom-created template is available, you can open your browser's console window and inspect the Handlebars.templates namespace.

Debugging Templates

When working with Handlebar templates, it can be difficult to identify where an issue is occurring or what a variable contains. To assist with troubleshooting this, you can use the log helper. The log helper will output the contents of this and the variable passed to it in your browser's console.

This is an example of using the logger in a handlebars template:

  {{log this}}

Helpers

Handlebar Helpers are a way of adding custom functionality to the templates. Helpers are located in the following places:

./sidecar/src/view/hbs-helpers.js : Sidecar uses these helpers by default
./include/javascript/sugar7/hbs-helpers.js : Additional helpers used by the base client

Creating Helpers

When working with Handlebar templates, you may need to create your helper. To do this, follow these steps:

Create a Handlebars helper file in the ./custom/ directory. For this example, we will create two functions to convert a string to uppercase or lowercase:

./custom/JavaScript/my-handlebar-helpers.js

  /**
 * Handlebars helpers.
 *
 * These functions are to be used in handlebars templates.
 * @class Handlebars.helpers
 * @singleton
 */
(function(app) {
    app.events.on("app:init", function() {

        /**
         * convert a string to upper case
         */
        Handlebars.registerHelper("customUpperCase", function (text)
        {
            return text.toUpperCase();
        });

        /**
         * convert a string to lower case
         */
        Handlebars.registerHelper("customLowerCase", function (text)
        {
            return text.toLowerCase();
        });

    });
})(SUGAR.App);

Next, create a JSGrouping extension in ./custom/Extension/application/Ext/JSGroupings/. Name the file uniquely for your customization. For this example, we will create:

./custom/Extension/application/Ext/JSGroupings/my-handlebar-helpers.php

  <?php

//Loop through the groupings to find include/javascript/sugar_grp7.min.js
foreach($js_groupings as $key => $groupings) {
    foreach($groupings as $file => $target) {
        if ($target == 'include/javascript/sugar_grp7.min.js') {
            //append the custom helper file
            $js_groupings[$key]['custom/JavaScript/my-handlebar-helpers.js'] = 'include/javascript/sugar_grp7.min.js';
        }

        break;
    }
}

Finally, navigate to Admin > Repair and perform the following two repair sequences to include the changes:
- Quick Repair and Rebuild
- Rebuild JS Groupings.

You can now use your custom helpers in the HBS files by using:

  {{customUpperCase "MyString"}} 
{{customLowerCase "MyString"}}