Handlebars.js Template Context in SuiteCommerce Customization

TL;DR Opening

Commerce templates in SuiteCommerce utilize the Handlebars.js templating engine, allowing developers to separate HTML presentation from the underlying logic. This separation is crucial for building themes while maintaining access to necessary data. Understanding template context is essential for effective theme customization.

What is Template Context?

Template context refers to the variables and data that a specific template can render. Each template defines its context, setting the scope of available variables. Customizing a template requires an understanding of this context, as you can only use the variables defined within it.

How Are Templates Structured?

Templates employ a mixture of HTML and Handlebars.js expressions. The latter are known as helpers and dictate how the template interacts with the underlying data. When a theme is activated, the template engine compiles these components into a cohesive web page. The context often includes crucial data points necessary for rendering elements dynamically.

Example of Template Context

In the following example from the case_list.tpl template, you can see the context defined:

1{!----
2Use the following context variables when customizing this template:
3   pageHeader (String)
4   hasCases (Number)
5   isLoading (Boolean)
6   showPagination (Boolean)
7   showCurrentPage (Boolean)
8   showBackToAccount (Boolean)
9----}}

This indicates the variables you can utilize, such as hasCases and isLoading.

Rendering Logic Based on Context Variables

Here's a snippet showing how these context variables can be incorporated:

1{{#if hasCases}}
2      <table class="case-list-recordviews-table">
3         <thead class="case-list-content-table">
4         ...
5         </thead>
6         <tbody data-view="Case.List.Items"></tbody>
7      </table>
8{{else}}
9      {{#if isLoading}}
10          <p class="case-list-empty">{{translate 'Loading...'}}</p>
11      {{else}}
12         <p class="case-list-empty">{{translate 'No cases were found'}}</p>
13      {{/if}}
14{{/if}}

This example checks if cases exist and renders a table or appropriate messages accordingly.

Finding Template Context

To discover the context variables in a template file, follow these steps:

1. Open the .tpl file in your editor.
2. Look for comment tags that list context variables at the end of the file:
   htmlCopy

   {{!--
   Use the following context variables when customizing this template:
   ...

3. Reference these variables for your customization.

Using Browser Developer Tools to Reveal Context Variables

If context variables are not listed in the template, you can reveal them using the {{log this}} helper. Follow these steps:

1. Add {{log this}} as the first line in your template.
2. Deploy the customization to your local server.
3. Open the page in your browser and access the developer tools Console tab. The available context variables will be printed there for further exploration.

Who This Affects

• Developers: Those creating or customizing SuiteCommerce themes will need to understand template context.
• SuiteCommerce Advanced Users: Access to context variables within associated view files is critical.

Key Takeaways

• Template context is essential for customizing SuiteCommerce templates effectively.
• Use the structure and context helpers provided by Handlebars.js for dynamic rendering.
• Always reference the context variables defined within the template for valid customizations.

Source: This article is based on Oracle's official NetSuite documentation.