Template Compilation for Handlebars in SuiteCommerce Advanced

SuiteCommerce Advanced (SCA) utilizes templates to define the HTML code that shapes the user interface of its applications. These templates play critical roles, including defining raw HTML and containing placeholders that get replaced by data.

How Does Template Compilation Work?

Templates are compiled into usable JavaScript and HTML through a templating engine, with SCA specifically leveraging the Handlebars.js library. The templating engine performs the following core functions:

• Transforms the raw template files into JavaScript functions.
• Replaces placeholders with actual data passed to the templates.

Logic-less Templates Explained

One of the notable characteristics of this templating approach is its emphasis on logic-less templates. This means that all application logic is offloaded to the views, ensuring that the HTML code remains clean and understandable. This separation enhances modularity and maintainability, which is especially important during upgrades to newer SCA versions.

The Compilation Process

Each template source file includes raw HTML and Handlebars placeholders. During compilation, the gulp template command is invoked, which preprocesses each template into a JavaScript function. This function then integrates with the view rendering process when the application is active.

Example of Transformation: Here's how the compilation transforms various constructs:

• A conditional statement like:

  htmlCopy

  {{#if showLanguages}}

  Becomes:

  htmlCopy

  if(context.showLanguages){}

• A placeholder for user data:

  htmlCopy

  <p>my name is {{userName}}</p>

  Transforms to:

  htmlCopy

  function(context){var s = '<p>my name is'; s += context.userName; s += '</p>'; return s; }

Template and View Interaction

Since templates are devoid of application logic, all necessary data must be provided via a context object during rendering. The view.render method facilitates this by calling the template function with the context object, typically retrievable through the getContext method. For example:

"text-purple-400">var context = "text-purple-400">this.getContext();
body.innerHTML = "text-purple-400">this.template(context);

This code segment demonstrates how views embrace the context object to effectively populate templates. Normally, every view includes a getContext method that returns all requisite data properties for the template.

Why Template Context Matters

The context object ensures that customization doesn’t get overridden with version upgrades. While properties within the context object won’t be removed or altered, new properties may be added while ensuring backward compatibility. This continuity is crucial for maintaining customizations during updates.

Custom Handlebars Helpers

Handlebars.js provides built-in helpers, and SCA expands functionalities with custom helpers for varied tasks. Some notable custom helpers include:

• translate: Localizes strings while preserving formatting.
• formatCurrency: Formats currency values accordingly.
• highlightKeyword: Highlights relevant keywords.
• resizeImage: Constructs URLs for images based on defined dimensions.
• ifEquals: Enables equality checking within templates.

Key Takeaways

• SCA uses the Handlebars.js library for template compilation.
• Logic-less templates separate HTML presentation from application logic.
• Templates are compiled into JavaScript functions during the build process.
• Context objects ensure data consistency across upgrades.
• Custom Handlebars helpers enhance template functionalities.