Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Templates: Difference between revisions

From MoodleDocs
No edit summary
m (Protected "Templates": Developer Docs Migration ([Edit=Allow only administrators] (indefinite)))
 
(8 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Template:Migrated|newDocId=/docs/guides/templates/}}
{{Moodle 2.9}}
{{Moodle 2.9}}


= Templates =
Templates in Moodle are used for rendering the output such as HTML or email messages bodies. Templates are defined as a text with placeholder tags. Placeholder tags are replaced with actual values during the rendering. Templates can be rendered both on the server side in PHP as well as on the client side in JavaScript. Themes can override the default templates. Moodle uses [https://mustache.github.io/mustache.5.html Mustache template system].
== Simple example ==
Given the template is defined as:
<syntaxhighlight lang="html+handlebars">
<div class="alert alert-info">
    <strong>Hello {{name}}!</strong> Your grade is: <strong>{{grade}}</strong>
</div>
</syntaxhighlight>
And the values for the placeholder tags <var>name</var> and <var>grade</var> are provided as a JSON object, referred to as ''rendering context'' (note the ''context'' here has nothing to do with Moodle [[Roles#Context|permission contexts]]. In Mustache, the term basically represents the data passed to the template).
<syntaxhighlight lang="json">
{
    "name": "Bobby",
    "grade": 10
}
</syntaxhighlight>
Then the rendered result will look like:
<div class="alert alert-info"><strong>Hello Bobby!</strong> Your grade is: <strong>10</strong></div>
The following page provides information about the Mustache templates syntax and how to use them in Moodle.
== Syntax ==
Mustache tags are made of two opening and closing curly braces. Their shape looks like a [https://en.wikipedia.org/wiki/Moustache moustache], thence the name.
=== Variables ===
<syntaxhighlight lang="html+handlebars">
{{name}}
</syntaxhighlight>
<syntaxhighlight lang="json">
{
    "name": "Bobby"
}
</syntaxhighlight>
The value of the key <var>name</var> will be searched for in the current rendering context (and any parent contexts) and when a value is found, the entire tag will be replaced by the value (HTML escaped).
=== Raw unescaped variable ===
All variables are HTML escaped by default. If you want to render raw unescaped HTML, use the triple mustache:
<syntaxhighlight lang="html+handlebars">
{{{description}}}
</syntaxhighlight>
<syntaxhighlight lang="json">
{
    "description": "<h1>Hello!</h1><p>In this course you will learn about ...</p>"
}
</syntaxhighlight>
Beware of the security implications of outputting raw HTML and make sure that the value of the variable has been processed by <tt>format_text()</tt> or another adequate way.
=== Sections ===
Sections render blocks of text zero, one or more times, depending on the value of the key in the current context. The opening tag has a hash (pound) sign and the closing tag has a slash, followed by the key.


== What is a template? ==
'''False values and empty lists'''
A template is an alternative to writing blocks of HTML directly in javascript / php by concatenating strings. The end result is the same, but templates have a number of advantages:
* It is easier to see the final result of the template because the code for a template is very close to what the final HTML will look like
* Because the templating language is intentionally limited, it is hard to introduce complex logic into a template. This makes it far easier for a theme designer to override a template, without breaking the logic
* Templates can be rendered from javascript. This allows ajax operations to re-render a portion of the page.


== How do I write a template? ==
When the key is false or an empty list, the HTML between the opening and closing tag will not be displayed. This can be effectively used to conditionally control the rendering of a section.
Templates are written in a language called "[http://mustache.github.io/mustache.5.html Mustache]". Mustache is written as HTML with additional tags used to format the display of the data. Mustache tags are made of 2 opening and closing curly braces <code xml>{{tag}}</code>. There are a few variations of these tags that behave differently.
<syntaxhighlight lang="html+handlebars">
* <code xml>{{raiden}}</code> This is a simple variable substitution. The variable named "raiden" will be searched for in the current context (and any parent contexts) and when a value is found, the entire tag will be replaced by the variable (HTML escaped).
{{#hasdata}}
* <code xml>{{{galaga}}}</code> This is an unescaped variable substitution. Instead of escaping the variable before replacing it in the template, the variable is included raw. This is useful when the variable contains a block of HTML (for example).
    This will not be shown if 'hasdata' is empty.
* <code xml>{{#lemmings}} jump off cliff {{/lemmings}}</code> These are opening and closing section tags. If the lemmings variable exists and evaluates to "not false" value, the variable is pushed on the stack, the contents of the section are parsed and included in the result. If the variable does not exist, or evaluates to false - the section will be skipped. If the variable lemmings evaluates to an array, the section will be repeated for each item in the array with the items of the array on the context. This is how to output a list.
{{/hasdata}}
* <code xml>{{^lemmings}} enjoy view {{/lemmings}}</code> Equivalent of "if-not" block, there is no "else" in mustache.
</syntaxhighlight>
* <code xml>{{> franken_style/name_of_template }}</code> This is a partial. Think of it like an include. Templates can include other templates using this tag. In the called template, the data it sees (for including values is the same as the data available where the partial is included.
<syntaxhighlight lang="json">
* <code xml>{{$blockvar}} ... {{/blockvar}}</code> This is a block variable. It defines a section of the template that can be overridden when it's included in another template.
{
* <code xml>{{< template_name}} ... {{/template_name}}</code> This is similar to including a partial but specifically indicates that you'd like to override one or more block variables defined within the template you're including. You can override the block variables by defining a block variable within these tags that matches the name of the block variable you'd like to override in the included template.
    "hasdata": false
}
</syntaxhighlight>
'''Non-empty lists'''


So - putting this all together:
When the value is a non-empty list, the text in the block will be displayed once for each item in the list. The context of the block will be set to the current item for each iteration. In this way we can loop over collections.
<syntaxhighlight lang="html+handlebars">
<ul>
    {{#grades}}
    <li>
        <em>{{course}}</em> - {{grade}}
    </li>
    {{/grades}}
</ul>


recipe.mustache
</syntaxhighlight>
<code xml>
<syntaxhighlight lang="json">
<h3>{{recipename}}</h3>
<p>{{description}}</p>
<h4>Ingredients</h4>
<ol>
{{#ingredients}}
<li>{{.}}</li>
{{/ingredients}}
</ol>
<h4>Steps</h4>
<ol>
{{#steps}}
<li>{{{.}}}</li>
{{/steps}}
</ol>
{{ > ratethisrecipe }}
</code>
 
When given this data:
<code javascript>
{
{
  recipename: "Cheese sandwich",
    "grades": [
  description: "Who doesn't like a good cheese sandwich?",
        {
  ingredients: ["bread", "cheese", "butter"],
            "course": "Arithmetic",
  steps: ["<p>Step 1 is to spread the butter on the bread</p>", "<p>Step 2 is to put the cheese &quot;in&quot; the bread (not on top, or underneath)</p>"]
            "grade": "8/10"
        },
        {
            "course": "Geometry",
            "grade": "10/10"
        }
    ]
}
}
</code>
</syntaxhighlight>
'''Lambdas'''


Gives this: <span style="font-size:4em">😋</span>
When the value is a callable, it will be invoked and returned value used as the section value. In Moodle plugins, this can be used to call the <tt>core_renderer</tt> methods via the <tt>output</tt> context variable:
<syntaxhighlight lang="html+handlebars">
{{#output.should_display_navbar_logo}}
    <img src="{{output.get_compact_logo_url}}">
{{/output.should_display_navbar_logo}}
</syntaxhighlight>
'''Inverted sections'''


More info - there are much clearer explanations of templates on the [http://mustache.github.io/mustache.5.html Mustache] website. Try reading those pages "before" posting on stack overflow :) .
Inverted sections will be rendered if the key does not exist, is false, or is an empty list. An inverted section begins with a caret (hat) and ends with a slash.
<syntaxhighlight lang="html+handlebars">
{{#hasgrade}}
    Your grade is: <strong>{{grade}}</strong>
{{/hasgrade}}


=== Blocks (Moodle 3.0 onwards) ===
{{^hasgrade}}
Blocks are a feature of Mustache that deserves a special mention. They are used as a form of inheritance - and are crucial to building a library of re-usable templates. To make use of "blocks" you define a parent template with replaceable sections. Each of those sections is marked with a "blocks" tag like this (A blocks tag looks like a regular tag, but the variable name is preceded with $):
    Your work has not been graded yet.
{{/hasgrade}}
</syntaxhighlight>
<syntaxhighlight lang="json">
{
    "hasgrade": false,
    "grade": null
}
</syntaxhighlight>
=== Comments ===
Comments begin with an exclamation mark. The whole section is ignored. Comments are used for boilerplate documentation. They can also be used to avoid having extra break-lines in the generated output.
<syntaxhighlight lang="html+handlebars">
{{!
    This is a comment and will not be present in the rendered result.
}}
</syntaxhighlight>
=== Partials ===
Templates can include other templates using the partial tag. Partials begin with a greater than sign. Partials are rendered at runtime and allow to split complex templates into smaller, potentially re-usable units. Moodle core provides with many templates that can be included this way.
<syntaxhighlight lang="html+handlebars">
{{! Show the loading icon. }}
<div class="p-5">
    {{> core/loading }}
</div>
</syntaxhighlight>
The included template uses the same rendering context as its parent template.
=== Blocks ===
{{Moodle 3.0}}
Mustache template system can be extended via so called [https://github.com/bobthecow/mustache.php/wiki/Pragmas Mustache pragmas]. Pragmas are non-standard extensions to the Mustache spec. Moodle 3.0 and higher has [https://github.com/bobthecow/mustache.php/wiki/BLOCKS-pragma BLOCKS pragma] installed and enabled.


<code xml>
The extension allows you to define a parent template with replaceable blocks. Blocks look like sections that use dollar sign in the opening tag. The following parent template defines two blocks <var>heading</var> and <var>content</var>
<syntaxhighlight lang="html+handlebars">
{{!
    @template tool_demo/section
}}
<section>
<section>
<h1>{{$sectionheading}}Default heading{{/sectionheading}}</h1>
    <h1>
<div>
        {{$heading}} Default section heading {{/heading}}
{{$content}}Content for section{{/content}}
    </h1>
</div>
    <div>
        {{$content}} Default section content {{/content}}
    </div>
</section>
</section>
</code>
</syntaxhighlight>
Particular child templates can now extend / inherit from this parent template and override the default block values.
<syntaxhighlight lang="html+handlebars">
{{!
    @template tool_demo/latestnews
}}
{{< tool_demo/section }}
    {{$heading}} Latest news {{/heading}}
    {{$content}} Today I learned how to use blocks in Mustache! {{/content}}
{{/ tool_demo/section}}
</syntaxhighlight>
Blocks are particularly useful for building a library of re-usable components.
== Helpers ==
Moodle providers several Mustache helpers. Helpers tags look like sections eventually containing zero or more parameters.
=== str ===
The <tt>{{#str}}</tt> is a string helper for loading text strings from language packs. It effectively represents Mustache variant of <code>get_string()</code> calls.
<syntaxhighlight lang="html+handlebars">
{{#str}} helloworld, mod_greeting {{/str}}
</syntaxhighlight>
The first two parameters are the string identifier and the component name. The optional third parameter defines the value for the string's <code>$a</code> placeholder. Literals as well as variable tags are allowed to define the value.
<syntaxhighlight lang="html+handlebars">
{{#str}} backto, core, Moodle.org {{/str}}


Now - wherever I need to re-use this template I can include it and replace the content of those sections at the same time.  
{{#str}} backto, core, {{name}} {{/str}}
</syntaxhighlight>
For strings that accept non-scalar placeholders, see the following section.


<code xml>
Note: if you want to do a '''help icon''', and wondering "where is the helper for that?" then acutally, it is not a helper. You need to use <code><nowiki>{{>core/help_icon}}</nowiki></code> as a partial.
{{< section}}
=== quote ===
{{$sectionheading}}Latest News{{/sectionheading}}
The <tt>{{#quote}}</tt> is used to quote non-scalar <tt>{{#str}}</tt> arguments.
{{$content}}Nothing happened today - sorry!{{/content}}
{{/section}}
</code>


Notice that when I include a template and I want to make use of blocks - the include tag points the other way:
Some strings accept complex non-scalar data structures passed as the value of the <code>$a</code> placeholder. You can use a JSON object syntax in that case:
<code xml>
<syntaxhighlight lang="html+handlebars">
{{< section}}
{{#str}} counteditems, core, { "count": "42", "items": "courses" } {{/str}}
</code>
</syntaxhighlight>
Not
If you wanted to use the context values instead of literal values, you might intuitively use something like this:
<code xml>
<syntaxhighlight lang="html+handlebars">
{{> section}}
</code>
 
Blocks support looping and many other cool things - for more info see https://github.com/bobthecow/mustache.php/wiki/BLOCKS-pragma
 
== Where do I put my templates? ==
 
Templates go in the <componentdir>/templates folder and must have a .mustache file extension. When loading templates the template name is <componentname>/<filename> (no file extension).
 
So "mod_lesson/timer" would load the template at mod/lesson/templates/timer.mustache.
 
Since Moodle 3.8 it is possible to use sub-directories under the "/templates" directory, however the first sub-directory _must_ meet the [[Coding style#Rules for level2|L2 namespace rules]].
 
== How do I call a template from javascript? ==
 
Rendering a template from javascript is fairly easy. There is a new AMD module that can load/cache and render a template for you.
 
<code javascript>
// This is AMD code for loading the "core/templates" module. see [Javascript Modules].
require(['core/templates'], function(templates) {
 
    // This will be the context for our template. So {{name}} in the template will resolve to "Tweety bird".
    var context = { name: 'Tweety bird', intelligence: 2 };
 
    // This will call the function to load and render our template.
    templates.render('block_looneytunes/profile', context)
 
    // It returns a promise that needs to be resoved.
            .then(function(html, js) {
                // Here eventually I have my compiled template, and any javascript that it generated.
                // The templates object has append, prepend and replace functions.
                templates.appendNodeContents('.block_looneytunes .content', html, js);
            }).fail(function(ex) {
                // Deal with this exception (I recommend core/notify exception function for this).
            });
});
</code>
 
 
Under the hood, this did many clever things for us. It loaded the template via an ajax call if it was not cached. It found any missing lang strings in the template and loaded them in a single ajax request, it split the JS from the HTML and returned us both in easy to use way. Read on for how to nicely deal with the javascript parameter.
 
Note: with some nice chaining and sugar, we can shorten the above example quite a bit:
<code javascript>
require(['core/templates', 'core/notification'], function(templates, notification) {
    var context = { name: 'Tweety bird', intelligence: 2 };
    templates.render('block_looneytunes/profile', context)
        .then(doneCallback)
        .fail(notification.exception);
});
</code>
 
== What if a template contains javascript? ==
 
Sometimes a template requires that some JS be run when it is added to the page in order to give it more features. In the template we can include blocks of javascript, but we should use a special section tag that has a "helper" method registered to handle javascript carefully.
 
Example
[https://github.com/moodle/moodle/blob/master/lib/form/templates/element-advcheckbox-inline.mustache#L34 lib/form/templates/element-advcheckbox-inline.mustache]
<code xml>
<!-- HTML here -->>
{{^element.frozen}}
{{#js}}
require(['theme_boost/form-display-errors'], function(module) {
    module.enhance({{#quote}}{{element.id}}{{/quote}});
});
{{/js}}
{{/element.frozen}}
</code>
 
If this template is rendered by PHP, the javascript is separated from the HTML, and is appended to a special section in the footer of the page "after" requirejs has loaded. This provides the optimal page loading speed. If the template is rendered by javascript, the javascript source will be passed to the "done" handler from the promise. Then, when the "done" handler has added the template to the DOM, it can call
<code javascript>templates.runTemplateJS(javascript);</code>
which will run the javascript (by creating a new script tag and appending it to the page head).
 
== What other helpers can I use? ==
 
The implementation of these helpers is in classes like [https://github.com/moodle/moodle/blob/master/lib/classes/output/mustache_string_helper.php#L31 \core\output\mustache_string_helper]. This is set up in the [https://github.com/moodle/moodle/blob/master/lib/outputrenderers.php#L100 get_mustache method in renderer_base] (There should be no need to look at the implementation, unless you are interested.) If you are considering adding a new helper, it should be limited to display logic - and you need to be able to create identical helpers for the javascript and php implementations (javascript ones go in lib/amd/src/templates.js).
 
=== {{# str }} ===
 
There is a string helper for loading language strings.
 
<code xml>
{{# str }} helloworld, mod_greeting {{/ str }}
</code>
 
The first 2 parameters are the string id and the component name. So this is effectively Mustache variant of <syntaxhighlight lang="php">get_string('helloworld', 'mod_greeting')</syntaxhighlight>.
 
The optional third parameter defines the value for the string's <syntaxhighlight lang="php">$a</syntaxhighlight> placeholder:
 
<code xml>
{{# str }} iscool, mod_cool, David Beckham {{/ str }}
</code>
 
This example would effectively do what <syntaxhighlight lang="php">get_string('iscool', 'mod_cool', 'David Beckham')</syntaxhighlight> does in Moodle PHP code.
 
Variable tags are allowed to define the value of the <syntaxhighlight lang="php">$a</syntaxhighlight> placeholder:
 
<code xml>
{{# str }} iscool, mod_cool, {{ name }} {{/ str }}
</code>
 
For strings that accept complex placeholder, see the following section.
 
=== {{# quote }} ===
 
As shown in the previous section, the <syntaxhighlight lang="php">{{# str }}</syntaxhighlight> helper may need complex data structures passed as the value of the <syntaxhighlight lang="php">$a</syntaxhighlight> placeholder. You can use a JSON object syntax in that case:
 
<code xml>
{{# str }} iscool, mod_cool, { "firstname": "David", "lastname": "Beckham" } {{/ str }}
</code>
 
If you wanted to use the context values instead of literal strings, you might intuitively use something like this:
 
<code xml>
{{! DO NOT DO THIS !}}
{{! DO NOT DO THIS !}}
{{# str }} iscool, mod_cool, { "firstname": "{{ firstname }}", "lastname": "{{ lastname }}" } {{/ str }}
{{#str}} counteditems, core, { "count": {{count}}, "items": {{itemname}} } {{/str}}
</code>
</syntaxhighlight>
 
There is a potential problem though. If the variable tag <var>itemname</var> evaluates to a string containing double quotes, it will break the JSON syntax. We need to escape certain characters potentially appearing in the variable tags. For this, we use the <tt>{{#quote}}</tt> helper.
There is a potential problem though. If the variable tag <syntaxhighlight lang="php">{{ firstname }}</syntaxhighlight> or <syntaxhighlight lang="php">{{ lastname }}</syntaxhighlight> evaluates to a string containing the double quote character, that will break the JSON syntax. We need to escape the double quotes potentially appearing in the variable tags. For this, use the <syntaxhighlight lang="php">{{# quote }}</syntaxhighlight> helper:
<syntaxhighlight lang="html+handlebars">
{{#str}} counteditems, core, { "count": {{count}}, "items": {{#quote}} {{itemname}} {{/quote}} } {{/str}}
</syntaxhighlight>
=== pix ===
The <tt>{{#pix}}</tt> is a icon picture helper for generating pix icon tags.
<syntaxhighlight lang="html+handlebars">
{{#pix}} t/edit, core, Edit this section {{/pix}}
</syntaxhighlight>
The first two parameters are the icon identifier and the component name. The rest is the alt text for the icon.


<code xml>
See [[Using images in a theme]] and [[Moodle_icons]] for some background information about pix icons in Moodle.
{{! This is OK !}}
=== userdate ===
{{# str }} iscool, mod_cool, { "firstname":  {{# quote }}{{ firstname }}{{/ quote }}, "lastname": {{# quote }}{{ lastname }}{{/ quote }} } {{/ str }}
</code>
 
See MDL-52136 for details.
=== {{# pix }} ===
 
There is a pix icon helper for generating pix icon tags.
 
<code xml>
{{# pix }} t/edit, core, Edit David Beckham {{/ pix }}
</code>
 
The first 2 parameters are the string id and the component name, the rest is the alt text for the image.
 
=== {{# userdate }} (Moodle 3.3 onwards) ===
{{Moodle 3.3}}
{{Moodle 3.3}}
This mustache template helper will format unix timestamps into a given human readable date format while using the user's timezone settings configured (if any) in Moodle. The helper will accept hardcoded values, context variables, or other helpers.  
The <tt>{{#userdate}}</tt> helper will format UNIX timestamps into a given human readable date format while using the user's timezone settings configured (if any) in Moodle. The helper will accept hardcoded values, context variables, or other helpers.  


The recommended way to use this helper is to use the string helper to get one of the core Moodle formats because they have been translated into other languages so you'll get multi-lang support for free (that's a pretty good deal!).
It is recommended to use the string helper to get one of the core Moodle formats.
 
<syntaxhighlight lang="json">
==== Using the string helper (recommended) ====
{
<syntaxhighlight lang="php">
    "time": 1628871929
// Assuming we had a context variable named "time" set to 1293876000.
}
{{#userdate}} {{time}}, {{#str}} strftimedate {{/str}} {{/userdate}}
</syntaxhighlight>
</syntaxhighlight>
This will ask the Moodle server for the string "strftimedate" and will use the value (which in this case is "%d %B %Y")  to format the user date. So the resulting formatted timestamp from the userdate helper will be "01 January 2011".
<syntaxhighlight lang="html+handlebars">
 
{{#userdate}} {{time}}, {{#str}} strftimedate, core_langconfig {{/str}} {{/userdate}}
==== Using context variables ====
<syntaxhighlight lang="php">
// Assuming we had a context variable named "time" set to 1293876000.
{{#userdate}} {{time}}, %A, %d %B %Y, %I:%M %p {{/userdate}}
</syntaxhighlight>
</syntaxhighlight>
Will produce "Saturday, 01 January 2011, 10:00 AM"
This will ask the Moodle server for the string "strftimedate" and will use the value (which in this case is "%d %B %Y" in case of English) to format the user date. So the resulting formatted timestamp from the userdate helper would be like "13 August 2021".
 
=== shortentext ===
==== Using hardcoded values ====
<code xml>
{{#userdate}} 1293876000, %A, %d %B %Y, %I:%M %p {{/userdate}}
</code>
Will produce "Saturday, 01 January 2011, 10:00 AM"
 
=== {{# shortentext }} (Moodle 3.3 onwards) ===
{{Moodle 3.3}}
{{Moodle 3.3}}
This helper can be used to shorten a large amount of text to a specified length and will append a trailing ellipsis to signify that the text has been shortened.  
The <tt>{{#shortentext}} </tt> helper can be used to shorten a large amount of text to a specified length and will append a trailing ellipsis to signify that the text has been shortened.  


The algorithm will attempt to preserve words while shortening to text. Words, for the purposes of the helper, are considered to be groups of consecutive characters broken by a space or, in the case of a multi-byte character, after the completion of the multi-byte character (rather than in the middle of the character).
The algorithm will attempt to preserve words while shortening to text. Words, for the purposes of the helper, are considered to be groups of consecutive characters broken by a space or, in the case of a multi-byte character, after the completion of the multi-byte character (rather than in the middle of the character).
Line 251: Line 220:


The helper takes two comma separated arguments. The first is the desired length and the second is the text to be shortened. Both can be provided as context variables.
The helper takes two comma separated arguments. The first is the desired length and the second is the text to be shortened. Both can be provided as context variables.
 
<syntaxhighlight lang="json">
==== Plain text ====
{
<syntaxhighlight lang="php">
    "description": "<p><em>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur lacinia pretium nulla gravida interdum.</em></p>"
{{#shortentext}} 30, long text without any tags blah de blah blah blah what {{/shortentext}}
}
</syntaxhighlight>
</syntaxhighlight>
Will produce:
<syntaxhighlight lang="html+handlebars">
<syntaxhighlight lang="php">
{{#shortentext}} 15, {{{description}}} {{/shortentext}}
long text without any tags ...
</syntaxhighlight>
</syntaxhighlight>
== Template files ==
Templates are saved in <tt>templates/*.mustache</tt> files within core components and plugins folders. When loading them, templates are identified by their [[Frankenstyle|full component name]] followed by slash and the filename without the file extension.


==== HTML text ====
'''Example:''' A <tt>timer</tt> template provided by the <tt>mod_lesson</tt> module would be referred to as <tt>mod_lesson/timer</tt> and it would be located in <tt>mod/lesson/templates/timer.mustache</tt> file.
<syntaxhighlight lang="php">
{{#shortentext}} 30, <div class='frog'><p><blockquote>Long text with tags that will be chopped off but <b>should be added back again</b></blockquote></p></div></p> {{/shortentext}}
</syntaxhighlight>
Will produce:
<syntaxhighlight lang="php">
<div class='frog'><p><blockquote>Long text with tags that ...</blockquote></p></div>
</syntaxhighlight>


==== Multi-byte text ====
Since Moodle 3.8 it is possible to use sub-directories under the <tt>templates</tt> directory. The first sub-directory name must meet [[Coding style#Rules for level2|certain naming rules]] (same as for class namespaces).
<syntaxhighlight lang="php">
=== Mustache file boilerplate ===
{{#shortentext}} 6, 𠮟𠮟𠮟𠮟𠮟𠮟𠮟𠮟𠮟𠮟𠮟𠮟 {{/shortentext}}
<pre>
</syntaxhighlight>
{{!
Will produce:
    This file is part of Moodle - https://moodle.org/
<syntaxhighlight lang="php">
𠮟𠮟𠮟...
</syntaxhighlight>


== How do I call a template from php? ==
    Moodle is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.


The templates in php are attached to the renderers. There is a renderer method "render_from_template" that does the trick.
    Moodle is distributed in the hope that it will be useful,
<syntaxhighlight lang="php">
    but WITHOUT ANY WARRANTY; without even the implied warranty of
$OUTPUT->render_from_template($templatename, $context);
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
</syntaxhighlight>
    GNU General Public License for more details.
Note $context is nothing to do with normal Moodle 'contexts'. It is the data passed to the template (the 'context' mentioned in mustache documentation).


== How do templates work with renderers? ==
    You should have received a copy of the GNU General Public License
    along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
}}
{{!
    @template plugintype_pluginname/template_name


Extra care must be taken to ensure that the data passed to the context parameter is useful to the templating language. The template language cannot:
    Template purpose and description.
* Call functions
* Perform any boolean logic
* Render renderables
* Do capability checks
* Make DB queries


So - I have "some" data in my renderable and some logic and HTML generation in my render method for that renderable - how do I refactor this to use a template?
    Classes required for JS:
    * none


The first thing to note, is that you don't have to use a template if you don't want to. It just means that themers will still have to override your render method, instead of just overriding the template. But if you DO want to use a template, you will earn "cred" with themers, and you will be able to re-render parts of your interface from javascript in response to ajax requests without reloading the whole page (that's cool).
    Data attributes required for JS:
    * none


There is a simple pattern to use to hook a template into a render method. If you make your renderable implement templatable as well as renderable - it will have to implement a new method "export_for_template(renderer_base $output)". This method takes the data stored in the renderable and "flattens it" so it can be used in a template. If there is some nested data in the renderable (like other renderables) and they do not support templates, they can be "rendered" into the flat data structure using the renderer parameter. It should return an stdClass with properties that are only made of simple types: int, string, bool, float, stdClass or arrays of these types. Then the render method can updated to export the data and render it with the template.
    Context variables required for this template:
    * none


In the simplest case where you have a renderable, templatable object with a class name matching the name of the template that will render it, you do not need to add any renderer code explicity. Passing your widget directly to $OUTPUT->renderer() will infer the name of your template, call export_for_template() and render_from_template(), then return the result.
    Example context (json):
    {
    }
}}
</pre>
== Rendering in PHP ==
Use the <code>render_from_template()</code> method to render the given context data with the template.
<syntaxhighlight lang="php">
$data = [
    'name' => 'Lorem ipsum',
    'description' => format_text($description, FORMAT_HTML),
];


In the renderable:
echo $OUTPUT->render_from_template($templatename, $data);
</syntaxhighlight>
=== Renderers ===
Templates can be effectively used in [[Renderer|renderers]] to generate the HTML representing the given <code>renderable</code> object. Make your <code>renderable</code> class also implement <code>templatable</code> interface. It will have to implement a new method <code>export_for_template(renderer_base $output)</code>. The method should return a JSON-serialisable object (containing only objects, arrays and scalars) that will be passed as the rendering context data to a template.
 
In the simplest case where you have a renderable, templatable object with a class name matching the name of the template that will render it, you do not need to add any renderer code explicity. Passing your widget directly to <code>$OUTPUT->render()</code> will infer the name of your template, call <code>export_for_template()</code> and <code>render_from_template()</code>, then return the result.
 
Example of the method added to the renderable mywidget:
<syntaxhighlight lang="php">
<syntaxhighlight lang="php">
/**
/**
  * Export this data so it can be used as the context for a mustache template.
  * Describe the renderable widget so it can be renderer by a mustache template.
  *
  *
* @param renderer_base $output
  * @return stdClass
  * @return stdClass
  */
  */
Line 315: Line 298:
     $data = new stdClass();
     $data = new stdClass();
     $data->canmanage = $this->canmanage;
     $data->canmanage = $this->canmanage;
     $data->things = array();
     $data->things = [];
     foreach ($this->things as $thing) {
     foreach ($this->things as $thing) {
         $data->things[] = $thing->to_record();
         $data->things[] = $thing->to_record();
     }
     }
     $data->navigation = array();
     $data->navigation = [];
     foreach ($this->navigation as $button) {
     foreach ($this->navigation as $button) {
         $data->navigation[] = $output->render($button);
         $data->navigation[] = $output->render($button);
Line 327: Line 310:
}
}
</syntaxhighlight>
</syntaxhighlight>
 
The rendering method can now use templates to render the object:
In your component's renderer:
<syntaxhighlight lang="php">
<syntaxhighlight lang="php">
/**
/**
  * Render via a template.
  * Render mywidget via a template.
  *
  *
  * @param mywidget $widget
  * @param mywidget $widget
  *
  *
  * @return string HTML for the page
  * @return string HTML
  */
  */
protected function render_mywidget(mywidget $widget) {
protected function render_mywidget(mywidget $widget) {
     $data = $widget->export_for_template($this);
     $data = $widget->export_for_template($this);
    // Do other logic if needed.
     return $this->render_from_template('tool_myplugin/mywidget', $data);
     return $this->render_from_template('tool_myplugin/mywidget', $data);
}
}
</syntaxhighlight>
</syntaxhighlight>
In your page:
In your page:
<syntaxhighlight lang="php">
<syntaxhighlight lang="php">
Line 349: Line 329:
echo $output->render($widget);
echo $output->render($widget);
</syntaxhighlight>
</syntaxhighlight>
== Rendering in JavaScript ==
Rendering a template from JavaScript is fairly easy. There is a [[Javascript Modules|JavaScript module]] that can load (and cache) a template and then use it for rendering the given data.
<syntaxhighlight lang="javascript">
import {exception as displayException} from 'core/notification';
import Templates from 'core/templates';


== How to I override a template in my theme? ==
// This will be the context for our template. So {{name}} in the template will resolve to "Tweety bird".
const context = {
    name: 'Tweety bird',
    intelligence: 2,
};


Templates can be overridden a bit easier than overriding a renderer. First - find the template that you want to change. E.g. "mod/wiki/templates/ratingui.mustache". Now, create a sub-folder under your themes "templates" directory with the component name of the plugin you are overriding. E.g "theme/timtam/templates/mod_wiki". Finally, copy the ratingui.mustache file into the newly created "theme/timtam/templates/mod_wiki" and edit it. You should see your changes immediately if theme designer mode is on. Note: templates are cached just like CSS, so if you are not using theme designer mode you will need to purge all caches to see the latest version of an edited template. If the template you are overriding contains a documentation comment (see next section) it is recommended to remove it, it will still show the documentation in the template library.
// This will call the function to load and render our template.
Templates.renderForPromise('block_looneytunes/profile', context)


== Should I document my templates? ==
// It returns a promise that needs to be resoved.
    .then(({html, js}) => {
        // Here eventually I have my compiled template, and any javascript that it generated.
        // The templates object has append, prepend and replace functions.
        Templates.appendNodeContents('.block_looneytunes .content', html, js);
    })


Yes!!!! Theme designers need to know the limits of what they can expect to change without breaking anything. As a further benefit - your beautiful new template can be displayed in the "Template Library" tool shipped with Moodle. In order to provide nice documentation and examples for the Template Library, you should follow these conventions when documenting your template.
    // Deal with this exception (Using core/notify exception function is recommended).
    .catch(ex => displayException(ex));
</syntaxhighlight>
Under the hood, this does a few clever things for us. It loads the template via an AJAX call if it was not cached. It finds any missing lang strings in the template and loads them in a single AJAX request. It split the JS from the HTML and returns us both in easy to use way. Read on for how to nicely deal with that <code>js</code> parameter.
== Template requires JavaScript ==
Sometimes a template requires that some JavaScript runs when it is added to the page in order to give it more features. In the template we can include blocks of JavaScript, but we should use a special section tag that has a "helper" method registered to handle JavaScript carefully.  


=== Add a documentation comment to your template ===
Example
Mustache comments look like this:
<syntaxhighlight lang="html+handlebars">
<pre>
<!-- HTML here -->>
  {{!
{{^element.frozen}}
  I am a comment.
{{#js}}
  I can span multiple lines.
require(['theme_boost/form-display-errors'], function(module) {
  }}
    module.enhance({{#quote}}{{element.id}}{{/quote}});
</pre>
});
 
{{/js}}
The template library will look for a mustache comment that contains this special marker as the documentation to display, and the source of an example context.
{{/element.frozen}}
 
</syntaxhighlight>
<syntaxhighlight lang="php">
If this template is rendered by PHP, the JavaScript is separated from the HTML, and is appended to a special section in the footer of the page "after" requirejs has loaded. This provides the optimal page loading speed. If the template is rendered by JavaScript, the JavaScript source will be passed to the "done" handler from the promise. Then, when the "done" handler has added the template to the DOM, it can call
@template component/templatename
<syntaxhighlight lang="javascript">
templates.runTemplateJS(javascript);
</syntaxhighlight>
</syntaxhighlight>
which will run the javascript (by creating a new script tag and appending it to the page head).


==== Useful things to include in the documentation for a template ====
Note: It is recommended that the JavaScript present be kept to a minimum - preferably just the inclusion of a module designed to do the actual work. This allows for a template to be overridden by a renderer without the JavaScript having to be copied. It also enforces appropriate linting and minification of the code.
===== Classes required for JS =====
== Overriding templates in a theme ==
This is a list of classes that are used by the javascript for this template. If removing a class from an element in the template will break the javascript, list it here.
Templates can be overridden by a theme.
 
# Find the template that you want to change - e.g. <tt>mod/wiki/templates/ratingui.mustache</tt>
===== Data attributes required for JS =====
# Create a sub-folder under your themes "templates" directory with the component name of the plugin you are overriding - e.g <tt>theme/timtam/templates/mod_wiki</tt>
This is a list of data attributes (e.g. data-enhance="true") that are used by the javascript for this template. If removing a data attribute from an element in the template will break the javascript, list it here.
# Copy the <tt>ratingui.mustache</tt> file into the newly created <tt>theme/timtam/templates/mod_wiki</tt> and edit it.
 
You should see your changes immediately if theme designer mode is on. Templates are cached just like CSS, so if you are not using theme designer mode you will need to purge all caches to see the latest version of an edited template. If the template you are overriding contains a documentation comment it is recommended to remove it. It will still show the documentation in the template library.
===== Context variables required for this template =====
== Documenting the templates ==
This is a description of the data that may be contained in the context that is passed to the template. Be explicit and document every attribute.
Theme designers need to know the limits of what they can expect to change without breaking anything. Also, correctly documented templates can be previewed in the "Template library" tool shipped with Moodle.
 
* '''Classes required for JS''' - This is a list of classes that are used by the javascript for this template. If removing a class from an element in the template will break the javascript, list it here.
===== Example context (JSON) =====
* '''Data attributes required for JS''' - This is a list of data attributes (e.g. data-enhance="true") that are used by the javascript for this template. If removing a data attribute from an element in the template will break the javascript, list it here.
The Template Library will look for this data in your documentation comment as it allows it to render a "preview" of the template right in the Template Library. This is useful for theme designers to test all the available templates in their new theme to make sure they look nice in a new theme. It is also useful to make sure the template responds to different screen sizes, languages and devices. The format is a JSON-encoded object that is passed directly into the render method for this template.  
* '''Context variables required for this template''' - This is a description of the data that may be contained in the context that is passed to the template. Be explicit and document every attribute.
 
* '''Example context (JSON)''' - The Template library will look for this data in your documentation comment as it allows it to render a "preview" of the template right in the Template library. This is useful for theme designers to test all the available templates in their new theme to make sure they look nice in a new theme. It is also useful to make sure the template responds to different screen sizes, languages and devices. The format is a JSON-encoded object that is passed directly into the render method for this template.  
==== A full example ====
== Coding style ==
lib/templates/pix_icon.mustache
<pre>
  {{!                                                                                                                               
    This file is part of Moodle - http://moodle.org/                                                                               
                                                                                                                                   
    Moodle is free software: you can redistribute it and/or modify                                                                 
    it under the terms of the GNU General Public License as published by                                                           
    the Free Software Foundation, either version 3 of the License, or                                                             
    (at your option) any later version.                                                                                           
                                                                                                                                   
    Moodle is distributed in the hope that it will be useful,                                                                     
    but WITHOUT ANY WARRANTY; without even the implied warranty of                                                                 
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the                                                                 
    GNU General Public License for more details.                                                                                   
                                                                                                                                   
    You should have received a copy of the GNU General Public License                                                             
    along with Moodle.  If not, see <http://www.gnu.org/licenses/>.                                                               
  }}                                                                                                                                 
  {{!                                                                                                                               
    @template core/pix_icon                                                                                                       
                                                                                                                                   
    Moodle pix_icon template.                                                                                                     
                                                                                                                                   
    The purpose of this template is to render a pix_icon.                                                                         
                                                                                                                                   
    Classes required for JS:                                                                                                       
    * none                                                                                                                         
                                                                                                                                   
    Data attributes required for JS:                                                                                               
    * none                                                                                                                         
                                                                                                                                   
    Context variables required for this template:                                                                                 
    * attributes Array of name / value pairs.                                                                                     
                                                                                                                                   
    Example context (json):                                                                                                       
    {                                                                                                                             
        "attributes": [                                                                                                           
            { "name": "src", "value": "http://moodle.com/wp-content/themes/moodle/images/logo-hat2.png" },                         
            { "name": "class", "value": "iconsmall" }                                                                             
        ]                                                                                                                         
    }                                                                                                                             
                                                                                                                                   
  }}                                                                                                                                 
  <img {{#attributes}}{{name}}="{{value}}" {{/attributes}}/>
</pre>
 
== Coding style for templates ==
This section documents some coding style guidelines to follow when writing templates. The reason for these guidelines is to promote consistency, and interoperability of the templates.
This section documents some coding style guidelines to follow when writing templates. The reason for these guidelines is to promote consistency, and interoperability of the templates.


=== Include GPL at the top of each template ===
'''Include GPL at the top of each template'''. Templates are a form of code and it is appropriate to license them like any other code.


Templates are a form of code and it is appropriate to license them like any other code.
'''Include a documentation comment for each template.''' The exception is when you are overriding a template, if the documentation from the parent still applies, you do not need to copy it to the overridden template.


===Include a documentation comment for each template===
'''Use data-attributes for JS hooks'''. Data attributes are ideal for adding javascript hooks to templates because:
 
The exception is when you are overriding a template, if the documentation from the parent still applies, you do not need to copy it to the overridden template.
 
===Use data-attributes for JS hooks===
 
Data attributes are ideal for adding javascript hooks to templates because:
* Classes are meant for styling - theme designers should be able to change the classes at will without breaking any functionality.
* Classes are meant for styling - theme designers should be able to change the classes at will without breaking any functionality.
* IDs must be unique in the page, but it is not possible to control how many times the same template might be included in the page.
* IDs must be unique in the page, but it is not possible to control how many times the same template might be included in the page.
* Data attributes can have meaningful names and can be efficiently queried with a selector
* Data attributes can have meaningful names and can be efficiently queried with a selector.
 
===Avoid custom CSS for templates===
 
This is not a hard rule, but a preference. We already have too much CSS in Moodle - where ever possible we should try and re-use the existing CSS instead of adding new CSS to support every new template.
 
===Re-use core templates as much as possible===


First we need to build the core set of reusable templates - but once that is in place we should always try to re-use those core templates to build interfaces. This will make Moodle more consistent, attractive and customisable.


===Do use the CSS framework classes directly in the templates===
'''Avoid custom CSS for templates'''. This is not a hard rule, but a preference. We already have too much CSS in Moodle - where ever possible we should try and re-use the existing CSS instead of adding new CSS to support every new template.


We have bootstrap in core - so lets make the most of it. There is no problem using bootstrap classes in core templates, as long as the "base" theme is also tested, and an overridden template is added there if required.
'''Re-use core templates as much as possible''' - First we need to build the core set of reusable templates - but once that is in place we should always try to re-use those core templates to build interfaces. This will make Moodle more consistent, attractive and customisable.


===Avoid IDs for styling or javascript===
'''Do use the CSS framework classes directly in the templates''' - We have bootstrap in core - so lets make the most of it. There is no problem using bootstrap classes in core templates, as long as the "base" theme is also tested, and an overridden template is added there if required.


IDs should never evet be used for styling as they have a high CSS specificity, and so are hard to override. In addition, IDs should be unique in the page, which implies that a template could only be used once in a page. IDs are also not ideal for javascript, for the same reason (must be unique in a page).
'''Avoid IDs for styling or javascript''' - IDs should never evet be used for styling as they have a high CSS specificity, and so are hard to override. In addition, IDs should be unique in the page, which implies that a template could only be used once in a page. IDs are also not ideal for javascript, for the same reason (must be unique in a page).


The only acceptable case to use an ID is you need to create a one to one connection between the JS and template. In this case use the uniqid helper to generate an ID that will not conflict with any other template on the page, and use it as part of the ID.
The only acceptable case to use an ID is you need to create a one to one connection between the JS and template. In this case use the uniqid helper to generate an ID that will not conflict with any other template on the page, and use it as part of the ID.
 
<syntaxhighlight lang="html+handlebars">
<syntaxhighlight lang="php">
<div id="{{uniqid}}-somethingspecific">
<div id="{{uniqid}}-somethingspecific">
</div>
</div>
Line 476: Line 417:
{{/js}}
{{/js}}
</syntaxhighlight>
</syntaxhighlight>
'''Follow CSS coding style''' - See [[CSS coding style]]. Use hyphens as word-separators for class names. Use lower case class names.


===Follow CSS coding style===
'''Wrap each template in one node with a classname that matches the template name'''. Generate a class name by combining the component and template names and separating words with underscore.
 
https://docs.moodle.org/dev/CSS_coding_style
 
Use hyphens as word-separators for class names.
Use lower case class names.
 
===Wrap each template in one node with a classname that matches the template name===
 
Generate a class name by combining the component and template names and separating words with underscore.


e.g.
e.g.
 
<syntaxhighlight lang="html+handlebars">
<syntaxhighlight lang="php">
<div class="core_user_header">
<div class="core_user_header">
...
...
</div>
</div>
</syntaxhighlight>
</syntaxhighlight>
== Notes ==
=== Iterating over PHP arrays in Mustache templates ===
In PHP, both lists and hashes are implemented as arrays. But Mustache must treat them as different structures because of cross language compatibility. If the PHP array does not have the <code>[0]</code> key, or there are gaps in the keys sequence, Mustache will interpret that array as a hash and will not iterate over it.


[[Category:AJAX]]
So you need to make sure the elements in the list are properly indexed:
[[Category:Javascript]]
[[Category:Output]]
 
===Iterating over php arrays in a mustache template===
 
Mustache treats hashes and arrays differently because of cross language compatibility
In php arrays and hashes are the same, but mustache treats them differently
It decides a php array is a hash and will not iterate over it if it is non 0 indexed and/or has a gap in the key numbers
so in short
you need to
<syntaxhighlight lang="php">
<syntaxhighlight lang="php">
$datafortemplate->mylist = array_values($myarraywithnonnumerickeys)
$datafortemplate->mylist = array_values($myarraywithnonnumerickeys)
</syntaxhighlight>
</syntaxhighlight>
you could also use
=== Test for non-empty array in Mustache templates ===
<syntaxhighlight lang="php">
Short answer: you can't.
$datafortemplate->mylist = new ArrayIterator($myarraywithnonnumerickeys);
<syntaxhighlight lang="html+handlebars">
{{! This will work in PHP but not in JavaScript. }}
{{#users.0}} ... {{/users.0}}
</syntaxhighlight>
</syntaxhighlight>
BUT this fails when $myarraywithnonnumerickeys is empty and you try to use
<syntaxhighlight lang="html+handlebars">
<code html5>
{{! This will work in JavaScript but not in PHP. }}
{{#mylist}}
{{#users.length}} ... {{/users.length}}
with an array iterator if mylist is empty this block will not run
</syntaxhighlight>
{{/mylist}}
As a workaround, include a specific property in the context like "hasusers".
{{^mylist}}
<syntaxhighlight lang="json">
with an array iterator mylist will not run this block either because it is not quite empty
{
{{/mylist}}
    "hasusers": false,
    "users": []
}
</syntaxhighlight>
</syntaxhighlight>


===Test for not empty array in a mustache template===


Short answer you can't. Include a specific property in the context like "hasusers".
<syntaxhighlight lang="html+handlebars">
 
{{#hasusers}}
In php
    {{#users}}
<pre>
    ....
{{#users.0}} blah {{/users.0}}
    {{/users}}
</pre>
{{#hasusers}}
 
</syntaxhighlight>
will work but please don't use this syntax, it will break if the template is used in javascript AND it mucks up the context.
=== Squash whitespace in a template ===
 
Sometimes whitespace is significant, for example inside a link it will show with an underline. If you need two Mustache tags from separate lines to be rendered with no whitespace between them you can use Mustache comments to squash the whitespace.
In javascript
<syntaxhighlight lang="html+handlebars">
 
<pre>
{{#users.length}} blah {{/users.length}}
</pre>
 
will work but please don't use this syntax, it will break if the template is used in php.
 
===Squash whitespace in a template===
Sometimes whitespace is significant, for example inside a link it will show with an underline. If you want 2 mustache tags from separate lines to be rendered with no whitespace between them you can use mustache comments to squash the whitespace.
 
<pre>
<a href="blah">{{!
<a href="blah">{{!
}}{{icon}}{{!
}}{{icon}}{{!
}}{{name}}</a>
}}{{name}}</a>
</pre>
</syntaxhighlight>
 
=== Access to globals ===
== How do I write core templates? ==
In PHP you have access to $CFG object to allow access to properties. Mustache rendering also exposes a globals object automatically during rendering. For example:
<nowiki><a href="{{globals.config.wwwroot}}/login/logout.php?sesskey={{globals.config.sesskey}}">{{#str}}</nowiki> logout, core <nowiki>{{/str}}</nowiki><nowiki></a></nowiki>
The properties available on the <code>globals.config</code> object are the same as normally exposed for javascript; these are gathered from <code>get_config_for_javascript()</code> function in ''/lib/outputrequirementslib.php''.
== Core templates ==
Core templates should ideally be simple generic components that can be used within other templates to create more complex page layouts. They should be flexible enough for developers and themers to easily use without having to replace the template. The templates should attempt to encapsulate some core structure for the element as well as key classes while allowing the content to be easily overridden. Ultimately we want to avoid having duplicate HTML copied from template to template where possible, particularly if the HTML element has some classes associated with it.
Core templates should ideally be simple generic components that can be used within other templates to create more complex page layouts. They should be flexible enough for developers and themers to easily use without having to replace the template. The templates should attempt to encapsulate some core structure for the element as well as key classes while allowing the content to be easily overridden. Ultimately we want to avoid having duplicate HTML copied from template to template where possible, particularly if the HTML element has some classes associated with it.


Line 563: Line 483:
* Use block variables to indicate sections of your template that people are likely to want to change. Typically where they will be wanting to substitute in their own content.
* Use block variables to indicate sections of your template that people are likely to want to change. Typically where they will be wanting to substitute in their own content.
* Try to keep any javascript that accompanies the template as decoupled from the HTML / CSS structure of the template as possible. Instead of relying on the existence of certain HTML elements or CSS classes it is generally better to leverage data-attributes which can be added to any element.
* Try to keep any javascript that accompanies the template as decoupled from the HTML / CSS structure of the template as possible. Instead of relying on the existence of certain HTML elements or CSS classes it is generally better to leverage data-attributes which can be added to any element.
=== An example: tabs ===
Let's go through an example to illustrate how you might build a core template. For the example we'll be building a tabs template, since it's a fairly complex component that requires the use of block variables and javascript.
Let's go through an example to illustrate how you might build a core template. For the example we'll be building a tabs template, since it's a fairly complex component that requires the use of block variables and javascript.


First we can create a basic template to get the general structure down, let's call it tabs. Here's what it might look like:
First we can create a basic template to get the general structure down, let's call it tabs. Here's what it might look like:
<pre>
<syntaxhighlight lang="html+handlebars">
<div id="{{ uniqid }}-tab-container">
<div id="{{ uniqid }}-tab-container">
     <ul role="tablist" class="nav nav-tabs">
     <ul role="tablist" class="nav nav-tabs">
Line 600: Line 518:
     });
     });
{{/js}}
{{/js}}
</pre>
</syntaxhighlight>
 
The template requires a context that looks something like:
The template requires a context that looks something like:
<pre>
<syntaxhighlight lang="json">
{
{
"tabs": [
    "tabs": [
{"id":"tab1","name":"Tab 1","content":"This is tab 1 content <a href=\"#\">test</a>"},
        {"id":"tab1","name":"Tab 1","content":"This is tab 1 content <a href=\"#\">test</a>"},
{"id":"tab2","name":"Tab 2","content":"This is tab 2 content <a href=\"#\">test</a>"},
        {"id":"tab2","name":"Tab 2","content":"This is tab 2 content <a href=\"#\">test</a>"},
{"id":"tab3","name":"Tab 3","content":"This is tab 3 content <a href=\"#\">test</a>"}
        {"id":"tab3","name":"Tab 3","content":"This is tab 3 content <a href=\"#\">test</a>"}
]
    ]
}
}
</pre>
</syntaxhighlight>
 
The javascript required to power the tabs element (keyboard navigation, show / hide panels etc) is written as an AMD module and is included by the template. The javascript is a little too large to go through here, but some key points to consider when writing it are: It should ideally be independent of the HTML structure, so if someone wants to completely rewrite the tabs to be different elements (e.g. buttons or a set of divs) then the same javascript can be used without needing to change it. In order to achieve this it is important to identify the key components of the template.
The javascript required to power the tabs element (keyboard navigation, show / hide panels etc) is written as an AMD module and is included by the template. The javascript is a little too large to go through here, but some key points to consider when writing it are:
It should ideally be independent of the HTML structure, so if someone wants to completely rewrite the tabs to be different elements (e.g. buttons or a set of divs) then the same javascript can be used without needing to change it. In order to achieve this it is important to identify the key components of the template.


In this case it is a tab list, a tab and it's content. One way to identify these components would be to inspect the structure of the DOM, for example you might say "find me the ul element" when looking for the tab list and then "find my the child li elements" to find the tabs. While this would work, it couples your javascript to the HTML structure and makes it difficult to change later. A different approach would be to use the element attributes, for example you might say "find my the element with the role 'tablist'" to get the tab list and then "find me the elements with the role 'tab'" to get the tabs. This allows the HTML structure to change without breaking the javascript (as long as the correct attributes are set, of course).
In this case it is a tab list, a tab and it's content. One way to identify these components would be to inspect the structure of the DOM, for example you might say "find me the ul element" when looking for the tab list and then "find my the child li elements" to find the tabs. While this would work, it couples your javascript to the HTML structure and makes it difficult to change later. A different approach would be to use the element attributes, for example you might say "find my the element with the role 'tablist'" to get the tab list and then "find me the elements with the role 'tab'" to get the tabs. This allows the HTML structure to change without breaking the javascript (as long as the correct attributes are set, of course).
Line 623: Line 538:


Here's what the page might look like:
Here's what the page might look like:
<pre>
<syntaxhighlight lang="html+handlebars">
<html>
<html>
     <header><title>User Profile</title></header>
     <header><title>User Profile</title></header>
Line 630: Line 545:
     </body>
     </body>
</html>
</html>
</pre>
</syntaxhighlight>
 
That looks pretty simple! The only problem is, how do I get my content there? I would have to supply a context like this in order to display the tabs I want:
That looks pretty simple! The only problem is, how do I get my content there? I would have to supply a context like this in order to display the tabs I want:
<pre>
<syntaxhighlight lang="json">
{
{
"tabs": [
    "tabs": [
{"id":"tab1","name":"Name","content":"Your name is Mr. Test User."},
        {"id":"tab1","name":"Name","content":"Your name is Mr. Test User."},
{"id":"tab2","name":"Email","content":"Your email is testuser@example.com"},
        {"id":"tab2","name":"Email","content":"Your email is testuser@example.com"},
]
    ]
}
}
</pre>
</syntaxhighlight>
 
Let's assume that the context for this page doesn't match what the tabs template is expecting though. Let's assume the tabs template is being rendered with this context:
Let's assume that the context for this page doesn't match what the tabs template is expecting though (as will be the case most of the time). Let's assume the tabs template is being rendered with this context:
<syntaxhighlight lang="json">
<pre>
{
{
"name":"Mr. Test User",
    "name":"Mr. Test User",
"email":"testuser@example.com"
    "email":"testuser@example.com"
}
}
</pre>
</syntaxhighlight>
 
Unfortunately, we'll almost certainly never have complete control over all of the contexts that our template will be rendered in which means we'll be expecting people to write new webservices to supply the same data in different formats every time they want to use a template. It becomes an unmanageable problem.
Unfortunately, we'll almost certainly never have complete control over all of the contexts that our template will be rendered in which means we'll be expecting people to write new webservices to supply the same data in different formats every time they want to use a template. It becomes an unmanageable problem.


Line 655: Line 567:


Let's have another go at that template, this time leveraging blocks:
Let's have another go at that template, this time leveraging blocks:
<pre>
<syntaxhighlight lang="html+handlebars">
<div id="{{ uniqid }}-tab-container">
<div id="{{ uniqid }}-tab-container">
{{$ tabheader }}
{{$ tabheader }}
Line 695: Line 607:
     });
     });
{{/js}}
{{/js}}
</pre>
</syntaxhighlight>
 
A summary of what we've changed:
A summary of what we've changed:
* Added a $tabheader block around the tab list, in case someone wants to change the ul element to something else.
* Added a $tabheader block around the tab list, in case someone wants to change the ul element to something else.
Line 702: Line 613:
* Added a $tabbody block around the content, in case someone wants to change the content elements from divs.
* Added a $tabbody block around the content, in case someone wants to change the content elements from divs.
* Added a $tabcontent block around the tab variable for the content to allow the content to be overriden on inlcude.
* Added a $tabcontent block around the tab variable for the content to allow the content to be overriden on inlcude.
Now let's see what using this template looks like for your User Profile page:
Now let's see what using this template looks like for your User Profile page:
<pre>
<syntaxhighlight lang="html+handlebars">
<html>
<html>
     <header><title>User Profile</title></header>
     <header><title>User Profile</title></header>
Line 744: Line 654:
     </body>
     </body>
</html>
</html>
</pre>
</syntaxhighlight>
 
That looks a bit better! Now we've been able to use the blocks to successfully change the template to use the context available to this page, we no longer need a "tabs" array with "name" and "content". Even the javascript will continue to work because we've kept the correct element attributes.  
That looks a bit better! Now we've been able to use the blocks to successfully change the template to use the context available to this page, we no longer need a "tabs" array with "name" and "content". Even the javascript will continue to work because we've kept the correct element attributes.  


Line 753: Line 662:


tabs.mustache:
tabs.mustache:
<pre>
<syntaxhighlight lang="html+handlebars">
<div id="{{ uniqid }}-tab-container">
<div id="{{ uniqid }}-tab-container">
{{$ tabheader }}
{{$ tabheader }}
Line 781: Line 690:
     });
     });
{{/js}}
{{/js}}
</pre>
</syntaxhighlight>
 
tab_header_item.mustache
tab_header_item.mustache
<pre>
<syntaxhighlight lang="html+handlebars">
<li role="tab"
<li role="tab"
data-selected-class="active"
data-selected-class="active"
Line 791: Line 699:
<a href="#">{{$ tabname }}{{{ name }}}{{/ tabname }}</a>
<a href="#">{{$ tabname }}{{{ name }}}{{/ tabname }}</a>
</li>
</li>
</pre>
</syntaxhighlight>
 
tab_content_item.mustache
tab_content_item.mustache
<pre>
<syntaxhighlight lang="html+handlebars">
<div role="tabpanel"
<div role="tabpanel"
class="tab-pane"
class="tab-pane"
Line 800: Line 707:
{{$ tabpanelcontent }}{{{ content }}}{{/ tabpanelcontent }}
{{$ tabpanelcontent }}{{{ content }}}{{/ tabpanelcontent }}
</div>
</div>
</pre>
</syntaxhighlight>
 
A summary of the changes:
A summary of the changes:
* Split the template into 3, moving the tab into it's own template and the content into it's own and then including them in the tabs template.
* Split the template into 3, moving the tab into it's own template and the content into it's own and then including them in the tabs template.
Line 807: Line 713:
* Added a $tabname block for in the tab_header_item template to make the name flexible on import.
* Added a $tabname block for in the tab_header_item template to make the name flexible on import.
* Added a $tabpanelcontant block in the tab_content_item template to make the content flexible on import.
* Added a $tabpanelcontant block in the tab_content_item template to make the content flexible on import.
Cool, so let's see what that looks like in our example now:
Cool, so let's see what that looks like in our example now:
<pre>
<syntaxhighlight lang="html+handlebars">
<html>
<html>
     <header><title>User Profile</title></header>
     <header><title>User Profile</title></header>
Line 833: Line 738:
     </body>
     </body>
</html>
</html>
</pre>
</syntaxhighlight>
 
And we're done! After making the changes above we've been able to keep the benefits of the previous change to allow the context changes but we've also removed the need to copy & paste the HTML everywhere. Instead we're able to use the child templates with a few additional blocks defined to get the content in there.
And we're done! After making the changes above we've been able to keep the benefits of the previous change to allow the context changes but we've also removed the need to copy & paste the HTML everywhere. Instead we're able to use the child templates with a few additional blocks defined to get the content in there.


Now if we want to change tabs HTML or CSS frameworks we can just change the core tabs templates and this page will receive the updates for free.
Now if we want to change tabs HTML or CSS frameworks we can just change the core tabs templates and this page will receive the updates for free.
[[Category:AJAX]]
[[Category:Javascript]]
[[Category:Output]]

Latest revision as of 14:08, 9 June 2022

Important:

This content of this page has been updated and migrated to the new Moodle Developer Resources. The information contained on the page should no longer be seen up-to-date.

Why not view this page on the new site and help us to migrate more content to the new site!

Moodle 2.9


Templates in Moodle are used for rendering the output such as HTML or email messages bodies. Templates are defined as a text with placeholder tags. Placeholder tags are replaced with actual values during the rendering. Templates can be rendered both on the server side in PHP as well as on the client side in JavaScript. Themes can override the default templates. Moodle uses Mustache template system.

Simple example

Given the template is defined as:

<div class="alert alert-info">
    <strong>Hello {{name}}!</strong> Your grade is: <strong>{{grade}}</strong>
</div>

And the values for the placeholder tags name and grade are provided as a JSON object, referred to as rendering context (note the context here has nothing to do with Moodle permission contexts. In Mustache, the term basically represents the data passed to the template).

{
    "name": "Bobby",
    "grade": 10
}

Then the rendered result will look like:

Hello Bobby! Your grade is: 10

The following page provides information about the Mustache templates syntax and how to use them in Moodle.

Syntax

Mustache tags are made of two opening and closing curly braces. Their shape looks like a moustache, thence the name.

Variables

{{name}}
{
    "name": "Bobby"
}

The value of the key name will be searched for in the current rendering context (and any parent contexts) and when a value is found, the entire tag will be replaced by the value (HTML escaped).

Raw unescaped variable

All variables are HTML escaped by default. If you want to render raw unescaped HTML, use the triple mustache:

{{{description}}}
{
    "description": "<h1>Hello!</h1><p>In this course you will learn about ...</p>"
}

Beware of the security implications of outputting raw HTML and make sure that the value of the variable has been processed by format_text() or another adequate way.

Sections

Sections render blocks of text zero, one or more times, depending on the value of the key in the current context. The opening tag has a hash (pound) sign and the closing tag has a slash, followed by the key.

False values and empty lists

When the key is false or an empty list, the HTML between the opening and closing tag will not be displayed. This can be effectively used to conditionally control the rendering of a section.

{{#hasdata}}
    This will not be shown if 'hasdata' is empty.
{{/hasdata}}
{
    "hasdata": false
}

Non-empty lists

When the value is a non-empty list, the text in the block will be displayed once for each item in the list. The context of the block will be set to the current item for each iteration. In this way we can loop over collections.

<ul>
    {{#grades}}
    <li>
        <em>{{course}}</em> - {{grade}}
    </li>
    {{/grades}}
</ul>
{
    "grades": [
        {
            "course": "Arithmetic",
            "grade": "8/10"
        },
        {
            "course": "Geometry",
            "grade": "10/10"
        }
    ]
}

Lambdas

When the value is a callable, it will be invoked and returned value used as the section value. In Moodle plugins, this can be used to call the core_renderer methods via the output context variable:

{{#output.should_display_navbar_logo}}
    <img src="{{output.get_compact_logo_url}}">
{{/output.should_display_navbar_logo}}

Inverted sections

Inverted sections will be rendered if the key does not exist, is false, or is an empty list. An inverted section begins with a caret (hat) and ends with a slash.

{{#hasgrade}}
    Your grade is: <strong>{{grade}}</strong>
{{/hasgrade}}

{{^hasgrade}}
    Your work has not been graded yet.
{{/hasgrade}}
{
    "hasgrade": false,
    "grade": null
}

Comments

Comments begin with an exclamation mark. The whole section is ignored. Comments are used for boilerplate documentation. They can also be used to avoid having extra break-lines in the generated output.

{{!
    This is a comment and will not be present in the rendered result.
}}

Partials

Templates can include other templates using the partial tag. Partials begin with a greater than sign. Partials are rendered at runtime and allow to split complex templates into smaller, potentially re-usable units. Moodle core provides with many templates that can be included this way.

{{! Show the loading icon. }}
<div class="p-5">
    {{> core/loading }}
</div>

The included template uses the same rendering context as its parent template.

Blocks

Moodle 3.0

Mustache template system can be extended via so called Mustache pragmas. Pragmas are non-standard extensions to the Mustache spec. Moodle 3.0 and higher has BLOCKS pragma installed and enabled.

The extension allows you to define a parent template with replaceable blocks. Blocks look like sections that use dollar sign in the opening tag. The following parent template defines two blocks heading and content

{{!
    @template tool_demo/section
}}
<section>
    <h1>
        {{$heading}} Default section heading {{/heading}}
    </h1>
    <div>
        {{$content}} Default section content {{/content}}
    </div>
</section>

Particular child templates can now extend / inherit from this parent template and override the default block values.

{{!
    @template tool_demo/latestnews
}}
{{< tool_demo/section }}
    {{$heading}} Latest news {{/heading}}
    {{$content}} Today I learned how to use blocks in Mustache! {{/content}}
{{/ tool_demo/section}}

Blocks are particularly useful for building a library of re-usable components.

Helpers

Moodle providers several Mustache helpers. Helpers tags look like sections eventually containing zero or more parameters.

str

The {{#str}} is a string helper for loading text strings from language packs. It effectively represents Mustache variant of get_string() calls.

{{#str}} helloworld, mod_greeting {{/str}}

The first two parameters are the string identifier and the component name. The optional third parameter defines the value for the string's $a placeholder. Literals as well as variable tags are allowed to define the value.

{{#str}} backto, core, Moodle.org {{/str}}

{{#str}} backto, core, {{name}} {{/str}}

For strings that accept non-scalar placeholders, see the following section.

Note: if you want to do a help icon, and wondering "where is the helper for that?" then acutally, it is not a helper. You need to use {{>core/help_icon}} as a partial.

quote

The {{#quote}} is used to quote non-scalar {{#str}} arguments.

Some strings accept complex non-scalar data structures passed as the value of the $a placeholder. You can use a JSON object syntax in that case:

{{#str}} counteditems, core, { "count": "42", "items": "courses" } {{/str}}

If you wanted to use the context values instead of literal values, you might intuitively use something like this:

{{! DO NOT DO THIS !}}
{{#str}} counteditems, core, { "count": {{count}}, "items": {{itemname}} } {{/str}}

There is a potential problem though. If the variable tag itemname evaluates to a string containing double quotes, it will break the JSON syntax. We need to escape certain characters potentially appearing in the variable tags. For this, we use the {{#quote}} helper.

{{#str}} counteditems, core, { "count": {{count}}, "items": {{#quote}} {{itemname}} {{/quote}} } {{/str}}

pix

The {{#pix}} is a icon picture helper for generating pix icon tags.

{{#pix}} t/edit, core, Edit this section {{/pix}}

The first two parameters are the icon identifier and the component name. The rest is the alt text for the icon.

See Using images in a theme and Moodle_icons for some background information about pix icons in Moodle.

userdate

Moodle 3.3

The {{#userdate}} helper will format UNIX timestamps into a given human readable date format while using the user's timezone settings configured (if any) in Moodle. The helper will accept hardcoded values, context variables, or other helpers.

It is recommended to use the string helper to get one of the core Moodle formats.

{
    "time": 1628871929
}
{{#userdate}} {{time}}, {{#str}} strftimedate, core_langconfig {{/str}} {{/userdate}}

This will ask the Moodle server for the string "strftimedate" and will use the value (which in this case is "%d %B %Y" in case of English) to format the user date. So the resulting formatted timestamp from the userdate helper would be like "13 August 2021".

shortentext

Moodle 3.3

The {{#shortentext}} helper can be used to shorten a large amount of text to a specified length and will append a trailing ellipsis to signify that the text has been shortened.

The algorithm will attempt to preserve words while shortening to text. Words, for the purposes of the helper, are considered to be groups of consecutive characters broken by a space or, in the case of a multi-byte character, after the completion of the multi-byte character (rather than in the middle of the character).

It will also attempt to preserve HTML in the text by keeping the opening and closing tags. Only text within the tags will be considered when calculating how much should be truncated to reach the desired length.

The helper takes two comma separated arguments. The first is the desired length and the second is the text to be shortened. Both can be provided as context variables.

{
    "description": "<p><em>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur lacinia pretium nulla gravida interdum.</em></p>"
}
{{#shortentext}} 15, {{{description}}} {{/shortentext}}

Template files

Templates are saved in templates/*.mustache files within core components and plugins folders. When loading them, templates are identified by their full component name followed by slash and the filename without the file extension.

Example: A timer template provided by the mod_lesson module would be referred to as mod_lesson/timer and it would be located in mod/lesson/templates/timer.mustache file.

Since Moodle 3.8 it is possible to use sub-directories under the templates directory. The first sub-directory name must meet certain naming rules (same as for class namespaces).

Mustache file boilerplate

{{!
    This file is part of Moodle - https://moodle.org/

    Moodle is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    Moodle is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
}}
{{!
    @template plugintype_pluginname/template_name

    Template purpose and description.

    Classes required for JS:
    * none

    Data attributes required for JS:
    * none

    Context variables required for this template:
    * none

    Example context (json):
    {
    }
}}

Rendering in PHP

Use the render_from_template() method to render the given context data with the template.

$data = [
    'name' => 'Lorem ipsum',
    'description' => format_text($description, FORMAT_HTML),
];

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

Renderers

Templates can be effectively used in renderers to generate the HTML representing the given renderable object. Make your renderable class also implement templatable interface. It will have to implement a new method export_for_template(renderer_base $output). The method should return a JSON-serialisable object (containing only objects, arrays and scalars) that will be passed as the rendering context data to a template.

In the simplest case where you have a renderable, templatable object with a class name matching the name of the template that will render it, you do not need to add any renderer code explicity. Passing your widget directly to $OUTPUT->render() will infer the name of your template, call export_for_template() and render_from_template(), then return the result.

Example of the method added to the renderable mywidget:

/**
 * Describe the renderable widget so it can be renderer by a mustache template.
 *
 * @param renderer_base $output
 * @return stdClass
 */
public function export_for_template(renderer_base $output) {

    $data = new stdClass();
    $data->canmanage = $this->canmanage;
    $data->things = [];
    foreach ($this->things as $thing) {
        $data->things[] = $thing->to_record();
    }
    $data->navigation = [];
    foreach ($this->navigation as $button) {
        $data->navigation[] = $output->render($button);
    }

    return $data;
}

The rendering method can now use templates to render the object:

/**
 * Render mywidget via a template.
 *
 * @param mywidget $widget
 *
 * @return string HTML
 */
protected function render_mywidget(mywidget $widget) {
    $data = $widget->export_for_template($this);
    return $this->render_from_template('tool_myplugin/mywidget', $data);
}

In your page:

$output = $PAGE->get_renderer('tool_myplugin');
echo $output->render($widget);

Rendering in JavaScript

Rendering a template from JavaScript is fairly easy. There is a JavaScript module that can load (and cache) a template and then use it for rendering the given data.

import {exception as displayException} from 'core/notification';
import Templates from 'core/templates';

// This will be the context for our template. So {{name}} in the template will resolve to "Tweety bird".
const context = {
    name: 'Tweety bird',
    intelligence: 2,
};

// This will call the function to load and render our template.
Templates.renderForPromise('block_looneytunes/profile', context)

// It returns a promise that needs to be resoved.
    .then(({html, js}) => {
        // Here eventually I have my compiled template, and any javascript that it generated.
        // The templates object has append, prepend and replace functions.
        Templates.appendNodeContents('.block_looneytunes .content', html, js);
    })

    // Deal with this exception (Using core/notify exception function is recommended).
    .catch(ex => displayException(ex));

Under the hood, this does a few clever things for us. It loads the template via an AJAX call if it was not cached. It finds any missing lang strings in the template and loads them in a single AJAX request. It split the JS from the HTML and returns us both in easy to use way. Read on for how to nicely deal with that js parameter.

Template requires JavaScript

Sometimes a template requires that some JavaScript runs when it is added to the page in order to give it more features. In the template we can include blocks of JavaScript, but we should use a special section tag that has a "helper" method registered to handle JavaScript carefully.

Example

<!-- HTML here -->>
{{^element.frozen}}
{{#js}}
require(['theme_boost/form-display-errors'], function(module) {
    module.enhance({{#quote}}{{element.id}}{{/quote}});
});
{{/js}}
{{/element.frozen}}

If this template is rendered by PHP, the JavaScript is separated from the HTML, and is appended to a special section in the footer of the page "after" requirejs has loaded. This provides the optimal page loading speed. If the template is rendered by JavaScript, the JavaScript source will be passed to the "done" handler from the promise. Then, when the "done" handler has added the template to the DOM, it can call

templates.runTemplateJS(javascript);

which will run the javascript (by creating a new script tag and appending it to the page head).

Note: It is recommended that the JavaScript present be kept to a minimum - preferably just the inclusion of a module designed to do the actual work. This allows for a template to be overridden by a renderer without the JavaScript having to be copied. It also enforces appropriate linting and minification of the code.

Overriding templates in a theme

Templates can be overridden by a theme.

  1. Find the template that you want to change - e.g. mod/wiki/templates/ratingui.mustache
  2. Create a sub-folder under your themes "templates" directory with the component name of the plugin you are overriding - e.g theme/timtam/templates/mod_wiki
  3. Copy the ratingui.mustache file into the newly created theme/timtam/templates/mod_wiki and edit it.

You should see your changes immediately if theme designer mode is on. Templates are cached just like CSS, so if you are not using theme designer mode you will need to purge all caches to see the latest version of an edited template. If the template you are overriding contains a documentation comment it is recommended to remove it. It will still show the documentation in the template library.

Documenting the templates

Theme designers need to know the limits of what they can expect to change without breaking anything. Also, correctly documented templates can be previewed in the "Template library" tool shipped with Moodle.

  • Classes required for JS - This is a list of classes that are used by the javascript for this template. If removing a class from an element in the template will break the javascript, list it here.
  • Data attributes required for JS - This is a list of data attributes (e.g. data-enhance="true") that are used by the javascript for this template. If removing a data attribute from an element in the template will break the javascript, list it here.
  • Context variables required for this template - This is a description of the data that may be contained in the context that is passed to the template. Be explicit and document every attribute.
  • Example context (JSON) - The Template library will look for this data in your documentation comment as it allows it to render a "preview" of the template right in the Template library. This is useful for theme designers to test all the available templates in their new theme to make sure they look nice in a new theme. It is also useful to make sure the template responds to different screen sizes, languages and devices. The format is a JSON-encoded object that is passed directly into the render method for this template.

Coding style

This section documents some coding style guidelines to follow when writing templates. The reason for these guidelines is to promote consistency, and interoperability of the templates.

Include GPL at the top of each template. Templates are a form of code and it is appropriate to license them like any other code.

Include a documentation comment for each template. The exception is when you are overriding a template, if the documentation from the parent still applies, you do not need to copy it to the overridden template.

Use data-attributes for JS hooks. Data attributes are ideal for adding javascript hooks to templates because:

  • Classes are meant for styling - theme designers should be able to change the classes at will without breaking any functionality.
  • IDs must be unique in the page, but it is not possible to control how many times the same template might be included in the page.
  • Data attributes can have meaningful names and can be efficiently queried with a selector.


Avoid custom CSS for templates. This is not a hard rule, but a preference. We already have too much CSS in Moodle - where ever possible we should try and re-use the existing CSS instead of adding new CSS to support every new template.

Re-use core templates as much as possible - First we need to build the core set of reusable templates - but once that is in place we should always try to re-use those core templates to build interfaces. This will make Moodle more consistent, attractive and customisable.

Do use the CSS framework classes directly in the templates - We have bootstrap in core - so lets make the most of it. There is no problem using bootstrap classes in core templates, as long as the "base" theme is also tested, and an overridden template is added there if required.

Avoid IDs for styling or javascript - IDs should never evet be used for styling as they have a high CSS specificity, and so are hard to override. In addition, IDs should be unique in the page, which implies that a template could only be used once in a page. IDs are also not ideal for javascript, for the same reason (must be unique in a page).

The only acceptable case to use an ID is you need to create a one to one connection between the JS and template. In this case use the uniqid helper to generate an ID that will not conflict with any other template on the page, and use it as part of the ID.

<div id="{{uniqid}}-somethingspecific">
</div>
{{#js}}
    callFunction('{{uniqid}}-somethingspecific');
{{/js}}

Follow CSS coding style - See CSS coding style. Use hyphens as word-separators for class names. Use lower case class names.

Wrap each template in one node with a classname that matches the template name. Generate a class name by combining the component and template names and separating words with underscore.

e.g.

<div class="core_user_header">
...
</div>

Notes

Iterating over PHP arrays in Mustache templates

In PHP, both lists and hashes are implemented as arrays. But Mustache must treat them as different structures because of cross language compatibility. If the PHP array does not have the [0] key, or there are gaps in the keys sequence, Mustache will interpret that array as a hash and will not iterate over it.

So you need to make sure the elements in the list are properly indexed:

$datafortemplate->mylist = array_values($myarraywithnonnumerickeys)

Test for non-empty array in Mustache templates

Short answer: you can't.

{{! This will work in PHP but not in JavaScript. }}
{{#users.0}} ... {{/users.0}}
{{! This will work in JavaScript but not in PHP. }}
{{#users.length}} ... {{/users.length}}

As a workaround, include a specific property in the context like "hasusers".

{
    "hasusers": false,
    "users": []
}


{{#hasusers}}
    {{#users}}
    ....
    {{/users}}
{{#hasusers}}

Squash whitespace in a template

Sometimes whitespace is significant, for example inside a link it will show with an underline. If you need two Mustache tags from separate lines to be rendered with no whitespace between them you can use Mustache comments to squash the whitespace.

<a href="blah">{{!
}}{{icon}}{{!
}}{{name}}</a>

Access to globals

In PHP you have access to $CFG object to allow access to properties. Mustache rendering also exposes a globals object automatically during rendering. For example:

<a href="{{globals.config.wwwroot}}/login/logout.php?sesskey={{globals.config.sesskey}}">{{#str}} logout, core {{/str}}</a>

The properties available on the globals.config object are the same as normally exposed for javascript; these are gathered from get_config_for_javascript() function in /lib/outputrequirementslib.php.

Core templates

Core templates should ideally be simple generic components that can be used within other templates to create more complex page layouts. They should be flexible enough for developers and themers to easily use without having to replace the template. The templates should attempt to encapsulate some core structure for the element as well as key classes while allowing the content to be easily overridden. Ultimately we want to avoid having duplicate HTML copied from template to template where possible, particularly if the HTML element has some classes associated with it.

Mustache relies on variables to substitute context data into the template but unfortunately it's very unlikely that the the names of the context data will match what the template is expecting for all the places that the template might be used. So in order to allow easy extensibility and avoid having to duplicate templates just to rename the variables we can wrap them in block variables which would allow the template that is including our template to replace that variable with one from it's own context inline.

There are a few key points to keep in mind when writing a core template:

  • Consider how your template will actually be used. Try writing a test page that uses your template to help discover some of the assumptions you might have in the template.
  • The example context you provide in the template is mostly just for showing the template in the template library and is likely not how your template will actually be used. Most uses of the template will have a different context all together.
  • Try to enforce a core structure but avoid enforcing a specific context. Content should be overridable.
  • Use block variables to indicate sections of your template that people are likely to want to change. Typically where they will be wanting to substitute in their own content.
  • Try to keep any javascript that accompanies the template as decoupled from the HTML / CSS structure of the template as possible. Instead of relying on the existence of certain HTML elements or CSS classes it is generally better to leverage data-attributes which can be added to any element.

Let's go through an example to illustrate how you might build a core template. For the example we'll be building a tabs template, since it's a fairly complex component that requires the use of block variables and javascript.

First we can create a basic template to get the general structure down, let's call it tabs. Here's what it might look like:

<div id="{{ uniqid }}-tab-container">
    <ul role="tablist" class="nav nav-tabs">
		{{# tabs }}
			<li role="tab"
					data-target="{{ uniqid }}-{{ id }}"
					data-selected-class="active"
					aria-controls="{{ uniqid }}-{{ id }}"
					aria-selected="false" tabindex="-1">

				<a href="#">{{{ name }}}</a>
			</li>
		{{/ tabs }}
	</ul>
    <div class="tab-content">
		{{# tabs }}
			<div role="tabpanel"
				class="tab-pane"
				id="{{ uniqid }}-{{ id }}">

				{{{ content }}}
			</div>
		{{/ tabs }}
	</div>
</div>
{{#js}}
    require(['jquery','core/tabs'], function($, tabs) {

        var container = $("#{{ uniqid }}-tab-container");
        tabs.create(container);
    });
{{/js}}

The template requires a context that looks something like:

{
    "tabs": [
        {"id":"tab1","name":"Tab 1","content":"This is tab 1 content <a href=\"#\">test</a>"},
        {"id":"tab2","name":"Tab 2","content":"This is tab 2 content <a href=\"#\">test</a>"},
        {"id":"tab3","name":"Tab 3","content":"This is tab 3 content <a href=\"#\">test</a>"}
    ]
}

The javascript required to power the tabs element (keyboard navigation, show / hide panels etc) is written as an AMD module and is included by the template. The javascript is a little too large to go through here, but some key points to consider when writing it are: It should ideally be independent of the HTML structure, so if someone wants to completely rewrite the tabs to be different elements (e.g. buttons or a set of divs) then the same javascript can be used without needing to change it. In order to achieve this it is important to identify the key components of the template.

In this case it is a tab list, a tab and it's content. One way to identify these components would be to inspect the structure of the DOM, for example you might say "find me the ul element" when looking for the tab list and then "find my the child li elements" to find the tabs. While this would work, it couples your javascript to the HTML structure and makes it difficult to change later. A different approach would be to use the element attributes, for example you might say "find my the element with the role 'tablist'" to get the tab list and then "find me the elements with the role 'tab'" to get the tabs. This allows the HTML structure to change without breaking the javascript (as long as the correct attributes are set, of course).

Another point of consideration for this example is what class to apply to a tab when it is selected. It makes sense to just apply something like "active" in the javascript, but that once again couples it to a particular CSS framework which makes it more difficult to change without modifying the javascript. In this case I chose to add a data attribute to the element to indicate which class will be set when the tab is selected. This means the javascript doesn't have to guess what the appropriate class is, it can just get it from the template.

Ok, so we've got our basic template. It's time to use it! Let's say we want to create a simple user profile page that might show 2 tabs, the first tab will be the user's name and the second tab will be the user's email address (please excuse the contrived example).

Here's what the page might look like:

<html>
    <header><title>User Profile</title></header>
    <body>
        {{< core/tabs }}
    </body>
</html>

That looks pretty simple! The only problem is, how do I get my content there? I would have to supply a context like this in order to display the tabs I want:

{
    "tabs": [
        {"id":"tab1","name":"Name","content":"Your name is Mr. Test User."},
        {"id":"tab2","name":"Email","content":"Your email is testuser@example.com"},
    ]
}

Let's assume that the context for this page doesn't match what the tabs template is expecting though. Let's assume the tabs template is being rendered with this context:

{
    "name":"Mr. Test User",
    "email":"testuser@example.com"
}

Unfortunately, we'll almost certainly never have complete control over all of the contexts that our template will be rendered in which means we'll be expecting people to write new webservices to supply the same data in different formats every time they want to use a template. It becomes an unmanageable problem.

Enter blocks! We can make the template more flexible by defining sections of the template that can be overriden when they are included. Pretty neat! This will allow us to enforce a certain core structure but not enforce a context on the template that is including the tabs.

Let's have another go at that template, this time leveraging blocks:

<div id="{{ uniqid }}-tab-container">
	{{$ tabheader }}
		<ul role="tablist" class="nav nav-tabs">
			{{$ tablist }}
				{{# tabs }}
					<li role="tab"
							data-target="{{ uniqid }}-{{ id }}"
							data-selected-class="active"
							aria-controls="{{ uniqid }}-{{ id }}"
							aria-selected="false" tabindex="-1">

						<a href="#">{{{ name }}}</a>
					</li>
				{{/ tabs }}
			{{/ tablist }}
		</ul>
	{{/ tabheader }}
	{{$ tabbody }}
		<div class="tab-content">
			{{$ tabcontent }}
				{{# tabs }}
					<div role="tabpanel"
						class="tab-pane"
						id="{{ uniqid }}-{{ id }}">

						{{{ content }}}
					</div>
				{{/ tabs }}
			{{/ tabcontent }}
		</div>
	{{/ tabbody }}
</div>
{{#js}}
    require(['jquery','core/tabs'], function($, tabs) {

        var container = $("#{{ uniqid }}-tab-container");
        tabs.create(container);
    });
{{/js}}

A summary of what we've changed:

  • Added a $tabheader block around the tab list, in case someone wants to change the ul element to something else.
  • Added a $tablist block around the group of tabs to allow them to be overriden on incldue.
  • Added a $tabbody block around the content, in case someone wants to change the content elements from divs.
  • Added a $tabcontent block around the tab variable for the content to allow the content to be overriden on inlcude.

Now let's see what using this template looks like for your User Profile page:

<html>
    <header><title>User Profile</title></header>
    <body>
        {{> core/tabs }}
			{{$ tablist }}
				<li role="tab"
						data-target="{{ uniqid }}-tab1"
						data-selected-class="active"
						aria-controls="{{ uniqid }}-tab1"
						aria-selected="false" tabindex="-1">

					<a href="#">Name</a>
				</li>
				<li role="tab"
						data-target="{{ uniqid }}-tab2"
						data-selected-class="active"
						aria-controls="{{ uniqid }}-tab2"
						aria-selected="false" tabindex="-1">

					<a href="#">Email</a>
				</li>
			{{/ tablist }}
			{{$ tabcontent }}
				<div role="tabpanel"
					class="tab-pane"
					id="{{ uniqid }}-tab1">

					Your name is {{ name }}.
				</div>
				<div role="tabpanel"
					class="tab-pane"
					id="{{ uniqid }}-tab2">

					Your email address is {{ email }}.
				</div>
			{{/ tabcontent }}
		{{/ core/tabs }}
    </body>
</html>

That looks a bit better! Now we've been able to use the blocks to successfully change the template to use the context available to this page, we no longer need a "tabs" array with "name" and "content". Even the javascript will continue to work because we've kept the correct element attributes.

We've still got a slight problem though... In order to change the data for the template we've had to copy & paste the HTML from the original template into our blocks as we do the override. While this works fine in this example, it means we don't quite get the encapsulation we want within the templates since we're leaking internal implementation details. If we ever wanted to change the CSS framework we use for Moodle (say from bootstrap 2 to boostrap 3 or 4) we'd have to find all the places in the code where this tabs template is used and make sure that the HTML is correct in their block overrides.

With that in mind, let's take one more pass at this template and see if we can improve it slightly again. This time we're doing to split the template out into 3 templates.

tabs.mustache:

<div id="{{ uniqid }}-tab-container">
	{{$ tabheader }}
		<ul role="tablist" class="nav nav-tabs">
			{{$ tablist }}
				{{# tabs }}
					{{> core/tab_header_item }}		
				{{/ tabs }}
			{{/ tablist }}
		</ul>
	{{/ tabheader }}
	{{$ tabbody }}
		<div class="tab-content">
			{{$ tabcontent }}
				{{# tabs }}
					{{> core/tab_content_item }}
				{{/ tabs }}
			{{/ tabcontent }}
		</div>
	{{/ tabbody }}
</div>
{{#js}}
    require(['jquery','core/tabs'], function($, tabs) {

        var container = $("#{{ uniqid }}-tab-container");
        tabs.create(container);
    });
{{/js}}

tab_header_item.mustache

<li role="tab"
		data-selected-class="active"
		aria-selected="false" tabindex="-1">

	<a href="#">{{$ tabname }}{{{ name }}}{{/ tabname }}</a>
</li>

tab_content_item.mustache

<div role="tabpanel"
	class="tab-pane"

	{{$ tabpanelcontent }}{{{ content }}}{{/ tabpanelcontent }}
</div>

A summary of the changes:

  • Split the template into 3, moving the tab into it's own template and the content into it's own and then including them in the tabs template.
  • Removed the ids from the tabs and content. The javascript would be updating to assign these ids at runtime so that they don't need to be provided as part of the template context.
  • Added a $tabname block for in the tab_header_item template to make the name flexible on import.
  • Added a $tabpanelcontant block in the tab_content_item template to make the content flexible on import.

Cool, so let's see what that looks like in our example now:

<html>
    <header><title>User Profile</title></header>
    <body>
        {{> core/tabs }}
			{{$ tablist }}
				{{< core/tab_header_item }}
					{{$ tabname }}Name{{/ tabname }}
				{{/ core/tab_header_item }}
				{{< core/tab_header_item }}
					{{$ tabname }}Email{{/ tabname }}
				{{/ core/tab_header_item }}
			{{/ tablist }}
			{{$ tabcontent }}
				{{< core/tab_content_item }}
					{{$ tabpanelcontent }}Your name is {{ name }}.{{/ tabpanelcontent }}
				{{/ core/tab_content_item }}
				{{< core/tab_content_item }}
					{{$ tabpanelcontent }}Your email address is {{ email }}.{{/ tabpanelcontent }}
				{{/ core/tab_content_item }}
			{{/ tabcontent }}
		{{/ core/tabs }}
    </body>
</html>

And we're done! After making the changes above we've been able to keep the benefits of the previous change to allow the context changes but we've also removed the need to copy & paste the HTML everywhere. Instead we're able to use the child templates with a few additional blocks defined to get the content in there.

Now if we want to change tabs HTML or CSS frameworks we can just change the core tabs templates and this page will receive the updates for free.