HTML Best Practices for Themes

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 template 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.

Each Commerce template includes a list of context variables within the file itself. The list includes 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.

Note:

If you are an extension developer making a template for an extension, the context is defined by your own custom views. See Work with Views in an Extension for details.

Note:

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

The following example from case_list.tpl shows 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 shows 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:

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

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

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

Note the context variables available to the template and customize accordingly.

To find the context variables using the browser developer tools:

Currently, some template files do not include the context. In these cases, you can use the {{log this}} helper.

This procedure assumes that you have begun customizing a template.

Open the template file you are customizing in an editor.

Note:
The examples in this section use Google’s Chrome browser developer tools.
Include the following helper as the first line in the template for which you want to reveal the context.
```
                 {{log this}} 

              
```
Deploy your customization to your local server. See Test a Theme on a Local Server.
Navigate to the page rendering your custom template.
Using your browser’s developer tools, inspect and refresh the page.
The developer tools Console tab lists the variables available to the template as the output of the {{log this}} helper:

Template Context

To find the template context in a template file:

To find the context variables using the browser developer tools:

Related Topics