Mustache templates

Mustache templates are the new way of rendering output. They are available from Totara 9 onwards.

Using Mustache templates

Writing a template

Effectively it is plan HTML with variables injected using {{ }} (AKA mustaches)

An example would be:

<span class="name">{{name}}</span>

If the name was Bob, it would output:

<span class="name">Bob</span>

Formatted HTML

In a lot of places, Totara php functions will return a nicely formatted string containing html tags. Using the example below will display these as plain text:

{{ variablename }}

For example using the input below:

<a href="blah">blah</a>

would return the HTML:

&gt;a href=&quote;blah&quote;&lt;blah&gt;/a&lt;

To get around this, use (but beware of XSS attacks):

{{{ variablename }}}

Classes (or key => variable array's)

To display attributes of a class, there are two possible notations, an "in" notation using '#' & '/' and a '.' notation.

Below is an example of an "in" notation using '#' & '/':

{{#user}}
    {{firstname}}
    {{lastname}}
{{/user}}

Here is an example of a '.' notation:

{{user.firstname}}
{{user.lastname}}

Loops

For example, if the supplied data has an array called names, it can be looped through in the following manor:

<ul id="users">
    {{#names}}<li class="name">{{.}}</li>{{/names}}
</ul>

If the array names has no elements, then that code snippet will return this invalid HTML:

<ul id="users">
</ul>

One of the limitations of the PHP Mustache implementation is that there is no equivalent for JavaScript arrays' .length property which can be used within templates to check if an array has items or not for situations like the above. It is possible to use an obscure <array>.0 syntax in PHP and JS however its intention is not clear. Therefore in PHP and JS the agreed standard in Totara is to add a variable at the same depth as the array in the template context using the naming convention <arrayname>_has_items which must contain a boolean (opposed to a count) e.g.

{{#names_has_items}}
<ul id="users">
   {{#names}}<li class="name">{{.}}</li>{{/names}}
</ul>
{{/names_has_items}}

Which will output nothing if there are no users, and the following code if names contain Bob and Mary:

<ul id="users">
    <li class="name">Bob</li>
    <li class="name">Mary</li>
</ul>

This approach can also be used with the inverse operator ^ to provide output when the array does not contain items e.g.

{{^names_has_items}}
<p>There are no items.</p>
{{/names_has_items}}

Where do they get stored?

In the templates directory within the plugin. They can also be overwritten in a theme by placing them in the <themename>/templates/<pluginname> directory.

Calling from PHP

This can be done simply by calling:

$OUTPUT->render_from_template('templatename', $data);

Where:

templatename is the directory/<template filename>
$data is a stdClass with the data to display

For example, if your template is located in user/templates/course_participants.mustache, then the call would be:

$OUTPUT->render_from_template('user/course_participants', $data);

Converting a renderer to a mustache template

The traditional Moodle renderer has been abused and generally contains too much logic. Ideally a renderer should (and Mustache will enforce this):

Only have one argument (which may be a class or array). If the object needs to be displayed in a different manor, it should call a different renderer.
Only have conditional statements that check if a variable is there or not, or alter the appearance based on what a value is (eg. add a CSS class, and/or display "fail" if a score is below 50%). ALL permissions checks etc. should be done before the renderer is called (and remove data.
Only call other renderers, or renderables. All data should be passed in via the 1 argument.

Once the renderer has be cleaned up, then it is merely a matter of translating the output of the PHP to Mustache, and instead of calling render, making a call to $OUTPUT->render_from_template().

Calling from Javascript

They are best loaded using the new javascript format using requireJS (for more documentation see JavaScript & AMD modules).

The dependency that is required is 'core/templates', and then a call can be made to renderTemplate('templatename', data). An example of this is:

require(['core/templates', 'core/notification'], function(templates, notification) {
    var context = { name: 'Tweety bird', intelligence: 2 };
    templates.renderTemplate('block_looneytunes/profile', context)
        .done(doneCallback)
        .fail(notification.exception);
});

Creating Mustache template context examples

In order for a template to provide a rendered example usage in the Template Library Site administration > Development > Template library template files must provide a JSON encoded object (see upstream documentation) which is passed to the rendering function. While this works nicely for simple templates there are a number of problems with this approach when it comes to templates which recieve pre-rendered HTML such as portability of image paths and potential for example interfaces to act on live data. A utility method has been provided to automate removal of the issues found to date and standardise example formatting. Template examples should still be checked manually for potential issues / edge cases yet to be identified.

The utility class is located in admin/tool/templatelibrary/classes/example_data_formatter.php and may be inserted into code just before a call to render_from_template() to output an example. This must be removed before committing the patch and is intended for development purposes only. Example usage:

// In some renderer method where $templatecontext
// has properties containing pre-rendered HTML.

// DEBUG: !! Remove these next 2 lines after copying the output in the browser !!
echo tool_templatelibrary\example_data_formatter::to_json($templatecontext);
die();

return $this->render_from_template('local_myplugin/templatename', $templatecontext);