Custom widget templates

All aspects of the widgets can be fully customised and changed by overriding the default templates provided with the SDK. This allows you to replace the widgets with your own HTML and CSS without having to build all the functionality already available in the SDK.

General information

Below are some general facts and features that you should be aware of when building your custom templates:

• The updateTemplate() function should be called directly after the init() function and before any of the widget rendering functions are called, otherwise the templates will not be used when rendering.

• All the widget templates make use of the Lo-Dash micro-templating function. For more information on the micro-templating function refer to the Lo-Dash documentation.

• All the Lo-Dash functions are available within the templates which allows you to manipulate, iterate, and transform the data being supplied. Examples below use some of the Lo-Dash functions, however for the full list of functions available please reference the Lo-Dash documentation.

• All the jQuery functions are also available for use from within the templates. In order to access jQuery from within a template you must use the short hand version: $.<function>. Calling jQuery.<function> will not work.

• The CSS class names used in the widgets all begin with mambo-*, so it is highly recommended that you do NOT prefix your CSS classes with this as you might experience unexpected styling!

• The CSS classes prefixed with mambo-ctrl-* are called control classes. These classes have no associated CSS styling and are used to control the functionality associated to a particular widget. Each widget exposes its own set of control classes.

• Many of the templates below are associated with data in JSON format. In order to preview the data being passed to the template, it is possible to use the console.log() function to print the object to the developer console. If you are unsure about what this means, search Google because it is extremely valuable knowledge!

• The sample code below will show you how to declare a new template and override the existing one. It assumes that the SDK has already been initialised using the Mambo.init() function and that the widgets are being displayed as described in the sections above.

Sample template

As mentioned above, you can use both Lo-Dash and jQuery functions inside your custom templates. Below is a code snippet with an example:

JavaScript

<script type="text/template" id="custom-template">

  <p>Let's check if it's an array and loop through it with Lo-Dash:</p>
  <% if( _.isArray( data ) ) { %>
      <% _.forEach( data, function( item, idx ) { %>
          <p>Item (<%= idx %>): <%= item.name %></p>
      <% }); %>
  <% } %>

  <p>Let's check if it's an array and loop through it with jQuery:</p>
  <% if( $.isArray( data ) ) { %>
      <% $.each( data, function( idx, item ) { %>
          <p>Item (<%= idx %>): <%= item.name %></p>
      <% }); %>
  <% } %>
</script>

What to expect

Each of the template documentation pages will provide you with:

1. A description of the template and where it is used.
2. A description of the control classes available to the template and what functionality is associated to each.
3. A description of the data that will be supplied to the template.
4. A functional code sample which allows you to quickly get started with your customisations.