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 theformatCurrency
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 thejQuery.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}}