HTML Best Practices

This topic applies to

Applies to

SuiteCommerce | SuiteCommerce Advanced


Commerce templates use the Handlebars.js templating engine to keep the HTML (presentation layer) separate from any deeper code logic. These logic-less templates help you build your themes without requiring access to deeper code. Templates define the HTML for specific areas of the user interface, such as a button or Home banner.

When an associated theme is activated, the template engine combines all of these files into a single, finished web page. To achieve this, templates use an easy-to-understand syntax, which is a combination of HTML and Handlebars.js expressions (helpers). These helpers tell the templating engine to include the value of variables (properties and objects) when rendering your site or executing functions. These variables are specific to each template, depending on what the template is designed to render. This information is called the template’s context.

Template Context

Each template relies on its context to know what variables are available (what data the template can render). You cannot customize a template to render information it cannot provide. Therefore, you must operate within this context when making any customizations to pre-existing templates or introducing your own.

Commerce templates include a list of context variables within the file itself. This lists the context objects, types, or any properties as part of an array. This information is nested within comment blocks at the end of each file.


If you are an extension developer making a template for an extension, the context is defined by your own custom views. See Extensibility API Tutorials for details.


SuiteCommerce Advanced users have access to the context within the associated view files.

The following example from case_list.tpl depicts this context notation.

... {!---- Use the following context variables when customizing this template: pageHeader (String) hasCases (Number) isLoading (Boolean) showPagination (Boolean) showCurrentPage (Boolean) showBackToAccount (Boolean) ----}}

The following code snippet depicts the hasCases number and isLoading boolean variables as used in the case_list.tpl template code. This code either renders a support case list or renders a Loading or No Cases Found string, depending on the query results.

... {{#if hasCases}} <table class="case-list-recordviews-table"> <thead class="case-list-content-table"> ... </thead> <tbody data-view="Case.List.Items"></tbody> </table> {{else}} {{#if isLoading}} <p class="case-list-empty">{{translate 'Loading...'}}</p> {{else}} <p class="case-list-empty">{{translate 'No cases were found'}}}</p> {{/if}} {{/if}} ...

To find the template context in a template file:

  1. In an editor, open the source .tpl file for the template you intend to customize.

  2. At the end of the file, look for the following string, located within comment tags:

    {{!-- Use the following context variables when customizing this template: ...
  3. Note the context variables available to the template and customize accordingly.

To find the context variables using the browser developer tools:

At this time, some template files do not include this context as described above. In these cases, you can use the {{log this}} helper as described below. This procedure assumes that you have already begun customizing a template. Do not edit source files directly.


The examples in this section uses Google’s Chrome browser developer tools.

  1. Open the template file you are customizing in an editor.

  2. Include the following helper as the first line in the template for which you want to reveal the context.

    {{log this}}
  3. Deploy your customization to your local server. See Test a Theme on a Local Server.

  4. Navigate to the page rendering your custom template.

  5. Using your browser’s developer tools, inspect and refresh the page.

  6. The developer tools Console tab lists the variables available to the template as the output of the {{log this}} helper: