Templates and the Template Context

SuiteCommerce Advanced (SCA) uses templates to define the HTML code used to display features of the application. Templates perform the following primary tasks:

Define the raw HTML code that displays the user interface of a browser-based application.
Contain placeholders that are replaced with data passed to the template.

Templates are compiled into functional JavaScript and HTML by a templating engine. SCA uses the Handlebars.js library to define templates and the template engine. The template engine performs the following tasks:

Transforms the raw template file into a JavaScript function.
Replaces placeholders based on data passed to the template

Logic-less Templates

Logic-less templates ensure that HTML code is separated from application code. All application logic is handled in the view. For example, when the application needs to access data stored in a model, a view handles that interaction. Logic-less templates make the application more modular and ensure that the source code is easier to maintain. More importantly, these templates ensure template customizations are not broken when upgrading to a new SCA version.

Template Compilation

The source files for each template contain the raw HTML as well as Handlebars placeholders. When you compile the application, one of the tasks the gulp template command performs is to pre-compile each of the template source files into a JavaScript function. The gulp deploy and gulp local commands call the gulp template command which, in turn, calls the Handlebars compiler.

The result of the gulp template command is that the template is transformed into a JavaScript function that can be called by passing a context object. This function is called when the view is rendered. Within the template file, Handlebars.js placeholders are transformed into JavaScript functions. For example, the following if construct:

          {{#if showLanguages}}

is transformed into the following code when the template is compiled:

          if(context.showLanguages){}

Handlebars.js placeholders that do not contain logic are also transformed into JavaScript functions. For example the following HTML code and placeholder:

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

is transformed into the following when the template is compiled:

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

Interaction Between Templates and Views

Since templates do not contain application code and contain minimal logic, the data they require must be passed to them. When calling, the template method passes the context object. Templates only contain logic for performing loops and conditionals. Views contain all of the logic required to display the contents of a template. Views also contain all of the application logic. To display a template, the view calls the template function from the view.render method. For example, when the application is compiled and running, a view’s render method would contain code similar to the following example to access the values contained in the context object:

          var context = this.getContext() body.innerHTML = this.template(context)

In this example, the view passes the context object to the template function. The object passed to the template is the object returned by the getContext method. In SCA, almost every view contains a getContext method. In general, this method is responsible for returning a context object that contains all of the data required by the template. This object may contain properties that contain data obtained from the model, configuration properties, or other properties the view requires.

Template Context

The template's context object returned by the getContext method can be seen as a contract between the view and the template. The purpose of this contract is to ensure that any customizations you make to the template are not overridden or broken when upgrading to a new version of SCA. Properties within the context object are not removed or modified in future versions. New properties may be added to the context object, but it will always be backward compatible with previous versions.

To ensure that this contract is maintained, the template only has access to this context object. The view is responsible for providing the context object and defining and respecting the contract in future versions.

Another area where the template context is important is within composite views. For example, you can customize a child view to use a custom template instead of the default template. When customizing an existing template or creating a new one, if you access the properties contained in the context object, these customizations will be preserved after an upgrade.

Custom Helpers

The Handlebars.js library defines helpers that perform functionality beyond that performed by the default placeholders. Handlebars.js defines multiple default helpers.

In addition to these default helpers, SCA defines custom helpers that perform various tasks. These helpers are defined in the HandlebarsExtras.js file located in the JavaScript subdirectory of the HandlebarsExtras application module. The following helpers are defined:

translate: returns a safe string that contains a localized version of the string by calling the _.translate function. Returning a safe string ensures that any HTML formatting or other text is preserved.
formatCurrency: returns a formatted currency value by calling the formatCurrency function.
highlightKeyword: returns a highlighted keyword by calling the _.highlightKeyword function. For example, the site_search_item.tpl template file uses this helper to highlight search results within a page using the following:
```
              {{highlightKeyword model._name query}} 

            
```
displayMessage: creates an instance of a GlobalViewsMessageView and renders the view.
objectToAtrributes: returns the attributes of an object, causing them to be displayed in the template. This helper calls the _.objectToAtrributes method.
each: defines a custom each helper that supports a Backbone.js collection. This helper iterates through each item of the collection.
resizeImage: builds URL images using the imageSizeMapping utility. This helper passes a URL and an object containing the dimensions of the image to this utility. It returns a normalized URL image based on these values.
fixUrl: returns a valid URL by calling the _.fixURL utility.
trimHtml: returns a trimmed HTML string based on the length passed to the helper. This helper calls the jQuery.trim method. The string returned can contain HTML elements.
breaklines: places break tags (<br/>) instead of new lines provided by the backend. Use this in Quotes, Returns, Case, and Review Order messages.

ifEquals: creates an equality condition to a Handlebars {{if}} helper. The following example depicts use for a custom transaction body field:

               {{#ifEquals model.options.custbody_my_transaction_body_field_2 'T'}}
    This is true
{{else}}
    This is false
{{/ifEquals}}

Logic-less Templates

Template Compilation

Interaction Between Templates and Views

Template Context

Custom Helpers

Related Topics