MoodleDocs - User contributions [en]

JS Framework Specification

2016-12-21T08:43:21Z

Cosmicjustin: /* JQuery (Recommended) */ Grammar edits to match style of list in previous section (No Frameworks)

{{Infobox Project
|name = JS Framework Specification
|state = Implemented
|tracker = MDL-49045
|discussion = https://moodle.org/mod/forum/discuss.php?d=268190
|assignee = [[User:Damyon Wiese|Damyon Wiese]]
}}

== Background ==
Moodle has used YUI as it's javascript framework ([https://moodle.org/mod/forum/discuss.php?d=48478 since 2006]). We have built in support for using their combo loaders, javascript build chain, module support, debugging and many other nice features. We use YUI to provide a standard API between different browser features and for the many nice things that are built in like dialogs, ajax requests, events, classes and inheritance.

Earlier this year (2014) Yahoo announced:

''we have made the difficult decision to immediately stop all new development on YUI in order to focus our efforts on this new technology landscape. This means that, going forward, new YUI releases will likely be few and far between, and will only contain targeted fixes that are absolutely critical to Yahoo properties.''

This started a (very constructive) forum discussion on the future of JS in Moodle (https://moodle.org/mod/forum/discuss.php?d=268190).

And following that discussion we made a policy decision (https://tracker.moodle.org/browse/MDL-47036) to create a "first prototype/example as described by Dan above with JQuery, RequireJS and grunt".

This document is meant to clearly document the features / characteristics of this prototype/example and compare it to our existing YUI integration. It should discuss how the 2 solutions can co-exist during a transition period.

== Summary of forum discussion ==
The forum discussion has had many contributors and is full of valuable comments. Please read it: https://moodle.org/mod/forum/discuss.php?d=268190.

Here is a much shorter summary of most of the things that were discussed:

=== Summary of options for JS library ===
==== No framework ====
Pros:
* Less overhead on each page (maybe)
* Won't find ourselves in the same position in future.

Cons:
* We need to re-implement the cross browser support (drag and drop, ajax ...),
* We are supposed to be building an LMS and tools for teachers, not JS libraries

==== JQuery (Recommended) ====
Pros:
* Most popular choice
* Lots of developers with experience
* Lots of other libraries rely on jquery
* Well supported, long life time, "60.4% of web sites use jQuery"
* Fast
* Many corporate supporters
* Clearly the most voted for option in the discussion
* Backing from deque (accessibility)
* Not too different to YUI
* [https://github.com/search?q=%24PAGE-%3Erequires-%3Ejquery&ref=searchresults&type=Code already used by add-ons ]
* Already bundled with moodle

Cons:
* Is it too much?
* Quality of plugins

Note: This does not include JQuery UI. We may include that eventually, but probably not AS-IS. Moodle has very strict requirements for accessibility that go beyond what JQuery UI provides. It is possible to use JQuery UI in an accessible way, but this would need a moodle wrapper to make sure we do it consistently (e.g. http://www.deque.com/blog/accessible-jquery-ui-datepicker/ ). Also we want to get to a point where the JS UI look consistent to the php generated UI elements. This could be by making themers use http://api.jqueryui.com/theming/css-framework/ to mirror their styles, or by modifying the widgets to pull their HTML from templates, or by building new widgets from the ground up that do what we want.

==== Use a set of polyfills and use ES6 syntax for everything ====
pros:
* nice "elegant" solution

cons:
* testing requirements go up greatly,
* we will probably end up rolling our own JS frame work piece by piece,
* plugins devs would all include jquery anyway (bootstrap).

==== Angular ====
pros:
* trendy,
* clean MVC design

cons:
* requires backend rewrite

==== Ember ====
cons:
* requires backend rewrite

=== Attributes we want in a JS framework ===
long term support cycles, standardize things that are not standard across browsers (dom manipulation, positioning, ajax, events, drag and drop?, 2d drawing?, transitions, accessible widgets?), sandboxing, dependency loading, able to (easily) load third party modules, performance

Note: Just because we have it now in YUI does not mean we need to have it from day 1 of the new framework - YUI will exist for a while and we choose the best extra library available for non-standard things (like 2d drawing, accessible widgets).

=== Summary of options for Accessible Javascript Widgets ===
==== Roll our own ====
* Yuk!
* Aria recommends against this: http://www.w3.org/TR/2009/WD-wai-aria-practices-20090224/#reuse_comp_lib

==== AccDC http://whatsock.com/ ====
Awesome project by one developer with a deep understanding of accessibility to create a widget library that implements accessible widgets first and expects you to make them look pretty later.

Pros: Accessibility definitely comes first with this library
Cons: Hurt by lack of maturity - no unit tests, no information on who is using this library, lacking some developer focused docs, lacking a real community

==== WET http://wet-boew.github.io/ ====
More of a complete framework than a single accessible widget library - and as such it is hard to recommend this. There would be no way to provide backwards compatibility and we would be locked into the selected combination of libraries etc.

==== Assets http://assets.cms.gov ====
More of a complete framework than a single accessible widget library - and as such it is hard to recommend this. There would be no way to provide backwards compatibility and we would be locked into the selected combination of libraries etc. Also docs note various known and un-fixed accessibility problems with various widgets.

==== JQTest ====
Name does not inspire confidence. It's a set of enhancements to JQuery UI to make those components accessibles. Seems to be abandonware.

==== JQuery UI (Recommended) ====
Pros: Huge community, stable releases, good UI for sighted users
Cons: Accessibility reviews have been done on older versions and found numerous bugs. I couldn't find an up-to date review - but from reviewing the demos on their site there are accessibility issues remaining (e.g. some controls are not keyboard accessible). We would have to wrap the JQuery UI components in order to ensure they are used in a way that guarantees accessibility.

=== Summary of options for loading modules ===

==== YUI loader ====
implements modules, sandboxing namespaces, dependency resolution, combo loading, build tools (minification, linting), classes, inheritance, small set of supported widgets, events

pros: we already include the library

cons: does not look to external devs like we have shifted from yui, requires YUI syntax to load modules (e.g. after the page has loaded)

note: it has ways to load ES6 modules (after transpiling them http://yuilibrary.com/yui/docs/yui/es6-modules.html)

==== RequireJS (Recommended) ====
implements: modules (AMD), dependency resolution, build tools (minification, linting) (requires node.js)

pros: Huge user base, most libraries available now ship as AMD compatible modules. Lightweight, simple support for JQuery, means we are doing things like the rest of the world.

cons: We may want to switch to ES6 in a few years

==== ECMAScript 6 modules ====
implements: modules, sandboxing, dependency resolution

pros: best forward looking option (standards based)

cons: new standard - no browser support yet - but there is a polyfill (https://github.com/google/traceur-compiler). After testing, the polyfill is slow and not 100% compatible with the draft spec. No existing libraries use this format - most of them use a pattern that allows them to co-exist as AMD, CommonJS or standalone libraries (Mustache, JQuery UI etc).

=== Summary of options for build tools ===
What is a build tool - think minification, linting, module packaging, generate documentation.

==== Shifter ====
pros: We use it now

cons: doesn't support ES6 modules except to convert them to YUI modules

==== Use a PHP library (not minify - maybe jshrink) (Recommended) ====
pros: Php library - we can automate the minification and tie it to purge caches, don't have to check JS has been compiled, don't have to include build products in git

cons: minify is old and deprecated need to replace it with something better, linting would need a separate tool (maybe part of code checker or cibot or just run jshint manually)

==== Grunt ====
pros: used by a lot of developers, can do more (unit tests), compile less, could run shifter too - so would be a combined process covering old/new, Forced linting step exposes the developer to a lot of jshint warnings while they are developing. Uglifier 2 is the "standard" js minifier (ie we are using the best tools).

cons: another build tool for new developers to support (barriers), Requires a set of files in the moodle root (Gruntfile.js, package.json) - and each moodle instance will need to install node packages with npm into a node_modules folder in their moodle root.

=== Prototypes ===
Based on the above summaries (and the lengthy discussion) - there are some worthwhile candidates we should test out:

==== RequireJS integration ====
With JQuery - http://requirejs.org/docs/jquery.html

Git branch: https://github.com/damyon/moodle/tree/MUSTACHE

This branch uses vanilla RequireJS with no build step. Modules are minified with our current JS minification library on the fly for production only and all modules are concatenated to a single JS file (one request). When modules are concatenated the module name is injected by the server (this is what r.js would do).

The module format is AMD and config for JQuery is built in.

Example of loading (sandboxed) jquery and calling it in a module.js file:

<code javascript>
require(['jquery'], function( $ ) {
$('h1').hide('slow');
});
</code>

Example of creating a module in a plugin:

Create file mod/assign/amd/test.js:
<code javascript>
// This module depends on jquery
define(['jquery'], function($) {
return {
// This module has one get function which returns the text from the heading node in the page.
get: function() {
return $('h1').text();
}
}
});
</code>

How to use the above module:
<code javascript>
require(['mod_assign/test'], function(test) {
console.log(test.get());
});
</code>
The jquery dependency was automatically pulled in - and the component name mapped to the modules area for the component.

==== ES6 Modules (with polyfill) ====
With JQuery loaded as ES6 module (maybe transpiled)

Need to test loading speed - concurrency etc

After testing this - it seems a bit of a dodgy solution because of the way the polyfill works. It either requires "transpiles" (a build step) the ES6 module to ES5, or requires the entire traceur library to do the transpiliing in the browser (slow).

Since traceur can transpile ES6 to AMD modules, maybe we should test an automated version of this so we write in ES6, but transpile to AMD and load with RequireJS. This gives us a future proof format that works now with a stable loader. Also - try 6in5.

Note - in researching this - I did not find any current libraries using the ES6 format with a transpile step in their build. This would introduce a difference between our JS and the JS we find in the real world, which is not a good thing. I'm not recommending this approach until it becomes more widespread.

==== Grunt ====
Dave has been working on grunt support and has a branch where you can run grunt in any directory, and it will either run shifter with the correct options, or manually run the required uglifier steps the minify AMD javascript.

There is a demo of GruntJS's capabilities which can be found here: https://github.com/gurgus/gruntdemo

This shows off the capability of a developer only having to run one command (`grunt`) from within a YUI or AMD directory and have the necessary build steps applied to their code.

==== Automated minification ====
We have a prototype of this approach here:
https://github.com/damyon/moodle/tree/MUSTACHE

(It also has mustache support because I have been working on both).

How this branch works:

When you request a module from requirejs like this:
<code javascript>
require(['core/alert'], function(Alert) {
var a = new Alert('I have a message', 'to say');
});
</code>

The requirejs config tells requirejs that the "lib/requirejs.php" script is the base of all urls.

The "lib/requirejs.php" script will return the requested module, correctly minified and with the correct module name inserted - but also all other AMD modules from all plugins and subsystem dirs in Moodle. This is similar to what the "r.js" optimiser tool does, but we
need it to be done at request time because you can add/remove plugins from Moodle.

Question: So - you get one mega minified JS file with all known modules as your response - won't that be huge?
Answer: No - not too huge - and the performance benefit of reducing JS requests is worth it. And it will be cached. The sum of all of our minified JS in all of our custom written yui modules is 800k. YUI itself is 2.8MB which is why it doesn't survive without a combo loader. Some google engineers in this presentation: https://www.youtube.com/watch?v=mGENRKrdoGY suggest that the point you want to start splitting your JS up is aroung 1MB - we have a lot of JS to write in the new format before we get to that point. Finally - our current JS uses handlebar templates defined in the Javascript - we have a new way of loading templates via AJAX so our new code will be a bit smaller.

Pros: No build steps

Cons: No lint step (could be done in codechecker, or by manually running jshint).

JS Framework Specification

2016-12-21T08:41:57Z

Cosmicjustin: /* No framework */ Grammar and spelling corrections

{{Infobox Project
|name = JS Framework Specification
|state = Implemented
|tracker = MDL-49045
|discussion = https://moodle.org/mod/forum/discuss.php?d=268190
|assignee = [[User:Damyon Wiese|Damyon Wiese]]
}}

== Background ==
Moodle has used YUI as it's javascript framework ([https://moodle.org/mod/forum/discuss.php?d=48478 since 2006]). We have built in support for using their combo loaders, javascript build chain, module support, debugging and many other nice features. We use YUI to provide a standard API between different browser features and for the many nice things that are built in like dialogs, ajax requests, events, classes and inheritance.

Earlier this year (2014) Yahoo announced:

''we have made the difficult decision to immediately stop all new development on YUI in order to focus our efforts on this new technology landscape. This means that, going forward, new YUI releases will likely be few and far between, and will only contain targeted fixes that are absolutely critical to Yahoo properties.''

This started a (very constructive) forum discussion on the future of JS in Moodle (https://moodle.org/mod/forum/discuss.php?d=268190).

And following that discussion we made a policy decision (https://tracker.moodle.org/browse/MDL-47036) to create a "first prototype/example as described by Dan above with JQuery, RequireJS and grunt".

This document is meant to clearly document the features / characteristics of this prototype/example and compare it to our existing YUI integration. It should discuss how the 2 solutions can co-exist during a transition period.

== Summary of forum discussion ==
The forum discussion has had many contributors and is full of valuable comments. Please read it: https://moodle.org/mod/forum/discuss.php?d=268190.

Here is a much shorter summary of most of the things that were discussed:

=== Summary of options for JS library ===
==== No framework ====
Pros:
* Less overhead on each page (maybe)
* Won't find ourselves in the same position in future.

Cons:
* We need to re-implement the cross browser support (drag and drop, ajax ...),
* We are supposed to be building an LMS and tools for teachers, not JS libraries

==== JQuery (Recommended) ====
pros:
* Most popular choice,
* lots of developers with experience,
* lots of other libraries rely on jquery,
* well supported, long life time, "60.4% of web sites use jQuery",
* fast,
* many corporate supporters,
* clearly the most voted for option in the discussion,
* backing from deque (accessibility),
* not too different to YUI
* [https://github.com/search?q=%24PAGE-%3Erequires-%3Ejquery&ref=searchresults&type=Code already used by add-ons ]
* already bundled with moodle

cons:
* Is it too much?,
* quality of plugins,

Note: This does not include JQuery UI. We may include that eventually, but probably not AS-IS. Moodle has very strict requirements for accessibility that go beyond what JQuery UI provides. It is possible to use JQuery UI in an accessible way, but this would need a moodle wrapper to make sure we do it consistently (e.g. http://www.deque.com/blog/accessible-jquery-ui-datepicker/ ). Also we want to get to a point where the JS UI look consistent to the php generated UI elements. This could be by making themers use http://api.jqueryui.com/theming/css-framework/ to mirror their styles, or by modifying the widgets to pull their HTML from templates, or by building new widgets from the ground up that do what we want.

==== Use a set of polyfills and use ES6 syntax for everything ====
pros:
* nice "elegant" solution

cons:
* testing requirements go up greatly,
* we will probably end up rolling our own JS frame work piece by piece,
* plugins devs would all include jquery anyway (bootstrap).

==== Angular ====
pros:
* trendy,
* clean MVC design

cons:
* requires backend rewrite

==== Ember ====
cons:
* requires backend rewrite

=== Attributes we want in a JS framework ===
long term support cycles, standardize things that are not standard across browsers (dom manipulation, positioning, ajax, events, drag and drop?, 2d drawing?, transitions, accessible widgets?), sandboxing, dependency loading, able to (easily) load third party modules, performance

Note: Just because we have it now in YUI does not mean we need to have it from day 1 of the new framework - YUI will exist for a while and we choose the best extra library available for non-standard things (like 2d drawing, accessible widgets).

=== Summary of options for Accessible Javascript Widgets ===
==== Roll our own ====
* Yuk!
* Aria recommends against this: http://www.w3.org/TR/2009/WD-wai-aria-practices-20090224/#reuse_comp_lib

==== AccDC http://whatsock.com/ ====
Awesome project by one developer with a deep understanding of accessibility to create a widget library that implements accessible widgets first and expects you to make them look pretty later.

Pros: Accessibility definitely comes first with this library
Cons: Hurt by lack of maturity - no unit tests, no information on who is using this library, lacking some developer focused docs, lacking a real community

==== WET http://wet-boew.github.io/ ====
More of a complete framework than a single accessible widget library - and as such it is hard to recommend this. There would be no way to provide backwards compatibility and we would be locked into the selected combination of libraries etc.

==== Assets http://assets.cms.gov ====
More of a complete framework than a single accessible widget library - and as such it is hard to recommend this. There would be no way to provide backwards compatibility and we would be locked into the selected combination of libraries etc. Also docs note various known and un-fixed accessibility problems with various widgets.

==== JQTest ====
Name does not inspire confidence. It's a set of enhancements to JQuery UI to make those components accessibles. Seems to be abandonware.

==== JQuery UI (Recommended) ====
Pros: Huge community, stable releases, good UI for sighted users
Cons: Accessibility reviews have been done on older versions and found numerous bugs. I couldn't find an up-to date review - but from reviewing the demos on their site there are accessibility issues remaining (e.g. some controls are not keyboard accessible). We would have to wrap the JQuery UI components in order to ensure they are used in a way that guarantees accessibility.

=== Summary of options for loading modules ===

==== YUI loader ====
implements modules, sandboxing namespaces, dependency resolution, combo loading, build tools (minification, linting), classes, inheritance, small set of supported widgets, events

pros: we already include the library

cons: does not look to external devs like we have shifted from yui, requires YUI syntax to load modules (e.g. after the page has loaded)

note: it has ways to load ES6 modules (after transpiling them http://yuilibrary.com/yui/docs/yui/es6-modules.html)

==== RequireJS (Recommended) ====
implements: modules (AMD), dependency resolution, build tools (minification, linting) (requires node.js)

pros: Huge user base, most libraries available now ship as AMD compatible modules. Lightweight, simple support for JQuery, means we are doing things like the rest of the world.

cons: We may want to switch to ES6 in a few years

==== ECMAScript 6 modules ====
implements: modules, sandboxing, dependency resolution

pros: best forward looking option (standards based)

cons: new standard - no browser support yet - but there is a polyfill (https://github.com/google/traceur-compiler). After testing, the polyfill is slow and not 100% compatible with the draft spec. No existing libraries use this format - most of them use a pattern that allows them to co-exist as AMD, CommonJS or standalone libraries (Mustache, JQuery UI etc).

=== Summary of options for build tools ===
What is a build tool - think minification, linting, module packaging, generate documentation.

==== Shifter ====
pros: We use it now

cons: doesn't support ES6 modules except to convert them to YUI modules

==== Use a PHP library (not minify - maybe jshrink) (Recommended) ====
pros: Php library - we can automate the minification and tie it to purge caches, don't have to check JS has been compiled, don't have to include build products in git

cons: minify is old and deprecated need to replace it with something better, linting would need a separate tool (maybe part of code checker or cibot or just run jshint manually)

==== Grunt ====
pros: used by a lot of developers, can do more (unit tests), compile less, could run shifter too - so would be a combined process covering old/new, Forced linting step exposes the developer to a lot of jshint warnings while they are developing. Uglifier 2 is the "standard" js minifier (ie we are using the best tools).

cons: another build tool for new developers to support (barriers), Requires a set of files in the moodle root (Gruntfile.js, package.json) - and each moodle instance will need to install node packages with npm into a node_modules folder in their moodle root.

=== Prototypes ===
Based on the above summaries (and the lengthy discussion) - there are some worthwhile candidates we should test out:

==== RequireJS integration ====
With JQuery - http://requirejs.org/docs/jquery.html

Git branch: https://github.com/damyon/moodle/tree/MUSTACHE

This branch uses vanilla RequireJS with no build step. Modules are minified with our current JS minification library on the fly for production only and all modules are concatenated to a single JS file (one request). When modules are concatenated the module name is injected by the server (this is what r.js would do).

The module format is AMD and config for JQuery is built in.

Example of loading (sandboxed) jquery and calling it in a module.js file:

<code javascript>
require(['jquery'], function( $ ) {
$('h1').hide('slow');
});
</code>

Example of creating a module in a plugin:

Create file mod/assign/amd/test.js:
<code javascript>
// This module depends on jquery
define(['jquery'], function($) {
return {
// This module has one get function which returns the text from the heading node in the page.
get: function() {
return $('h1').text();
}
}
});
</code>

How to use the above module:
<code javascript>
require(['mod_assign/test'], function(test) {
console.log(test.get());
});
</code>
The jquery dependency was automatically pulled in - and the component name mapped to the modules area for the component.

==== ES6 Modules (with polyfill) ====
With JQuery loaded as ES6 module (maybe transpiled)

Need to test loading speed - concurrency etc

After testing this - it seems a bit of a dodgy solution because of the way the polyfill works. It either requires "transpiles" (a build step) the ES6 module to ES5, or requires the entire traceur library to do the transpiliing in the browser (slow).

Since traceur can transpile ES6 to AMD modules, maybe we should test an automated version of this so we write in ES6, but transpile to AMD and load with RequireJS. This gives us a future proof format that works now with a stable loader. Also - try 6in5.

Note - in researching this - I did not find any current libraries using the ES6 format with a transpile step in their build. This would introduce a difference between our JS and the JS we find in the real world, which is not a good thing. I'm not recommending this approach until it becomes more widespread.

==== Grunt ====
Dave has been working on grunt support and has a branch where you can run grunt in any directory, and it will either run shifter with the correct options, or manually run the required uglifier steps the minify AMD javascript.

There is a demo of GruntJS's capabilities which can be found here: https://github.com/gurgus/gruntdemo

This shows off the capability of a developer only having to run one command (`grunt`) from within a YUI or AMD directory and have the necessary build steps applied to their code.

==== Automated minification ====
We have a prototype of this approach here:
https://github.com/damyon/moodle/tree/MUSTACHE

(It also has mustache support because I have been working on both).

How this branch works:

When you request a module from requirejs like this:
<code javascript>
require(['core/alert'], function(Alert) {
var a = new Alert('I have a message', 'to say');
});
</code>

The requirejs config tells requirejs that the "lib/requirejs.php" script is the base of all urls.

The "lib/requirejs.php" script will return the requested module, correctly minified and with the correct module name inserted - but also all other AMD modules from all plugins and subsystem dirs in Moodle. This is similar to what the "r.js" optimiser tool does, but we
need it to be done at request time because you can add/remove plugins from Moodle.

Question: So - you get one mega minified JS file with all known modules as your response - won't that be huge?
Answer: No - not too huge - and the performance benefit of reducing JS requests is worth it. And it will be cached. The sum of all of our minified JS in all of our custom written yui modules is 800k. YUI itself is 2.8MB which is why it doesn't survive without a combo loader. Some google engineers in this presentation: https://www.youtube.com/watch?v=mGENRKrdoGY suggest that the point you want to start splitting your JS up is aroung 1MB - we have a lot of JS to write in the new format before we get to that point. Finally - our current JS uses handlebar templates defined in the Javascript - we have a new way of loading templates via AJAX so our new code will be a bit smaller.

Pros: No build steps

Cons: No lint step (could be done in codechecker, or by manually running jshint).

Templates

2016-12-20T09:04:00Z

Cosmicjustin: Fix a typo

{{Moodle 2.9}}

= Templates =

== What is a template? ==
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? ==
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.
* <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).
* <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).
* <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.
* <code xml>{{^lemmings}} enjoy view {{/lemmings}}</code> Equivalent of "if-not" block, there is no "else" in mustache.
* <code xml>{{> pacman }}</code> This is a partial. Think of it like an include. Templates can include other templates using this tag.
* <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.

So - putting this all together:

recipe.mustache
<code xml>
<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",
description: "Who doesn't like a good cheese sandwich?",
ingredients: ["bread", "cheese", "butter"],
steps: ["<p>Step 1 is to spread the butter on the bread</p>", "<p>Step 2 is to put the cheese "in" the bread (not on top, or underneath)</p>"]
}
</code>

Gives this: <span style="font-size:4em">😋</span>

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 :) .

=== Blocks (Moodle 3.0 onwards) ===
Blocks are a feature of Mustache that deserves a special mention. The are used as a form of inheritance - and are crucial to building a library of re-usable templates. To use 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 $):

<code xml>
<section>
<h1>{{$sectionheading}}Default heading{{/sectionheading}}</h1>
<div>
{{$content}}Content for section{{/content}}
</div>
</section>
</code>

Now - wherever I need to re-use this template I can include it and replace the content of those sections at the same time.

<code xml>
{{< section}}
{{$sectionheading}}Latest News{{/sectionheading}}
{{$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:
<code xml>
{{< section}}
</code>
Not
<code xml>
{{> 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.

Note: Do not try and put your templates in sub folders under the "/templates" directory. This is not supported and will not work.

== 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.
var promise = templates.render('block_looneytunes/profile', context);

// The promise object returned by this function means "I've considered your request and will finish it later - I PROMISE!"

// How we deal with promise objects is by adding callbacks.
promise.done(function(source, javascript) {
// Here eventually I have my compiled template, and any javascript that it generated.

// I can execute the javascript (probably after adding the HTML to the DOM) like this:
templates.runTemplateJS(javascript);
});

// Sometimes things fail
promise.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)
.done(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
profile.mustache
<code xml>
<div id="profile">
<p>Name: {{name}}</p>
<p>Intelligence: {{intelligence}}</p>
</div>
{{#js}}
require('jquery', function($) {
// Effects! Can we have "blink"?
$('#profile').slideDown();
});
{{/js}}
</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? ==

=== {{# 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 <code>get_string('helloworld', 'mod_greeting')</code>.

The optional third parameter defines the value for the string's <code>$a</code> placeholder:

<code xml>
{{# str }} iscool, mod_cool, David Beckham {{/ str }}
</code>

This example would effectively do what <code>get_string('iscool', 'mod_cool', 'David Beckham')</code> does in Moodle PHP code.

Variable tags are allowed to define the value of the <code>$a</code> 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 <code>{{# str }}</code> helper may need complex data structures passed as the value of the <code>$a</code> 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 !}}
{{# str }} iscool, mod_cool, { "firstname": "{{ firstname }}", "lastname": "{{ lastname }}" } {{/ str }}
</code>

There is a potential problem though. If the variable tag <code>{{ firstname }}</code> or <code>{{ lastname }}</code> 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 <code>{{# quote }}</code> helper:

<code xml>
{{! This is OK !}}
{{# 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.

== How do I call a template from php? ==

The templates in php are attached to the renderers. There is a renderer method "render_from_template($templatename, $context)" that does the trick.

== How do templates work with renderers? ==

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:
* 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?

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).

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.

In the renderable:
<code php>
/**
* Export this data so it can be used as the context for a mustache template.
*
* @return stdClass
*/
public function export_for_template(renderer_base $output) {
$data = new stdClass();
$data->canmanage = $this->canmanage;
$data->things = array();
foreach ($this->things as $thing) {
$data->things[] = $thing->to_record();
}
$data->navigation = array();
foreach ($this->navigation as $button) {
$data->navigation[] = $output->render($button);
}

return $data;
}
</code>

In the renderer class:
<code php>
/**
* Defer to template.
*
* @param mywidget $widget
*
* @return string HTML for the page
*/
render(mywidget $widget) {
$data = $widget->export_for_template($this);
return $this->render_from_template('mywidget', $data);
}
</code>

== How to I override a template in my theme? ==

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.

== Should I document my templates? ==

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.

=== Add a documentation comment to your template ===
Mustache comments look like this:
<pre>
{{!
I am a comment.
I can span multiple lines.
}}
</pre>

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.

<code>
@template component/templatename
</code>

==== Useful things to include in the documentation for a template ====
===== 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.

==== A full example ====
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.

=== 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.

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

===Follow CSS coding style===

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.

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

[[Category:AJAX]]
[[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
<code php>
$datafortemplate->mylist = array_values($myarraywithnonnumerickeys)
</code>
you could also use
<code php>
$datafortemplate->mylist = new ArrayIterator($myarraywithnonnumerickeys);
</code>
BUT this fails when $myarraywithnonnumerickeys is empty and you try to use
<code html5>
{{#mylist}}
with an array iterator if mylist is empty this block will not run
{{/mylist}}
{{^mylist}}
with an array iterator mylist will not run this block either because it is not quite empty
{{/mylist}}
</code>

== How do I write 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.

=== 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.

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>
<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}}
</pre>

The template requires a context that looks something like:
<pre>
{
"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>"}
]
}
</pre>

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:
<pre>
<html>
<header><title>User Profile</title></header>
<body>
{{< core/tabs }}
</body>
</html>
</pre>

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>
{
"tabs": [
{"id":"tab1","name":"Name","content":"Your name is Mr. Test User."},
{"id":"tab2","name":"Email","content":"Your email is testuser@example.com"},
]
}
</pre>

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:
<pre>
{
"name":"Mr. Test User",
"email":"testuser@example.com"
}
</pre>

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 leverging blocks:
<pre>
<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}}
</pre>

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:
<pre>
<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>
</pre>

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:
<pre>
<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}}
</pre>

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

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

tab_content_item.mustache
<pre>
<div role="tabpanel"
class="tab-pane"

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

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:
<pre>
<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>
</pre>

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.

Using images in a theme

2016-12-13T10:46:02Z

Cosmicjustin: Syntax error in an example

{{Template:Themes}}
==A little background==
Moodle a standard way of making use of images within its pages enabling theme designers to take full control over what images are being used and when possible ensures images are passed through Moodle's performance caching system to obtain the best possible performance.

==Before we start==

# Make sure you have a theme and images to work with, one that you have a backup of just in case.
# Take note of your theme's main layout file e.g. ''standard.php''.
# Take note of your theme's main CSS file e.g. ''core.css''.
# Turn on '''Theme designer mode'''.

==Image locations within Moodle==

There are three main areas in which images are located - core, plugin and theme.

Core images are used throughout Moodle and are stored in ''moodle/pix''.

The pix directory contains the following subdirectories:

:''a'' - Icons that are not widely used
:''c'' - Calendar-related icons
:"e" - Editor-related icons
:''f'' - File icons for different file types
:''g'' - Default user icons and thumbnails
:''i'' - General icons
:''m'' - Currency symbols
:''s'' - Smileys
:''t'' - General icons
:''u'' - User icons and thumbnails
:''y'' - YUI icons

Plugin images are used by plugins and are stored within the plugin's directory e.g. ''mod/forum/*'' or ''blocks/navigation/*''

Theme images are used in themes and are stored in the ''pix'' subdirectory of a theme.

==Adding new images to your theme==

To add new images to your theme, such as a background image or a logo, you should start by creating a pix directory within your themes directory.

Lets assume you have two images, gradient.png and logo.jpg. Copy both files to your themes pix directory.

The plan is to use gradient.png as the background image for your theme (in CSS) and use logo.jpg in the header (in your theme's layout file).

===Using images within CSS===

Moodle parses all CSS files. When theme designer mode is off, Moodle combines them into a handful of large CSS files that get cached and served. At the same time Moodle also looks at the CSS and replaces special syntax rules.

<div style='padding:10px;background-color:#f7f7f7;border:1px dashed #123456'><nowiki>[[pix:theme|</nowiki><span style='color:#336699;font-weight:bold;'><nowiki>path/to/image/</nowiki></span><span style='color:#33993A;font-weight:bold;'>imagename</span><nowiki>]]</nowiki></div>

The above pattern is looked for by Moodle and gets replaced with the correct image URL when found.
You should note the following things about this pattern when using your own images within CSS:

# The bits in black don't change
# The bit in blue is the path to your image within the pix directory. It shouldn't start with a / but should end with one.
# The bit in green is the filename ('''no need to include the file extension''')

To use gradient.png as the background for our pages, add the following line of CSS to the themes core.css.
<code css>
body {background-image:url([[pix:theme|gradient]]);}
</code>

Before we look at how to use your own images within your themes layout files we should first look at how this changes if the image is in a sub directory.

Lets assume gradient.png is located here: '''pix/myimages/gradients/gradient.png'''

The CSS would need to be as follows:
<code css>
body {background-image:url([[pix:theme|myimages/gradients/gradient]]);}
</code>

If you want to refer to an image belonging to a plugin, you can do it like this:

<code css>
body {background-image:url([[pix:quiz|icon]]);}
body {background-image:url([[pix:qtype_ddmarker|grid]]);}
</code>

That refers to mod/quiz/pix/icon.png/gif and question/type/ddmarker/pix/grid.png/gif respectively (or whatever icons you have put in your theme to override these).

===Using your images within your layout files===

To use logo.jpg within the a layout php file or layout mustache template you need to add the url for the image to the template context and then include an image tag in the template using the source from the context.

Images:
<code>
/pix/logo.jpg
/pix/myimages/logos/logo.png
</code>

''theme/yourtheme/layout/somelayout.php''
<code php>
...
$templatecontext = [
...
$imageone => $OUTPUT->pix_url('logo', 'theme'),
$imagetwo => $OUTPUT->pix_url('myimages/logos/logo', 'theme'),
...
];

echo $OUTPUT->render_from_template('theme_yourtheme/somelayout', $templatecontext);
</code>

''theme/yourtheme/templates/somelayout.mustache''
<code handlebars>
...
<img src="{{{imageone}}}" alt="Please give your image alt text or set the role to presentation" width="50" height="50">
<img src="{{{imagetwo}}}" alt="Please give your image alt text or set the role to presentation" width="50" height="50">
...
</code>

==Overriding images in your theme==

Overriding images within your theme can be an important part of creating and/or modifying themes.

As mentioned, there are three main areas for images within Moodle, core, plugins, and themes. Obviously we won't be overriding theme images as we are in a theme and have full control over that already which just leaves core and plugin images that you may want to override.

Within your theme create the following two directories:
; /pix_core/ : This is where your images to override core images will need to be.
; /pix_plugins/ : This is where images to override plugins will need to be.

Next, copy the images that you wish to override into either the pix_core or pix_plugins directory. You need to replicate the directory structure that the images are located in.

The following two examples illustrate how this works for both core and plugin images.

===Overriding core images===
For this example I am going to override the following two images:
# '''moodle/pix/help.gif''' This image is used for all help image icons and is shown throughout Moodle.
# '''moodle/pix/i/info.gif''' This image is used in several places, most notably the front page if the combo list is being displayed.

So first up help.gif. This is the most basic example of overriding an image. Because the image is directly within Moodle's pix directory we can simply place our new help image into our themes pix_core directory. There's nothing more to it!

The second example if not really any more difficult. Because the image is located within the subdirectory '''i''' we must create a sub directory within our pix_core directory into which we will copy our new help image. That is, the image ends up at '''/pix_core/i/info.png''' inside your theme folder. And again done!

You should also note that, as with any other image in Moodle, the extension doesn't matter. If you want to replace help.gif with a help.png you can just put the png into the correct directory. As long as the filename is the same Moodle will find it.

===Overriding plugin images===
This is a little bit more difficult than overriding core images, but not too much so. For this example, let's say I want to override the following two plugin images:
# '''moodle/mod/forum/icon.gif''' This is the icon that is used everywhere for the forum.
# '''moodle/blocks/customblock/activate.png''' This is an icon in a custom block I have installed.

Just as with core images, we need to put the image in the correct directory structure. In this case it is going to be within our theme's '''pix_plugins''' directory.
The correct path must use the plugin type [[Frankenstyle]] prefix and the plugin name.

For the examples above the paths to override the plugin images will be:
# '''pix_plugins/mod/forum/'''
# '''pix_plugins/block/customblock/'''

When looking for an overriding image the following path is used.

# theme (static)
# themename => mytheme
# area => pix_plugins for plugin images, pix_core for core images, pix for theme images.
# plugin type => booktool for the book tool sub plugin for example.
# plugin name => print for the name of the sub plugin.
# file name => book for the name of the image.

It then searches for the image with the following extensions gif, png, jpg, jpeg in that order.

So you end up with:
<code>
/theme/themename/area/plugintype/pluginname/filename.gif
</code>

==See also==

* [[Plugins]]
* [[Replacing icons with CSS3]]
* [http://youtu.be/g_9VM9OMs3Y Adding Images to your Theme] MoodleBites video on YouTube

Using Moodle forum discussions:
* [http://moodle.org/mod/forum/discuss.php?d=151581 Using images within your themes (and the silk icon theme)]
* [http://moodle.org/mod/forum/discuss.php?d=151581#p689883 choosing images based on the users current language]
* [http://moodle.org/mod/forum/discuss.php?d=157935&parent=691903 how to add a category(categorias) img-bullet]