MoodleDocs - User contributions [en]

Javascript Modules

2019-08-05T06:19:52Z

Ryanwyllie: /* ES6 Modules (Moodle v3.8 and above) */

{{Moodle 2.9}}

= Javascript Modules =

== What is a Javascript module and why do I care? ==

A Javascript module is nothing more than a collection of Javascript code that can be used (reliably) from other pieces of Javascript.

== Why should I package my code as a module? ==

By packaging your code as a module you break your code up into smaller reusable pieces. This is good because:

a) Each smaller piece is simpler to understand / debug

b) Each smaller piece is simpler to test

c) You can re-use common code instead of duplicating it

= How do I write a Javascript module in Moodle? =

Since version 2.9, Moodle supports Javascript modules written using the Asynchronous Module Definition ([https://github.com/amdjs/amdjs-api/wiki/AMD AMD]) API. This is a standard API for creating Javascript modules and you will find many useful third party libraries that are already using this format.

To edit or create an AMD module in Moodle you need to do a couple of things.

Since version 3.8, Moodle supports [https://github.com/lukehoban/es6features#readme ECMAScript 2015 features] (aka ES6) in a cross browser compatible way thanks to [https://babeljs.io/ Babel JS]. In order to achieve the compatibility with older browsers Babel will compile the newer ES6 features back into ES5 Javascript. Unfortunately this means that in order for your Javascript changes to show in the browser they must be compiled by running Grunt, even with the cachejs config setting set to false (i.e. "Development mode").

== Install grunt ==

The AMD modules in Moodle must be processed by some build tools before they will be visible to your web browser. We use "[[grunt]]" as a build tool to wrap our different processes. Grunt is a build tool written in Javascript that runs in the "[http://nodejs.org/ nodejs]" environment.

This means you first have to '''install nodejs''' - and its package manager [https://www.npmjs.com/ npm]. The details of how to install those packages will vary by operating system, but on Linux it's probably similar to "sudo apt-get install nodejs npm". There are downloadable packages for other operating systems here: http://nodejs.org/download/. Moodle currently requires node {{NodeJSVersion}}.

Once this is done, you can '''run the command''':

npm install
npm install -g grunt-cli

from the top of the Moodle directory to install all of the required tools. (You may need extra permissions to use the -g option.)

== Development mode (Moodle v2.9 to v3.7) ==

To avoid having to constantly run grunt, make sure you set the following in your config.php

<code php>
// Prevent JS caching
$CFG->cachejs = false;
</code>

Moodle will now run your module from the amd/src module. Don't forget to switch this off and run 'grunt' before deploying the new version!

In this mode - if you get a strange message in your javascript console like "No define call for core/first" it means you have a syntax error in the javascript you are developing.
Or, "No define call for theme_XXX/loader" as you are probably missing the 'src' folder with relevant JS files. which might happen when you turn debugging ON on a theme that was bought, without 'src' folder :-(

== Development mode (Moodle v3.8 and above) ==

All Javascript code is now compiled using Babel which means Moodle will only ever serve minified Javascript to the browser, even in development mode. However in development mode Moodle will also send the browser the corresponding source map files for each of the Javascript modules. The source map files will tell the browser how to map the minified source code back to the unminified original source code so that the original source files will be displayed in the sources section of the browser's development tools.

While in development mode each of the Javascript modules will appear in the browser's source tree as separate modules (no more giant first.js file!) and they will also be loaded with individual network requests (this is a compromise we had to make thanks to some browser bugs with source map files).

To enable development mode set the '''cachejs''' config value to '''false''' in the admin settings or directly in your config.php file:
<code php>
// Prevent JS caching
$CFG->cachejs = false;
</code>

Since all Javascript must now be compiled you must run Grunt in order for you changes to appear in the browser. However rather than running Grunt manually each time on either the whole project or each file you modified, it is recommended that you just run the '''grunt watch''' task at the root of your Moodle directory. The grunt watch task will listen for changes to the Javascript files in the Moodle directory and will automatically lint and compile only the file that is changed after each change is detected. This removes the need to manually run grunt after each change.

== Running grunt ==

You can run grunt in your plugin's 'amd' directory and it will only operate on your modules. If you're having problems or just want to check your work it is worth running for the 'lint' feature. This can find basic problems. This sub-directory support wont work on Windows unfortunately but there is an alternative: Run grunt from the top directory with the --root=path/to/dir to limit execution to a sub-directory.

See [[Grunt#Running_grunt]] for more details of specific grunt commands which can be used.

If you get the error message

/usr/bin/env: node: No such file or directory

Then see the thread https://github.com/nodejs/node-v0.x-archive/issues/3911

On Ubuntu 14.04 this fixed it for me:

sudo ln -fs /usr/bin/nodejs /usr/local/bin/node

Note: Once you have run grunt and built your code, you will then need to purge Moodle caches otherwise the changes made to your minified files may not be picked up by Moodle.

== ES6 Modules (Moodle v3.8 and above) ==

In addition to AMD module syntax Moodle now supports the [https://github.com/lukehoban/es6features#modules ES6 syntax] for writing Javascript modules. All modules (defined using either syntax) are compatible with one another. Behind the scenes the ES6 module syntax is converted into an AMD syntax as part of the Babel compiling process.

=== Export default ===
There is one slight difference between the ES6 definition for exporting modules and the RequireJS (AMD) definition.

ES6 allows you to export a “default” value which is actually no different to exporting a named value where the name is “default”. Unfortunately, RequireJS allows for unnamed default exports (e.g. you can do "return SomeClass;") which can be imported by just requiring them in other AMD modules.

That’s a bit confusing, get to the point! Well, it basically means that in Moodle you won’t be able to write an ES6 module that exports both a default and named exports, e.g. "export default function() {...}" and "export const FOO = 'bar'" in the same module. The export default will simply override all other exports in that module.

=== Inline Javascript ===
Another important note is that ES6 support is only for stand alone Javascript files because it relies on the compilation from Babel and Grunt. That means any inline Javascript (either in PHP or in Mustache templates) won't support the ES6 features. Instead it would be best to keep the inline Javascript as minimal as possible and only use it to load a stand alone Javascript module.

== Minimum (getting started) module for plugins ==

This shows the absolute minimum module you need to get started adding modules to your plugins. It's actually quite simple...

<code javascript>
// Put this file in path/to/plugin/amd/src
// You can call it anything you like

define(['jquery'], function($) {

return {
init: function() {

// Put whatever you like here. $ is available
// to you as normal.
$(".someclass").change(function() {
alert("It changed!!");
});
}
};
});
</code>

This code passes the jquery module into our function (parameter $). There are a number of other useful modules available in Moodle, some of which you'll probably need in a practical application. See [[Useful_core_Javascript_modules]]. Simply list them in both the define() first parameter and the function callback. E.g.,
<code javascript>
define(['jquery', 'core/str', 'core/ajax'], function($, str, ajax) {
</code>

The idea here is that we will run the 'init' function from our (PHP) code to set things up. This is called from PHP like this...

<code php>
$PAGE->requires->js_call_amd('frankenstyle_path/your_js_filename', 'init');
</code>

Don't forget to supply the complete '[[Frankenstyle]]' path. The .js is not needed.

js_call_amd takes a third parameter which is an ''array'' of parameters. These will translate to individual parameters in the 'init' function call. For example...

<code php>
$PAGE->requires->js_call_amd('block_iomad_company_admin/department_select', 'init', array($first, $last));
</code>

...calls

<code javascript>
return {
init: function(first, last) {
}
</code>

A more comprehensive explanation follows...

== "Hello World" I am a Javascript Module ==
Lets now create a simple Javascript module so we can see how to lay things out.

Each Javascript module is contained in a single source file in the <componentdir>/amd/src folder. The final name of the module is taken from the file name and the component name. E.g. block_overview/amd/src/helloworld.js would be a module named "block_overview/helloworld". the name of the module is important when you want to call it from somewhere else in the code.

After running grunt - the minified Javascript files are stored in the <componentdir>/amd/build folder. The javascript files are renamed to show that they are minified (helloworld.js becomes helloworld.min.js).

Don't forget to add the built files (the ones in amd/build) to your git commits, or in production no-one will see your changes.

Lets create a simple module now:

blocks/overview/amd/src/helloworld.js
<code javascript>
// Standard license block omitted.
/*
* @package block_overview
* @copyright 2015 Someone cool
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

/**
* @module block_overview/helloworld
*/
define(['jquery'], function($) {

/**
* Give me blue.
* @access private
* @return {string}
*/
var makeItBlue = function() {
// We can use our jquery dependency here.
return $('.blue').show();
};

/**
* @constructor
* @alias module:block_overview/helloworld
*/
var greeting = function() {
/** @access private */
var privateThoughts = 'I like the colour blue';

/** @access public */
this.publicThoughts = 'I like the colour orange';

};

/**
* A formal greeting.
* @access public
* @return {string}
*/
greeting.prototype.formal = function() {
return 'How do you do?';
};

/**
* An informal greeting.
* @access public
* @return {string}
*/
greeting.prototype.informal = function() {
return 'Wassup!';
};
return greeting;
});
</code>

The most interesting line above is:
<code>
define(['jquery'], function($) {
</code>

All AMD modules must call "define()" as the first and only global scoped piece of code. This ensures the javascript code contains no global variables and will not conflict with any other loaded module. The name of the module does not need to be specified because it is determined from the filename and component (but it can be listed in a comment for JSDoc as shown here).

The first argument to "define" is the list of dependencies for the module. This argument must be passed as an array, even if there is only one. In this example "jquery" is a dependency. "jquery" is shipped as a core module is available to all AMD modules.

The second argument to "define" is the function that defines the module. This function will receive as arguments, each of the requested dependencies in the same order they were requested. In this example we receive JQuery as an argument and we name the variable "$" (it's a JQuery thing). We can then access JQuery normally through the $ variable which is in scope for any code in our module.

The rest of the code in this example is a standard way to define a Javascript module with public/private variables and methods. There are many ways to do this, this is only one.

It is important that we are returning 'greeting'. If there is no return then your module will be declared as undefined.

== Loading modules dynamically ==
What do you do if you don't know in advance which modules will be required? Stuffing all possible required modules in the define call is one solution, but it's ugly and it only works for code that is in an AMD module (what about inline code in the page?). AMD lets you load a dependency any time you like.
<code javascript>

// Load a new dependency.
require(['mod_wiki/timer'], function(timer) {
// timer is available to do my bidding.
});
</code>

== Including an external javascript/jquery library ==
If you want to include a javascript / jquery library downloaded from the internet you can do so as follows:

'''Warning: if the library you download, supports AMD but is already "named" you will not be able to include it directly'''
e.g.
<code javascript>
define("typeahead.js", *[ "jquery" ], function(a0) {
return factory(a0);
});
</code>
will not work, as moodle injects it's own define name when loading the library.

If the library is in AMD format and has a define:
e.g. i want to include the jquery final countdown timer on my page ( hilios.github.io/jQuery.countdown/ )
* download the module in both normal and minified versions
* place the modules in your moodle install e.g. your custom theme dir, or plugin dir
* /theme/mytheme/amd/src/jquery.countdown.js

you can now include the module and initialise it (there are multiple ways to do this)
php:

1. Create your own AMD module and initialise it:

In your PHP file:
<code php>
$this->page->requires->js_call_amd('theme_mytheme/countdowntimer', 'initialise', $params);
</code>

Javascript module:
<code javascript>
// /theme/mytheme/amd/src/countdowntimer.js
define(['jquery', 'theme_mytheme/jquery.countdown'], function($, c) {
return {
initialise: function ($params) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
}
};
});
</code>

2. Put the javascript into a mustache template:
<code javascript>
// /theme/mytheme/templates/countdowntimer.mustache
<span id="clock"></span>
{{#js}}
require(['jquery', 'theme_mytheme/jquery.countdown'], function($) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
});
{{/js}}
</code>

3. Call the javascript directly from php (although who would want to put javascript into php? ergh):
<code php>
$PAGE->requires->js_amd_inline('
require(['theme_mytheme/jquery.countdown'], function(min) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
});
');
</code>
<br>
Note: It could be useful when you wish to pass a big chunk of data from php directly into a JS variable, to workaround MDL-62468 .<br>
Example: https://github.com/moodle/moodle/blob/master/media/player/videojs/classes/plugin.php#L386

===More examples of including 3rd-party JS modules===
* [https://moodle.org/mod/forum/discuss.php?d=327579#p1317252 Adding custom js via AMD (highcharts) to essential theme]

== Embedding AMD code in a page ==
So you have created lots of cool Javascript modules. Great. How do we actually call them? Any javascript code that calls an AMD module must execute AFTER the requirejs module loader has finished loading. We have provided a function "js_call_amd" that will call a single function from an AMD module with parameters.

<code php>
$PAGE->requires->js_call_amd($modulename, $functionname, $params);
</code>

that will "do the right thing" with your block of AMD code and execute it at the end of the page, after our AMD module loader has loaded.
Notes:
* the $modulename is the 'componentname/modulename' discussed above
* the $functionname is the name of a public function exposed by the amd module.
* the $params is an array of params passed as arguments to the function. These should be simple types that can be handled by json_encode (no recursive arrays, or complex classes please).
* if the size of the params array is too large (> 1Kb), this will produce a developer warning. Do not attempt to pass large amounts of data through this function, it will pollute the page size. A preferred approach is to pass css selectors for DOM elements that contain data-attributes for any required data, or fetch data via ajax in the background.

AMD / JS code can also be embedded on a page via mustache templates
see here: https://docs.moodle.org/dev/Templates#What_if_a_template_contains_javascript.3F

== But I have a mega JS file I don't want loaded on every page? ==
Loading all JS files at once and stuffing them in the browser cache is the right choice for MOST js files, there are probably some exceptions. For these files, you can rename the javascript file to end with the suffix "-lazy.js" which indicates that the module will not be loaded by default, it will be requested the first time it is used. There is no difference in usage for lazy loaded modules, the require() call looks exactly the same, it's just that the module name will also have the "-lazy" suffix.

== Useful links ==
* [https://assets.moodlemoot.org/sites/15/20171004085436/JavaScript-AMD-with-RequireJS-presented-by-Daniel-Roperto-Catalyst.pdf JavaScript AMD with RequireJS] presented by Daniel Roperto, Catalyst. (MoodleMOOT AU 2017)
* [[Useful_core_Javascript_modules]]
*[[Guide_to_adding_third_party_jQuery_for_AMD]] by Patrick Thibaudeau
*[https://moodle.org/mod/forum/discuss.php?d=378112#p1524459 How to get variables from PHP into javascript AMD modules in M3.5] Justin Hunt, on Moodle forums.

[[Category:AJAX]]
[[Category:Javascript]]

Javascript Modules

2019-08-05T06:14:15Z

Ryanwyllie:

{{Moodle 2.9}}

= Javascript Modules =

== What is a Javascript module and why do I care? ==

A Javascript module is nothing more than a collection of Javascript code that can be used (reliably) from other pieces of Javascript.

== Why should I package my code as a module? ==

By packaging your code as a module you break your code up into smaller reusable pieces. This is good because:

a) Each smaller piece is simpler to understand / debug

b) Each smaller piece is simpler to test

c) You can re-use common code instead of duplicating it

= How do I write a Javascript module in Moodle? =

Since version 2.9, Moodle supports Javascript modules written using the Asynchronous Module Definition ([https://github.com/amdjs/amdjs-api/wiki/AMD AMD]) API. This is a standard API for creating Javascript modules and you will find many useful third party libraries that are already using this format.

To edit or create an AMD module in Moodle you need to do a couple of things.

Since version 3.8, Moodle supports [https://github.com/lukehoban/es6features#readme ECMAScript 2015 features] (aka ES6) in a cross browser compatible way thanks to [https://babeljs.io/ Babel JS]. In order to achieve the compatibility with older browsers Babel will compile the newer ES6 features back into ES5 Javascript. Unfortunately this means that in order for your Javascript changes to show in the browser they must be compiled by running Grunt, even with the cachejs config setting set to false (i.e. "Development mode").

== Install grunt ==

The AMD modules in Moodle must be processed by some build tools before they will be visible to your web browser. We use "[[grunt]]" as a build tool to wrap our different processes. Grunt is a build tool written in Javascript that runs in the "[http://nodejs.org/ nodejs]" environment.

This means you first have to '''install nodejs''' - and its package manager [https://www.npmjs.com/ npm]. The details of how to install those packages will vary by operating system, but on Linux it's probably similar to "sudo apt-get install nodejs npm". There are downloadable packages for other operating systems here: http://nodejs.org/download/. Moodle currently requires node {{NodeJSVersion}}.

Once this is done, you can '''run the command''':

npm install
npm install -g grunt-cli

from the top of the Moodle directory to install all of the required tools. (You may need extra permissions to use the -g option.)

== Development mode (Moodle v2.9 to v3.7) ==

To avoid having to constantly run grunt, make sure you set the following in your config.php

<code php>
// Prevent JS caching
$CFG->cachejs = false;
</code>

Moodle will now run your module from the amd/src module. Don't forget to switch this off and run 'grunt' before deploying the new version!

In this mode - if you get a strange message in your javascript console like "No define call for core/first" it means you have a syntax error in the javascript you are developing.
Or, "No define call for theme_XXX/loader" as you are probably missing the 'src' folder with relevant JS files. which might happen when you turn debugging ON on a theme that was bought, without 'src' folder :-(

== Development mode (Moodle v3.8 and above) ==

All Javascript code is now compiled using Babel which means Moodle will only ever serve minified Javascript to the browser, even in development mode. However in development mode Moodle will also send the browser the corresponding source map files for each of the Javascript modules. The source map files will tell the browser how to map the minified source code back to the unminified original source code so that the original source files will be displayed in the sources section of the browser's development tools.

While in development mode each of the Javascript modules will appear in the browser's source tree as separate modules (no more giant first.js file!) and they will also be loaded with individual network requests (this is a compromise we had to make thanks to some browser bugs with source map files).

To enable development mode set the '''cachejs''' config value to '''false''' in the admin settings or directly in your config.php file:
<code php>
// Prevent JS caching
$CFG->cachejs = false;
</code>

Since all Javascript must now be compiled you must run Grunt in order for you changes to appear in the browser. However rather than running Grunt manually each time on either the whole project or each file you modified, it is recommended that you just run the '''grunt watch''' task at the root of your Moodle directory. The grunt watch task will listen for changes to the Javascript files in the Moodle directory and will automatically lint and compile only the file that is changed after each change is detected. This removes the need to manually run grunt after each change.

== Running grunt ==

You can run grunt in your plugin's 'amd' directory and it will only operate on your modules. If you're having problems or just want to check your work it is worth running for the 'lint' feature. This can find basic problems. This sub-directory support wont work on Windows unfortunately but there is an alternative: Run grunt from the top directory with the --root=path/to/dir to limit execution to a sub-directory.

See [[Grunt#Running_grunt]] for more details of specific grunt commands which can be used.

If you get the error message

/usr/bin/env: node: No such file or directory

Then see the thread https://github.com/nodejs/node-v0.x-archive/issues/3911

On Ubuntu 14.04 this fixed it for me:

sudo ln -fs /usr/bin/nodejs /usr/local/bin/node

Note: Once you have run grunt and built your code, you will then need to purge Moodle caches otherwise the changes made to your minified files may not be picked up by Moodle.

== ES6 Modules (Moodle v3.8 and above) ==

In addition to AMD module syntax Moodle now supports the [https://github.com/lukehoban/es6features#modules ES6 syntax] for writing Javascript modules. All modules (defined using either syntax) are compatible with one another. Behind the scenes the ES6 module syntax is converted into an AMD syntax as part of the Babel compiling process.

There is one slight difference between the ES6 definition for exporting modules and the RequireJS (AMD) definition.

ES6 allows you to export a “default” value which is actually no different to exporting a named value where the name is “default”. Unfortunately, RequireJS allows for unnamed default exports (e.g. you can do "return SomeClass;") which can be imported by just requiring them in other AMD modules.

That’s a bit confusing, get to the point! Well, it basically means that in Moodle you won’t be able to write an ES6 module that exports both a default and named exports, e.g. "export default function() {...}" and "export const FOO = 'bar'" in the same module. The export default will simply override all other exports in that module.

== Minimum (getting started) module for plugins ==

This shows the absolute minimum module you need to get started adding modules to your plugins. It's actually quite simple...

<code javascript>
// Put this file in path/to/plugin/amd/src
// You can call it anything you like

define(['jquery'], function($) {

return {
init: function() {

// Put whatever you like here. $ is available
// to you as normal.
$(".someclass").change(function() {
alert("It changed!!");
});
}
};
});
</code>

This code passes the jquery module into our function (parameter $). There are a number of other useful modules available in Moodle, some of which you'll probably need in a practical application. See [[Useful_core_Javascript_modules]]. Simply list them in both the define() first parameter and the function callback. E.g.,
<code javascript>
define(['jquery', 'core/str', 'core/ajax'], function($, str, ajax) {
</code>

The idea here is that we will run the 'init' function from our (PHP) code to set things up. This is called from PHP like this...

<code php>
$PAGE->requires->js_call_amd('frankenstyle_path/your_js_filename', 'init');
</code>

Don't forget to supply the complete '[[Frankenstyle]]' path. The .js is not needed.

js_call_amd takes a third parameter which is an ''array'' of parameters. These will translate to individual parameters in the 'init' function call. For example...

<code php>
$PAGE->requires->js_call_amd('block_iomad_company_admin/department_select', 'init', array($first, $last));
</code>

...calls

<code javascript>
return {
init: function(first, last) {
}
</code>

A more comprehensive explanation follows...

== "Hello World" I am a Javascript Module ==
Lets now create a simple Javascript module so we can see how to lay things out.

Each Javascript module is contained in a single source file in the <componentdir>/amd/src folder. The final name of the module is taken from the file name and the component name. E.g. block_overview/amd/src/helloworld.js would be a module named "block_overview/helloworld". the name of the module is important when you want to call it from somewhere else in the code.

After running grunt - the minified Javascript files are stored in the <componentdir>/amd/build folder. The javascript files are renamed to show that they are minified (helloworld.js becomes helloworld.min.js).

Don't forget to add the built files (the ones in amd/build) to your git commits, or in production no-one will see your changes.

Lets create a simple module now:

blocks/overview/amd/src/helloworld.js
<code javascript>
// Standard license block omitted.
/*
* @package block_overview
* @copyright 2015 Someone cool
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

/**
* @module block_overview/helloworld
*/
define(['jquery'], function($) {

/**
* Give me blue.
* @access private
* @return {string}
*/
var makeItBlue = function() {
// We can use our jquery dependency here.
return $('.blue').show();
};

/**
* @constructor
* @alias module:block_overview/helloworld
*/
var greeting = function() {
/** @access private */
var privateThoughts = 'I like the colour blue';

/** @access public */
this.publicThoughts = 'I like the colour orange';

};

/**
* A formal greeting.
* @access public
* @return {string}
*/
greeting.prototype.formal = function() {
return 'How do you do?';
};

/**
* An informal greeting.
* @access public
* @return {string}
*/
greeting.prototype.informal = function() {
return 'Wassup!';
};
return greeting;
});
</code>

The most interesting line above is:
<code>
define(['jquery'], function($) {
</code>

All AMD modules must call "define()" as the first and only global scoped piece of code. This ensures the javascript code contains no global variables and will not conflict with any other loaded module. The name of the module does not need to be specified because it is determined from the filename and component (but it can be listed in a comment for JSDoc as shown here).

The first argument to "define" is the list of dependencies for the module. This argument must be passed as an array, even if there is only one. In this example "jquery" is a dependency. "jquery" is shipped as a core module is available to all AMD modules.

The second argument to "define" is the function that defines the module. This function will receive as arguments, each of the requested dependencies in the same order they were requested. In this example we receive JQuery as an argument and we name the variable "$" (it's a JQuery thing). We can then access JQuery normally through the $ variable which is in scope for any code in our module.

The rest of the code in this example is a standard way to define a Javascript module with public/private variables and methods. There are many ways to do this, this is only one.

It is important that we are returning 'greeting'. If there is no return then your module will be declared as undefined.

== Loading modules dynamically ==
What do you do if you don't know in advance which modules will be required? Stuffing all possible required modules in the define call is one solution, but it's ugly and it only works for code that is in an AMD module (what about inline code in the page?). AMD lets you load a dependency any time you like.
<code javascript>

// Load a new dependency.
require(['mod_wiki/timer'], function(timer) {
// timer is available to do my bidding.
});
</code>

== Including an external javascript/jquery library ==
If you want to include a javascript / jquery library downloaded from the internet you can do so as follows:

'''Warning: if the library you download, supports AMD but is already "named" you will not be able to include it directly'''
e.g.
<code javascript>
define("typeahead.js", *[ "jquery" ], function(a0) {
return factory(a0);
});
</code>
will not work, as moodle injects it's own define name when loading the library.

If the library is in AMD format and has a define:
e.g. i want to include the jquery final countdown timer on my page ( hilios.github.io/jQuery.countdown/ )
* download the module in both normal and minified versions
* place the modules in your moodle install e.g. your custom theme dir, or plugin dir
* /theme/mytheme/amd/src/jquery.countdown.js

you can now include the module and initialise it (there are multiple ways to do this)
php:

1. Create your own AMD module and initialise it:

In your PHP file:
<code php>
$this->page->requires->js_call_amd('theme_mytheme/countdowntimer', 'initialise', $params);
</code>

Javascript module:
<code javascript>
// /theme/mytheme/amd/src/countdowntimer.js
define(['jquery', 'theme_mytheme/jquery.countdown'], function($, c) {
return {
initialise: function ($params) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
}
};
});
</code>

2. Put the javascript into a mustache template:
<code javascript>
// /theme/mytheme/templates/countdowntimer.mustache
<span id="clock"></span>
{{#js}}
require(['jquery', 'theme_mytheme/jquery.countdown'], function($) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
});
{{/js}}
</code>

3. Call the javascript directly from php (although who would want to put javascript into php? ergh):
<code php>
$PAGE->requires->js_amd_inline('
require(['theme_mytheme/jquery.countdown'], function(min) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
});
');
</code>
<br>
Note: It could be useful when you wish to pass a big chunk of data from php directly into a JS variable, to workaround MDL-62468 .<br>
Example: https://github.com/moodle/moodle/blob/master/media/player/videojs/classes/plugin.php#L386

===More examples of including 3rd-party JS modules===
* [https://moodle.org/mod/forum/discuss.php?d=327579#p1317252 Adding custom js via AMD (highcharts) to essential theme]

== Embedding AMD code in a page ==
So you have created lots of cool Javascript modules. Great. How do we actually call them? Any javascript code that calls an AMD module must execute AFTER the requirejs module loader has finished loading. We have provided a function "js_call_amd" that will call a single function from an AMD module with parameters.

<code php>
$PAGE->requires->js_call_amd($modulename, $functionname, $params);
</code>

that will "do the right thing" with your block of AMD code and execute it at the end of the page, after our AMD module loader has loaded.
Notes:
* the $modulename is the 'componentname/modulename' discussed above
* the $functionname is the name of a public function exposed by the amd module.
* the $params is an array of params passed as arguments to the function. These should be simple types that can be handled by json_encode (no recursive arrays, or complex classes please).
* if the size of the params array is too large (> 1Kb), this will produce a developer warning. Do not attempt to pass large amounts of data through this function, it will pollute the page size. A preferred approach is to pass css selectors for DOM elements that contain data-attributes for any required data, or fetch data via ajax in the background.

AMD / JS code can also be embedded on a page via mustache templates
see here: https://docs.moodle.org/dev/Templates#What_if_a_template_contains_javascript.3F

== But I have a mega JS file I don't want loaded on every page? ==
Loading all JS files at once and stuffing them in the browser cache is the right choice for MOST js files, there are probably some exceptions. For these files, you can rename the javascript file to end with the suffix "-lazy.js" which indicates that the module will not be loaded by default, it will be requested the first time it is used. There is no difference in usage for lazy loaded modules, the require() call looks exactly the same, it's just that the module name will also have the "-lazy" suffix.

== Useful links ==
* [https://assets.moodlemoot.org/sites/15/20171004085436/JavaScript-AMD-with-RequireJS-presented-by-Daniel-Roperto-Catalyst.pdf JavaScript AMD with RequireJS] presented by Daniel Roperto, Catalyst. (MoodleMOOT AU 2017)
* [[Useful_core_Javascript_modules]]
*[[Guide_to_adding_third_party_jQuery_for_AMD]] by Patrick Thibaudeau
*[https://moodle.org/mod/forum/discuss.php?d=378112#p1524459 How to get variables from PHP into javascript AMD modules in M3.5] Justin Hunt, on Moodle forums.

[[Category:AJAX]]
[[Category:Javascript]]

Javascript Modules

2019-08-05T05:57:08Z

Ryanwyllie: /* How do I write a Javascript module in Moodle? */

{{Moodle 2.9}}

= Javascript Modules =

== What is a Javascript module and why do I care? ==

A Javascript module is nothing more than a collection of Javascript code that can be used (reliably) from other pieces of Javascript.

== Why should I package my code as a module? ==

By packaging your code as a module you break your code up into smaller reusable pieces. This is good because:

a) Each smaller piece is simpler to understand / debug

b) Each smaller piece is simpler to test

c) You can re-use common code instead of duplicating it

= How do I write a Javascript module in Moodle? =

Since version 2.9, Moodle supports Javascript modules written using the Asynchronous Module Definition ([https://github.com/amdjs/amdjs-api/wiki/AMD AMD]) API. This is a standard API for creating Javascript modules and you will find many useful third party libraries that are already using this format.

To edit or create an AMD module in Moodle you need to do a couple of things.

Since version 3.8, Moodle supports [https://babeljs.io/docs/en/learn#ecmascript-2015-features ECMAScript 2015 features] (aka ES6) in a cross browser compatible way thanks to [https://babeljs.io/ Babel JS]. In order to achieve the compatibility with older browsers Babel will compile the newer ES6 features back into ES5 Javascript. Unfortunately this means that in order for your Javascript changes to show in the browser they must be compiled by running Grunt, even with the cachejs config setting set to false (i.e. "Development mode").

== Install grunt ==

The AMD modules in Moodle must be processed by some build tools before they will be visible to your web browser. We use "[[grunt]]" as a build tool to wrap our different processes. Grunt is a build tool written in Javascript that runs in the "[http://nodejs.org/ nodejs]" environment.

This means you first have to '''install nodejs''' - and its package manager [https://www.npmjs.com/ npm]. The details of how to install those packages will vary by operating system, but on Linux it's probably similar to "sudo apt-get install nodejs npm". There are downloadable packages for other operating systems here: http://nodejs.org/download/. Moodle currently requires node {{NodeJSVersion}}.

Once this is done, you can '''run the command''':

npm install
npm install -g grunt-cli

from the top of the Moodle directory to install all of the required tools. (You may need extra permissions to use the -g option.)

== Development mode (Moodle v2.9 to v3.7) ==

To avoid having to constantly run grunt, make sure you set the following in your config.php

<code php>
// Prevent JS caching
$CFG->cachejs = false;
</code>

Moodle will now run your module from the amd/src module. Don't forget to switch this off and run 'grunt' before deploying the new version!

In this mode - if you get a strange message in your javascript console like "No define call for core/first" it means you have a syntax error in the javascript you are developing.
Or, "No define call for theme_XXX/loader" as you are probably missing the 'src' folder with relevant JS files. which might happen when you turn debugging ON on a theme that was bought, without 'src' folder :-(

== Development mode (Moodle v3.8 and above) ==

All Javascript code is now compiled using Babel which means Moodle will only ever serve minified Javascript to the browser, even in development mode. However in development mode Moodle will also send the browser the corresponding source map files for each of the Javascript modules. The source map files will tell the browser how to map the minified source code back to the unminified original source code so that the original source files will be displayed in the sources section of the browser's development tools.

While in development mode each of the Javascript modules will appear in the browser's source tree as separate modules (no more giant first.js file!) and they will also be loaded with individual network requests (this is a compromise we had to make thanks to some browser bugs with source map files).

To enable development mode set the '''cachejs''' config value to '''false''' in the admin settings or directly in your config.php file:
<code php>
// Prevent JS caching
$CFG->cachejs = false;
</code>

Since all Javascript must now be compiled you must run Grunt in order for you changes to appear in the browser. However rather than running Grunt manually each time on either the whole project or each file you modified, it is recommended that you just run the '''grunt watch''' task at the root of your Moodle directory. The grunt watch task will listen for changes to the Javascript files in the Moodle directory and will automatically lint and compile only the file that is changed after each change is detected. This removes the need to manually run grunt after each change.

== Running grunt ==

You can run grunt in your plugin's 'amd' directory and it will only operate on your modules. If you're having problems or just want to check your work it is worth running for the 'lint' feature. This can find basic problems. This sub-directory support wont work on Windows unfortunately but there is an alternative: Run grunt from the top directory with the --root=path/to/dir to limit execution to a sub-directory.

See [[Grunt#Running_grunt]] for more details of specific grunt commands which can be used.

If you get the error message

/usr/bin/env: node: No such file or directory

Then see the thread https://github.com/nodejs/node-v0.x-archive/issues/3911

On Ubuntu 14.04 this fixed it for me:

sudo ln -fs /usr/bin/nodejs /usr/local/bin/node

Note: Once you have run grunt and built your code, you will then need to purge Moodle caches otherwise the changes made to your minified files may not be picked up by Moodle.

== Minimum (getting started) module for plugins ==

This shows the absolute minimum module you need to get started adding modules to your plugins. It's actually quite simple...

<code javascript>
// Put this file in path/to/plugin/amd/src
// You can call it anything you like

define(['jquery'], function($) {

return {
init: function() {

// Put whatever you like here. $ is available
// to you as normal.
$(".someclass").change(function() {
alert("It changed!!");
});
}
};
});
</code>

This code passes the jquery module into our function (parameter $). There are a number of other useful modules available in Moodle, some of which you'll probably need in a practical application. See [[Useful_core_Javascript_modules]]. Simply list them in both the define() first parameter and the function callback. E.g.,
<code javascript>
define(['jquery', 'core/str', 'core/ajax'], function($, str, ajax) {
</code>

The idea here is that we will run the 'init' function from our (PHP) code to set things up. This is called from PHP like this...

<code php>
$PAGE->requires->js_call_amd('frankenstyle_path/your_js_filename', 'init');
</code>

Don't forget to supply the complete '[[Frankenstyle]]' path. The .js is not needed.

js_call_amd takes a third parameter which is an ''array'' of parameters. These will translate to individual parameters in the 'init' function call. For example...

<code php>
$PAGE->requires->js_call_amd('block_iomad_company_admin/department_select', 'init', array($first, $last));
</code>

...calls

<code javascript>
return {
init: function(first, last) {
}
</code>

A more comprehensive explanation follows...

== "Hello World" I am a Javascript Module ==
Lets now create a simple Javascript module so we can see how to lay things out.

Each Javascript module is contained in a single source file in the <componentdir>/amd/src folder. The final name of the module is taken from the file name and the component name. E.g. block_overview/amd/src/helloworld.js would be a module named "block_overview/helloworld". the name of the module is important when you want to call it from somewhere else in the code.

After running grunt - the minified Javascript files are stored in the <componentdir>/amd/build folder. The javascript files are renamed to show that they are minified (helloworld.js becomes helloworld.min.js).

Don't forget to add the built files (the ones in amd/build) to your git commits, or in production no-one will see your changes.

Lets create a simple module now:

blocks/overview/amd/src/helloworld.js
<code javascript>
// Standard license block omitted.
/*
* @package block_overview
* @copyright 2015 Someone cool
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

/**
* @module block_overview/helloworld
*/
define(['jquery'], function($) {

/**
* Give me blue.
* @access private
* @return {string}
*/
var makeItBlue = function() {
// We can use our jquery dependency here.
return $('.blue').show();
};

/**
* @constructor
* @alias module:block_overview/helloworld
*/
var greeting = function() {
/** @access private */
var privateThoughts = 'I like the colour blue';

/** @access public */
this.publicThoughts = 'I like the colour orange';

};

/**
* A formal greeting.
* @access public
* @return {string}
*/
greeting.prototype.formal = function() {
return 'How do you do?';
};

/**
* An informal greeting.
* @access public
* @return {string}
*/
greeting.prototype.informal = function() {
return 'Wassup!';
};
return greeting;
});
</code>

The most interesting line above is:
<code>
define(['jquery'], function($) {
</code>

All AMD modules must call "define()" as the first and only global scoped piece of code. This ensures the javascript code contains no global variables and will not conflict with any other loaded module. The name of the module does not need to be specified because it is determined from the filename and component (but it can be listed in a comment for JSDoc as shown here).

The first argument to "define" is the list of dependencies for the module. This argument must be passed as an array, even if there is only one. In this example "jquery" is a dependency. "jquery" is shipped as a core module is available to all AMD modules.

The second argument to "define" is the function that defines the module. This function will receive as arguments, each of the requested dependencies in the same order they were requested. In this example we receive JQuery as an argument and we name the variable "$" (it's a JQuery thing). We can then access JQuery normally through the $ variable which is in scope for any code in our module.

The rest of the code in this example is a standard way to define a Javascript module with public/private variables and methods. There are many ways to do this, this is only one.

It is important that we are returning 'greeting'. If there is no return then your module will be declared as undefined.

== Loading modules dynamically ==
What do you do if you don't know in advance which modules will be required? Stuffing all possible required modules in the define call is one solution, but it's ugly and it only works for code that is in an AMD module (what about inline code in the page?). AMD lets you load a dependency any time you like.
<code javascript>

// Load a new dependency.
require(['mod_wiki/timer'], function(timer) {
// timer is available to do my bidding.
});
</code>

== Including an external javascript/jquery library ==
If you want to include a javascript / jquery library downloaded from the internet you can do so as follows:

'''Warning: if the library you download, supports AMD but is already "named" you will not be able to include it directly'''
e.g.
<code javascript>
define("typeahead.js", *[ "jquery" ], function(a0) {
return factory(a0);
});
</code>
will not work, as moodle injects it's own define name when loading the library.

If the library is in AMD format and has a define:
e.g. i want to include the jquery final countdown timer on my page ( hilios.github.io/jQuery.countdown/ )
* download the module in both normal and minified versions
* place the modules in your moodle install e.g. your custom theme dir, or plugin dir
* /theme/mytheme/amd/src/jquery.countdown.js

you can now include the module and initialise it (there are multiple ways to do this)
php:

1. Create your own AMD module and initialise it:

In your PHP file:
<code php>
$this->page->requires->js_call_amd('theme_mytheme/countdowntimer', 'initialise', $params);
</code>

Javascript module:
<code javascript>
// /theme/mytheme/amd/src/countdowntimer.js
define(['jquery', 'theme_mytheme/jquery.countdown'], function($, c) {
return {
initialise: function ($params) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
}
};
});
</code>

2. Put the javascript into a mustache template:
<code javascript>
// /theme/mytheme/templates/countdowntimer.mustache
<span id="clock"></span>
{{#js}}
require(['jquery', 'theme_mytheme/jquery.countdown'], function($) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
});
{{/js}}
</code>

3. Call the javascript directly from php (although who would want to put javascript into php? ergh):
<code php>
$PAGE->requires->js_amd_inline('
require(['theme_mytheme/jquery.countdown'], function(min) {
$('#clock').countdown('2020/10/10', function(event) {
$(this).html(event.strftime('%D days %H:%M:%S'));
});
});
');
</code>
<br>
Note: It could be useful when you wish to pass a big chunk of data from php directly into a JS variable, to workaround MDL-62468 .<br>
Example: https://github.com/moodle/moodle/blob/master/media/player/videojs/classes/plugin.php#L386

===More examples of including 3rd-party JS modules===
* [https://moodle.org/mod/forum/discuss.php?d=327579#p1317252 Adding custom js via AMD (highcharts) to essential theme]

== Embedding AMD code in a page ==
So you have created lots of cool Javascript modules. Great. How do we actually call them? Any javascript code that calls an AMD module must execute AFTER the requirejs module loader has finished loading. We have provided a function "js_call_amd" that will call a single function from an AMD module with parameters.

<code php>
$PAGE->requires->js_call_amd($modulename, $functionname, $params);
</code>

that will "do the right thing" with your block of AMD code and execute it at the end of the page, after our AMD module loader has loaded.
Notes:
* the $modulename is the 'componentname/modulename' discussed above
* the $functionname is the name of a public function exposed by the amd module.
* the $params is an array of params passed as arguments to the function. These should be simple types that can be handled by json_encode (no recursive arrays, or complex classes please).
* if the size of the params array is too large (> 1Kb), this will produce a developer warning. Do not attempt to pass large amounts of data through this function, it will pollute the page size. A preferred approach is to pass css selectors for DOM elements that contain data-attributes for any required data, or fetch data via ajax in the background.

AMD / JS code can also be embedded on a page via mustache templates
see here: https://docs.moodle.org/dev/Templates#What_if_a_template_contains_javascript.3F

== But I have a mega JS file I don't want loaded on every page? ==
Loading all JS files at once and stuffing them in the browser cache is the right choice for MOST js files, there are probably some exceptions. For these files, you can rename the javascript file to end with the suffix "-lazy.js" which indicates that the module will not be loaded by default, it will be requested the first time it is used. There is no difference in usage for lazy loaded modules, the require() call looks exactly the same, it's just that the module name will also have the "-lazy" suffix.

== Useful links ==
* [https://assets.moodlemoot.org/sites/15/20171004085436/JavaScript-AMD-with-RequireJS-presented-by-Daniel-Roperto-Catalyst.pdf JavaScript AMD with RequireJS] presented by Daniel Roperto, Catalyst. (MoodleMOOT AU 2017)
* [[Useful_core_Javascript_modules]]
*[[Guide_to_adding_third_party_jQuery_for_AMD]] by Patrick Thibaudeau
*[https://moodle.org/mod/forum/discuss.php?d=378112#p1524459 How to get variables from PHP into javascript AMD modules in M3.5] Justin Hunt, on Moodle forums.

[[Category:AJAX]]
[[Category:Javascript]]

Useful core Javascript modules

2018-12-06T06:17:44Z

Ryanwyllie: /* PubSub (core/pubsub) */

{{Moodle 2.9}}

The source code for all these modules (and a number of others) can be found in lib/amd/src.

== Configuration settings (core/config) ==

Example of using config module:
<code javascript>
require(['core/config’], function(mdlcfg) {
console.log(mdlcfg.wwwroot); // outputs the wwwroot of moodle to console
});
</code>

== Language strings (core/str) ==

Example of using language strings module (retrieved via ajax, if the string is not yet loaded)
<code javascript>
require([‘core/str’], function(str) {
// start retrieving the localized string; store the promise that some time in the future the string will be there.
var editaPresent = str.get_string('edita', 'core', stringargument);
// as soon as the string is retrieved, i.e. the promise has been fulfilled,
// edit the text of a UI element so that it then is the localized string
// Note: $.when can be used with an arbitrary number of promised things
$.when(editaPresent).done(function(localizedEditString) {
$("someUIElementSelector").text = localizedEditString;
});
});
</code>

The string will be retrieved via AJAX request on the first use and cached in browser local storage until purge caches or site upgrade

IT IS NOT RECOMMENDED to call:
<code php>
$PAGE->requires->string_for_js('edita', 'core'); // You do not need this!
</code>

Because:
* The list of strings used now needs to be maintained in 2 places
* The strings are always sent, and bloat the page size even if they are not used
* All strings fetched via the AJAX method above are cached in browser local storage anyway, so these strings will never be used 99% of the time

==Notifications (core/notification)==

Examples:
<code javascript>
require(['core/notification’], function(notification) {
notification.alert('Hello', 'Welcome to my site!', 'Continue');
});
</code>

Strings and notifications:
<code javascript>
require(['core/str', 'core/notification’], function(str, notification) {
str.get_strings([
{'key' : 'delete'},
{'key' : 'confirmdeletetag', component : 'tag'},
{'key' : 'yes'},
{'key' : 'no'},
]).done(function(s) {
notification.confirm(s[0], s[1], s[2], s[3], function() {
window.location.href = href;
});
}
).fail(notification.exception);
});
</code>

== URL module (core/url) ==

Useful Functions:
<code javascript>
// Generate an absolute URL by using the relative path to a file and optionally slash arguments
url.fileUrl(relativeScript, slashArgs)
// Generate an absolute URL from the given relative path, include the URL parameters and possibly the current session key
url.relativeUrl(relativePath, params, includeSessionKey)
// Generates an image url using the filename of the image and the Moodle component (core, plugin, etc.) where it can be found
url.imageUrl(imagename, component)
</code>

Example:

<code javascript>
// Prerequisites:
// - A Javascript file is present under $CFG->wwwroot."/path/to/file.js"
require(['core/url'], function(url) {
url.fileUrl("/path/to/file.js", "");
console.log("Generated URL: " + url);
});
</code>

== Ajax Module (core/ajax) ==

The preferred way to write new ajax interactions in Moodle is to use the javascript module "core/ajax" which can directly call existing web service functions. This saves having to worry about security in ajax functionality because it's all done for you.

For the full story, see [[AJAX]]

== Tree (core/tree) ==
{{Moodle 3.1}}
If you want to add a hierarchical interface, you should use the tree module. It will handle user interaction and accessibility for you.

<code javascript>
define(['jquery', 'core/tree'], function($, Tree) {
return {
init: function() {
new Tree("css/jquery selector of the tree container");
}
};
});
</code>

Read more about the [[Tree]] module

== Modal (core/modal) ==
{{Moodle 3.2}}

If you'd like to add a modal to your page the modal modules will handle all of the magic for you, all you need to bring is your content!
<code javascript>
require(['jquery', 'core/modal_factory'], function($, ModalFactory) {
var trigger = $('#create-modal');
ModalFactory.create({
title: 'test title',
body: '<p>test body content</p>',
footer: 'test footer content',
}, trigger)
.done(function(modal) {
// Do what you want with your new modal.

// Maybe... add a class to the modal dialog, to be able to style it.
modal.getRoot().addClass('mydialog');
});
});
</code>

Read more about the [[AMD_Modal]] module

== Paged content (core/paged_content_factory) ==
{{Moodle 3.6}}

If you need to create a paged content region to asynchronously load the pages as the user requests them then you can use the paged content modules.

Read more about the [[AMD_paged_content]] module

== PubSub (core/pubsub) ==
{{Moodle 3.6}}

A simple module to do event subscription and publishing in JavaScript without the need for jQuery.

Read more about the [[AMD_pubsub}} module

==See also==
* [[Javascript Modules]]
* [[Fragment]]

[[Category:AJAX]]
[[Category:Javascript]]

Useful core Javascript modules

2018-12-06T06:17:22Z

Ryanwyllie:

{{Moodle 2.9}}

The source code for all these modules (and a number of others) can be found in lib/amd/src.

== Configuration settings (core/config) ==

Example of using config module:
<code javascript>
require(['core/config’], function(mdlcfg) {
console.log(mdlcfg.wwwroot); // outputs the wwwroot of moodle to console
});
</code>

== Language strings (core/str) ==

Example of using language strings module (retrieved via ajax, if the string is not yet loaded)
<code javascript>
require([‘core/str’], function(str) {
// start retrieving the localized string; store the promise that some time in the future the string will be there.
var editaPresent = str.get_string('edita', 'core', stringargument);
// as soon as the string is retrieved, i.e. the promise has been fulfilled,
// edit the text of a UI element so that it then is the localized string
// Note: $.when can be used with an arbitrary number of promised things
$.when(editaPresent).done(function(localizedEditString) {
$("someUIElementSelector").text = localizedEditString;
});
});
</code>

The string will be retrieved via AJAX request on the first use and cached in browser local storage until purge caches or site upgrade

IT IS NOT RECOMMENDED to call:
<code php>
$PAGE->requires->string_for_js('edita', 'core'); // You do not need this!
</code>

Because:
* The list of strings used now needs to be maintained in 2 places
* The strings are always sent, and bloat the page size even if they are not used
* All strings fetched via the AJAX method above are cached in browser local storage anyway, so these strings will never be used 99% of the time

==Notifications (core/notification)==

Examples:
<code javascript>
require(['core/notification’], function(notification) {
notification.alert('Hello', 'Welcome to my site!', 'Continue');
});
</code>

Strings and notifications:
<code javascript>
require(['core/str', 'core/notification’], function(str, notification) {
str.get_strings([
{'key' : 'delete'},
{'key' : 'confirmdeletetag', component : 'tag'},
{'key' : 'yes'},
{'key' : 'no'},
]).done(function(s) {
notification.confirm(s[0], s[1], s[2], s[3], function() {
window.location.href = href;
});
}
).fail(notification.exception);
});
</code>

== URL module (core/url) ==

Useful Functions:
<code javascript>
// Generate an absolute URL by using the relative path to a file and optionally slash arguments
url.fileUrl(relativeScript, slashArgs)
// Generate an absolute URL from the given relative path, include the URL parameters and possibly the current session key
url.relativeUrl(relativePath, params, includeSessionKey)
// Generates an image url using the filename of the image and the Moodle component (core, plugin, etc.) where it can be found
url.imageUrl(imagename, component)
</code>

Example:

<code javascript>
// Prerequisites:
// - A Javascript file is present under $CFG->wwwroot."/path/to/file.js"
require(['core/url'], function(url) {
url.fileUrl("/path/to/file.js", "");
console.log("Generated URL: " + url);
});
</code>

== Ajax Module (core/ajax) ==

The preferred way to write new ajax interactions in Moodle is to use the javascript module "core/ajax" which can directly call existing web service functions. This saves having to worry about security in ajax functionality because it's all done for you.

For the full story, see [[AJAX]]

== Tree (core/tree) ==
{{Moodle 3.1}}
If you want to add a hierarchical interface, you should use the tree module. It will handle user interaction and accessibility for you.

<code javascript>
define(['jquery', 'core/tree'], function($, Tree) {
return {
init: function() {
new Tree("css/jquery selector of the tree container");
}
};
});
</code>

Read more about the [[Tree]] module

== Modal (core/modal) ==
{{Moodle 3.2}}

If you'd like to add a modal to your page the modal modules will handle all of the magic for you, all you need to bring is your content!
<code javascript>
require(['jquery', 'core/modal_factory'], function($, ModalFactory) {
var trigger = $('#create-modal');
ModalFactory.create({
title: 'test title',
body: '<p>test body content</p>',
footer: 'test footer content',
}, trigger)
.done(function(modal) {
// Do what you want with your new modal.

// Maybe... add a class to the modal dialog, to be able to style it.
modal.getRoot().addClass('mydialog');
});
});
</code>

Read more about the [[AMD_Modal]] module

== Paged content (core/paged_content_factory) ==
{{Moodle 3.6}}

If you need to create a paged content region to asynchronously load the pages as the user requests them then you can use the paged content modules.

Read more about the [[AMD_paged_content]] module

== PubSub (core/pubsub) ==

A simple module to do event subscription and publishing in JavaScript without the need for jQuery.

Read more about the [[AMD_pubsub}} module

==See also==
* [[Javascript Modules]]
* [[Fragment]]

[[Category:AJAX]]
[[Category:Javascript]]

AMD pubsub

2018-12-06T06:17:11Z

Ryanwyllie:

{{Moodle 3.6}}

= What is this? =
A simple module to do event subscription and publishing in JavaScript. It was added to avoid the need to use jQuery and the DOM.

= Why would I use it? =
Allows modules to communicate with one another indirectly without the need to include jQuery or touch the DOM.

= Example =
<code javascript>
// Module A.
require(['core/pubsub'], function(PubSub) {
PubSub.publish('example-event', someData);
});

// Module B.
require(['core/pubsub'], function(PubSub) {
PubSub.subscribe('example-event', function(someData) {
console.log('Received', someData);
});
});
</code>

AMD pubsub

2018-12-06T06:15:19Z

Ryanwyllie: Created page with "{{Moodle 3.6}} = What is this? = A simply module to do event subscription and publishing in JavaScript. It was added to avoid the need to use jQuery and the DOM. = Why would..."

{{Moodle 3.6}}

= What is this? =
A simply module to do event subscription and publishing in JavaScript. It was added to avoid the need to use jQuery and the DOM.

= Why would I use it? =
Allows modules to communicate with one another indirectly without the need to include jQuery or touch the DOM.

= Example =
<code javascript>
// Module A.
require(['core/pubsub'], function(PubSub) {
PubSub.publish('example-event', someData);
});

// Module B.
require(['core/pubsub'], function(PubSub) {
PubSub.subscribe('example-event', function(someData) {
console.log('Received', someData);
});
});
</code>

Useful core Javascript modules

2018-12-06T06:03:54Z

Ryanwyllie:

{{Moodle 2.9}}

The source code for all these modules (and a number of others) can be found in lib/amd/src.

== Configuration settings (core/config) ==

Example of using config module:
<code javascript>
require(['core/config’], function(mdlcfg) {
console.log(mdlcfg.wwwroot); // outputs the wwwroot of moodle to console
});
</code>

== Language strings (core/str) ==

Example of using language strings module (retrieved via ajax, if the string is not yet loaded)
<code javascript>
require([‘core/str’], function(str) {
// start retrieving the localized string; store the promise that some time in the future the string will be there.
var editaPresent = str.get_string('edita', 'core', stringargument);
// as soon as the string is retrieved, i.e. the promise has been fulfilled,
// edit the text of a UI element so that it then is the localized string
// Note: $.when can be used with an arbitrary number of promised things
$.when(editaPresent).done(function(localizedEditString) {
$("someUIElementSelector").text = localizedEditString;
});
});
</code>

The string will be retrieved via AJAX request on the first use and cached in browser local storage until purge caches or site upgrade

IT IS NOT RECOMMENDED to call:
<code php>
$PAGE->requires->string_for_js('edita', 'core'); // You do not need this!
</code>

Because:
* The list of strings used now needs to be maintained in 2 places
* The strings are always sent, and bloat the page size even if they are not used
* All strings fetched via the AJAX method above are cached in browser local storage anyway, so these strings will never be used 99% of the time

==Notifications (core/notification)==

Examples:
<code javascript>
require(['core/notification’], function(notification) {
notification.alert('Hello', 'Welcome to my site!', 'Continue');
});
</code>

Strings and notifications:
<code javascript>
require(['core/str', 'core/notification’], function(str, notification) {
str.get_strings([
{'key' : 'delete'},
{'key' : 'confirmdeletetag', component : 'tag'},
{'key' : 'yes'},
{'key' : 'no'},
]).done(function(s) {
notification.confirm(s[0], s[1], s[2], s[3], function() {
window.location.href = href;
});
}
).fail(notification.exception);
});
</code>

== URL module (core/url) ==

Useful Functions:
<code javascript>
// Generate an absolute URL by using the relative path to a file and optionally slash arguments
url.fileUrl(relativeScript, slashArgs)
// Generate an absolute URL from the given relative path, include the URL parameters and possibly the current session key
url.relativeUrl(relativePath, params, includeSessionKey)
// Generates an image url using the filename of the image and the Moodle component (core, plugin, etc.) where it can be found
url.imageUrl(imagename, component)
</code>

Example:

<code javascript>
// Prerequisites:
// - A Javascript file is present under $CFG->wwwroot."/path/to/file.js"
require(['core/url'], function(url) {
url.fileUrl("/path/to/file.js", "");
console.log("Generated URL: " + url);
});
</code>

== Ajax Module (core/ajax) ==

The preferred way to write new ajax interactions in Moodle is to use the javascript module "core/ajax" which can directly call existing web service functions. This saves having to worry about security in ajax functionality because it's all done for you.

For the full story, see [[AJAX]]

== Tree (core/tree) ==
{{Moodle 3.1}}
If you want to add a hierarchical interface, you should use the tree module. It will handle user interaction and accessibility for you.

<code javascript>
define(['jquery', 'core/tree'], function($, Tree) {
return {
init: function() {
new Tree("css/jquery selector of the tree container");
}
};
});
</code>

Read more about the [[Tree]] module

== Modal (core/modal) ==
{{Moodle 3.2}}

If you'd like to add a modal to your page the modal modules will handle all of the magic for you, all you need to bring is your content!
<code javascript>
require(['jquery', 'core/modal_factory'], function($, ModalFactory) {
var trigger = $('#create-modal');
ModalFactory.create({
title: 'test title',
body: '<p>test body content</p>',
footer: 'test footer content',
}, trigger)
.done(function(modal) {
// Do what you want with your new modal.

// Maybe... add a class to the modal dialog, to be able to style it.
modal.getRoot().addClass('mydialog');
});
});
</code>

Read more about the [[AMD_Modal]] module

== Paged content (core/paged_content_factory) ==
{{Moodle 3.6}}

If you need to create a paged content region to asynchronously load the pages as the user requests them then you can use the paged content modules.

Read more about the [[AMD_paged_content]] module

==See also==
* [[Javascript Modules]]
* [[Fragment]]

[[Category:AJAX]]
[[Category:Javascript]]

AMD paged content

2018-12-06T05:59:41Z

Ryanwyllie: Created page with "{{Moodle 3.6}} = What is this? = The paged content factory allows you to quickly and easily create a paged content region (see [https://getbootstrap.com/docs/4.0/components/p..."

{{Moodle 3.6}}

= What is this? =
The paged content factory allows you to quickly and easily create a paged content region (see [https://getbootstrap.com/docs/4.0/components/pagination/]). The factory will handle creating and configuring the region for you so that it confirms with the standard Bootstrap markup (on the Boost and Clean themes).

= PHP =
This can be used to render the paged content in PHP however it requires that all pages be preloaded and rendered in PHP and doesn't support AJAX loading of additional pages.

If you render the paged content in PHP it will initialise all of the JavaScript required to control the navigation between pages for the user.

To render it in PHP simply render the [https://github.com/moodle/moodle/blob/master/lib/templates/paged_content.mustache] template with the appropriate context.

= JavaScript =
This is the real strength of this module. Core comes shipped with a paged content factory module which will create and enhance the paged content region for you. It allows you to very quickly and easily create a paged content region that asynchronously loads the pages as the user requests them.

== How do I use it? ==
The paged content factory has a few different ways to create the element depending on how you'd like it to behave. The creation methods can be split into two categories, either asynchronous (you don't have all of the data loaded) or static (you already have all of the data you want to paginate).

If you have all of the data up front then you can give it all to the createFromStaticList list function along with a few options and the factory will create the paged content element for you.

If you'd like to load the data asynchronously then you can use one of the other create functions, depending on whether you'd like to specify the limit of items per page and/or the total number of items. All of the async create functions require you to provide a callback function which will be called in order to load and render the requested pages.

Each create function also optionally takes a config object (more information below).

=== Load and render callback ===
As part of the create functions you will be required to provide a callback function that the paged content code will call when the user requests a page. The callback function will be provided a list of pages being requested (this is typically just one page but not guaranteed to be). Each page data contains the page number (indexed from 1), the limit, and offset to use to load the data.

The callback must return an array of promises (order matching the given array) that resolve with the rendered HTML for that page.

The second parameter to the callback will be an object containing actions which can be called to trigger behaviour in the paged content. At the moment the only action that can be called is allItemsLoaded which your callback function should call to tell the paged content code that there are no more items to load. This is only required if you created the paged content area without a total upfront.

=== Config ===
You can provide a configuration object to the paged content factory in order to control certain behaviours

The current options are:
* dropdown - bool (default: false) - If the pagination controls should be a dropdown instead of a paging bar
* maxPages - int - Maximum number of page options for the dropdown (only works if dropdown is set to true)
* ignoreControlWhileLoading - boolean (default: true) - Disable the pagination controls while a page is being loaded
* controlPlacementBottom - boolean (default: false) - Put the pagination controls under the paged content area (default is above)
* eventNamespace - string (default: a generated unique id) - Provide a custom namespace to prefix the pagination events with. This can be used if you have code that wants to listen to events for a specific paged content region.
* persistentLimitKey - string (default: null) - If provided the factory will automatically use this value as the key to save the selected limit option in user preferences so that they persist between page loads

= Example: Async load with unknown total number of items =
<code javascript>
require(
[
'jquery',
'core/paged_content_factory',
'core/templates'
],
function(
$,
PagedContentFactory,
Templates
) {
// Some container for your paged content.
var container = $('#container');

PagedContentFactory.createWithLimit(
// Show 10 items per page.
10,
// Callback to load and render the items as the user clicks on the pages.
function(pagesData, actions) {
return pagesData.map(function(pageData) {
// Your function to load the data for the given limit and offset.
return loadData(pageData.limit, pageData.offset)
.then(function(data) {
// You criteria for when all of the data has been loaded.
if (data.length > 100) {
// Tell the page content code everything has been loaded now.
actions.allItemsLoaded(pageData.pageNumber);
}

// Your function to render the data you've loaded.
return renderData(data);
});
});
},
// Config to set up the paged content.
{
controlPlacementBottom: true,
eventNamespace: 'example-paged-content',
persistentLimitKey: 'example-paged-content-limit-key'
}
).then(function(html, js) {
// Add the paged content into the page.
Templates.replaceNodeContents(container, html, js);
});
});
</code>

Calendar API

2017-11-14T02:34:13Z

Ryanwyllie:

{{ Moodle 3.3 }}

This page documents the Calendar API as it is in Moodle 3.3 and later. For the API in older versions of Moodle, see [[Calendar_API_old]].

The Calendar API allows you to add, modify and delete events in the calendar for user, groups, courses and the site. As of 3.3 it also allows you to provide actions for these events so that they are then displayed on block_myoverview, which by default is shown on users' dashboard.

==Overview==

The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events to users. These events are generated by other plugins, like activities, to let the user know of an important date. For example, when an assignment opens for submission.

The block_myoverview plugin displays calendar events that have an action associated with them. For example, an activity may have a due date specified, in which case it will create a calendar action event so that the event will display on the dashboard for the user, as well as the calendar. In order to provide the action associated for this event you have to define a callback in your plugin which is detailed below.

==Creating an event==
Creating a new calendar event.

<code php>
require_once($CFG->dirroot.'/calendar/lib.php');

$event = new stdClass();
$event->eventtype = SCORM_EVENT_TYPE_OPEN; // Constant defined somewhere in your code - this can be any string value you want. It is a way to identify the event.
$event->type = CALENDAR_EVENT_TYPE_STANDARD; // This is used for events we only want to display on the calendar, and are not needed on the block_myoverview.
$event->name = get_string('calendarstart', 'scorm', $scorm->name);
$event->description = format_module_intro('scorm', $scorm, $cmid);
$event->courseid = $scorm->course;
$event->groupid = 0;
$event->userid = 0;
$event->modulename = 'scorm';
$event->instance = $scorm->id;
$event->timestart = $scorm->timeopen;
$event->visible = instance_is_visible('scorm', $scorm);
$event->timeduration = 0;

calendar_event::create($event);
</code>

==Updating an event==
You can update an existing event in database by providing at least the event id. If the event is a part of a chain of repeated events, the rest of series event will also be updated (depending on the value of property repeateditall). This function could also be used to insert new event to database, if the given event does not exist yes. The optional parameter $checkcapability is used to check user's capability to edit/add events. By default the $checkcapability parameter is set to true.

<code php>
$eventid = required_param('id', PARAM_INT);
$event = calendar_event::load($eventid);

$data = $mform->get_data();
$event->update($data);
</code>

==Deleting an event==
You can delete an existing event from the database. The optional parameter $deleterepeated is used as an indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also delete all associated files related to the event's editor context.

<code php>
$eventid = required_param('id', PARAM_INT);
$event = calendar_event::load($eventid);
$event->delete($repeats);
</code>

==Event priority==
There might be cases that an activity event will have user and/or group overrides. Therefore we need a way to show only the relevant event on the user's calendar. This is where the 'priority' field comes in.

The event priority is set to the following:
* NULL for non-override events.
<code php>
$event->priority = null;
</code>
* 0 for user override events.
<code php>
$event->priority = CALENDAR_EVENT_USER_OVERRIDE_PRIORITY;
</code>
* A positive integer for group events.

For integer and non-null event priorities, the lower the value, the higher the priority is. Meaning, user overrides always have a higher priority than group overrides. Group override priorities are currently being determined in two ways in core activities:
# In the assignment module, the event priorities for group overrides are being determined from the 'sortorder' column in the 'assign_overrides' table.
# In the lesson and quiz modules, the event priorities for group overrides are being calculated using the functions lesson_get_group_override_priorities($lessonid) and quiz_get_group_override_priorities($quizid).

Should you ever decide to sort out group override priorities by implementing *_get_group_override_priorities(), the recommended return structure would be something like
<code php>
[
'youreventtype1' => $prioritiesforeventtype1,
...
]
</code>
where '$prioritiesforeventtype1' is an associative array that has the timestamp of the group override event as key and the calculated priority as value. For more details, please see the implementation for the lesson module below:
<code php>
/**
* Calculates the priorities of timeopen and timeclose values for group overrides for a lesson.
*
* @param int $lessonid The lesson ID.
* @return array|null Array of group override priorities for open and close times. Null if there are no group overrides.
*/
function lesson_get_group_override_priorities($lessonid) {
global $DB;

// Fetch group overrides.
$where = 'lessonid = :lessonid AND groupid IS NOT NULL';
$params = ['lessonid' => $lessonid];
$overrides = $DB->get_records_select('lesson_overrides', $where, $params, '', 'id, groupid, available, deadline');
if (!$overrides) {
return null;
}

$grouptimeopen = [];
$grouptimeclose = [];
foreach ($overrides as $override) {
if ($override->available !== null && !in_array($override->available, $grouptimeopen)) {
$grouptimeopen[] = $override->available;
}
if ($override->deadline !== null && !in_array($override->deadline, $grouptimeclose)) {
$grouptimeclose[] = $override->deadline;
}
}

// Sort open times in ascending manner. The earlier open time gets higher priority.
sort($grouptimeopen);
// Set priorities.
$opengrouppriorities = [];
$openpriority = 1;
foreach ($grouptimeopen as $timeopen) {
$opengrouppriorities[$timeopen] = $openpriority++;
}

// Sort close times in descending manner. The later close time gets higher priority.
rsort($grouptimeclose);
// Set priorities.
$closegrouppriorities = [];
$closepriority = 1;
foreach ($grouptimeclose as $timeclose) {
$closegrouppriorities[$timeclose] = $closepriority++;
}

return [
'open' => $opengrouppriorities,
'close' => $closegrouppriorities
];
}
</code>

==Action events==

Action events are calendar events that can be actioned. E.g. A student submitting an assignment by a certain date. These events are displayed on the block_myoverview which by default is on users' dashboard. Creating these is the same as creating a normal calendar event except instead of using CALENDAR_EVENT_TYPE_STANDARD as your calendar event type, you use CALENDAR_EVENT_TYPE_ACTION. The events are also sorted on the dashboard by the value specified in the 'timesort' field (unixtime) for the event.

Example of the changes to the above code would be to change the 'type' and to specify the 'timesort' value.

<code php>
$event->type = CALENDAR_EVENT_TYPE_ACTION;
$event->timesort = $scorm->timeclose;
</code>

[[File:my overview sam student.png]]

===The callbacks===

There are 3 callbacks your module can implement that are used to control when and how your action is shown to the user.

====mod_xyz_core_calendar_is_event_visible()====
This callback determines if an event should be visible throughout the site. For example, the assignment module creates a grading event for teachers. We do not want this event being visible to users who can not perform this action (eg. students), so we return false for those users. If you do not implement this function then the event will always be visible.

<code php>
/**
* Is the event visible?
*
* This is used to determine global visibility of an event in all places throughout Moodle. For example,
* the ASSIGN_EVENT_TYPE_GRADINGDUE event will not be shown to students on their calendar, and
* ASSIGN_EVENT_TYPE_DUE events will not be shown to teachers.
*
* @param calendar_event $event
* @return bool Returns true if the event is visible to the current user, false otherwise.
*/
function mod_assign_core_calendar_is_event_visible(calendar_event $event) {
global $CFG, $USER;

require_once($CFG->dirroot . '/mod/assign/locallib.php');

$cm = get_fast_modinfo($event->courseid)->instances['assign'][$event->instance];
$context = context_module::instance($cm->id);

$assign = new assign($context, $cm, null);

if ($event->eventtype == ASSIGN_EVENT_TYPE_GRADINGDUE) {
return $assign->can_grade();
} else {
return !$assign->can_grade() && $assign->can_view_submission($USER->id);
}
}
</code>

====mod_xyz_core_calendar_provide_event_action()====
This function takes a calendar event and provides the action associated with it, or null if there is none in which case the event will not be shown in block_myoverview (but will still be shown in the calendar block). This is used by the block_myoverview plugin. If you do not implement this function then the events created by your plugin will not be shown on the block.

Eg.
<code php>
function mod_scorm_core_calendar_provide_event_action(calendar_event $event,
\core_calendar\action_factory $factory) {
global $CFG;

require_once($CFG->dirroot . '/mod/scorm/locallib.php');

$cm = get_fast_modinfo($event->courseid)->instances['scorm'][$event->instance];

if (!empty($cm->customdata['timeclose']) && $cm->customdata['timeclose'] < time()) {
// The scorm has closed so the user can no longer submit anything.
return null;
}

// Restore scorm object from cached values in $cm, we only need id, timeclose and timeopen.
$customdata = $cm->customdata ?: [];
$customdata['id'] = $cm->instance;
$scorm = (object)($customdata + ['timeclose' => 0, 'timeopen' => 0]);

// Check that the SCORM activity is open.
list($actionable, $warnings) = scorm_get_availability_status($scorm);

return $factory->create_instance(
get_string('enter', 'scorm'),
new \moodle_url('/mod/scorm/view.php', array('id' => $cm->id)),
1,
$actionable
);
}
</code><br />
The variables to pass to <code>create_instance()</code> are -

# $name String The name of the event, eg. get_string('dosomething', 'mod_xyz').
# $url \moodle_url The URL the user visits in order to perform this action.
# $itemcount int This represents the number of items that require action (eg. Need to write 3 forum posts). If this is 0 then the event is not displayed.
# $actionable bool This determines if the event is currently able to be acted on. Eg. the activity may not currently be open due to date restrictions so the event is shown to the user to let them know that there is an upcoming event but the url will not be active.

====mod_xyz_core_calendar_event_action_shows_item_count()====
This function determines if a given event should display the number of items to action on block_myoverview. For example, if the event type is ASSIGN_EVENT_TYPE_GRADINGDUE then we only display the item count if there are one or more assignments to grade. If you do not implement this function then the item count is always hidden. This is usually fine as the majority of events only have an item count of '1' (eg. Submitting an assignment) and there is no need display the item count.

Eg.

<code php>
/**
* Callback function that determines whether an action event should be showing its item count
* based on the event type and the item count.
*
* @param calendar_event $event The calendar event.
* @param int $itemcount The item count associated with the action event.
* @return bool
*/
function mod_assign_core_calendar_event_action_shows_item_count(calendar_event $event, $itemcount = 0) {
// List of event types where the action event's item count should be shown.
$eventtypesshowingitemcount = [
ASSIGN_EVENT_TYPE_GRADINGDUE
];
// For mod_assign, item count should be shown if the event type is 'gradingdue' and there is one or more item count.
return in_array($event->eventtype, $eventtypesshowingitemcount) && $itemcount > 0;
}
</code>

==Refreshing calendar events of activity modules==
A new ad-hoc task 'refresh_mod_calendar_events_task' has been created. This task basically loops through all of the activity modules that implement the '*_refresh_events()' hook.

Sample usage:
<code php>
// Create the instance.
$refreshtask = new refresh_mod_calendar_events_task();

// Add custom data.
$customdata = [
'plugins' => ['assign', 'lesson', 'quiz'] // Optional. If not specified, it will refresh the events of all of the activity modules.
];
$refreshtask->set_custom_data($customdata);

// Queue it.
\core\task\manager::queue_adhoc_task($refreshtask);
</code>

==calendar_get_legacy_events()==
This functions accepts the same inputs as 'calendar_get_events()' but is now utilising the new Moodle Calendar API system. It respects overrides and will also add the action properties, whenever appropriate.

''Note that this function will not work as expected if you pass a list of user ids as the current user session is internally used to determine which events should be visible. More info in https://tracker.moodle.org/browse/MDL-60340''

==Changes to Behat==
The "And I follow "Course1"" Behat step won't work from the Dashboard anymore and has been replaced with "And I am on "Course 1" course homepage" where 'Course 1' is the fullname of the course.

==Drag & drop==

The calendar supports dragging and dropping events within the calendar in order to change the start day for the event. Each type of calendar event can be dragged by a user with sufficient permissions to edit the event.

===Dragging action events===

When an action event is dragged the corresponding property will also be updated in the activity instance that generated the event. For example, dragging the assignment due date event will result in the assignment activity’s due date to be changed.

In order to drag an action event the logged in user must have the moodle/course:manageactivities capability in the activity that generated the event.

For an action event to be draggable the activity that generated it will need to have implemented at least one (but ideally both) callback to handle updating itself after the calendar event is dragged.

====core_calendar_event_timestart_updated (required)====
This callback is required to be implemented by any activity that wishes to have it’s action events draggable in the calendar.

This callback handles updating the activity instance based on the changed action event. The callback will receive the updated calendar event and the corresponding activity instance.

Example:
<code php>
function mod_feedback_core_calendar_event_timestart_updated(\calendar_event $event, \stdClass $feedback) {
global $CFG, $DB;

if (empty($event->instance) || $event->modulename != 'feedback') {
return;
}

if ($event->instance != $feedback->id) {
return;
}

if (!in_array($event->eventtype, [FEEDBACK_EVENT_TYPE_OPEN, FEEDBACK_EVENT_TYPE_CLOSE])) {
return;
}

$courseid = $event->courseid;
$modulename = $event->modulename;
$instanceid = $event->instance;
$modified = false;

$coursemodule = get_fast_modinfo($courseid)->instances[$modulename][$instanceid];
$context = context_module::instance($coursemodule->id);

// The user does not have the capability to modify this activity.
if (!has_capability('moodle/course:manageactivities', $context)) {
return;
}

if ($event->eventtype == FEEDBACK_EVENT_TYPE_OPEN) {
// If the event is for the feedback activity opening then we should
// set the start time of the feedback activity to be the new start
// time of the event.
if ($feedback->timeopen != $event->timestart) {
$feedback->timeopen = $event->timestart;
$feedback->timemodified = time();
$modified = true;
}
} else if ($event->eventtype == FEEDBACK_EVENT_TYPE_CLOSE) {
// If the event is for the feedback activity closing then we should
// set the end time of the feedback activity to be the new start
// time of the event.
if ($feedback->timeclose != $event->timestart) {
$feedback->timeclose = $event->timestart;
$modified = true;
}
}

if ($modified) {
$feedback->timemodified = time();
$DB->update_record('feedback', $feedback);
$event = \core\event\course_module_updated::create_from_cm($coursemodule, $context);
$event->trigger();
}
}
</code>

====core_calendar_get_valid_event_timestart_range====
This callback should calculate the minimum and maximum allowed timestart property for the given calendar event. This will typically be based on the properties of the activity instance, for example the timeopen and timeclose properties of the activity could form the minimum and maximum bounds, respectively.

These values will be used to provide a visual indicator to the user in the calendar UI for which days are valid for the event to be dragged to. It will also be used to validate that the calendar event is being updated to a valid timestart value.

The callback should return an array with two values, the first value representing the minimum cutoff and the second the maximum.

The callback can return an array for each of the minimum and maximum cutoffs, if it has them. The array should contain the timestamp of the cutoff and an error message to be displayed to the user if they attempt to drag an event to a day that violates the limit. For example:
<code php>
[
[1505704373, 'The due date must be after the sbumission start date'], // Minimum cutoff.
[1506741172, 'The due date must be before the cutoff date'] // Maximum cutoff.
]
</code>

If the calendar event has no limits then it should return null in for either/both of the min and max cutoff values to indicate that it isn’t limited. For example:
<code php>
[null, null] // No limits.
</code><br />
<code php>
[null, [1510625037, “This is the maximum cutoff”]] // No minimum cutoff.
</code><br />
<code php>
[[1510625037, “This is the minimum cutoff”], null] // No maximum cutoff.
</code>

If the calendar event has no valid timestart values then the callback should return [false, false]. This is used to prevent the drag and drop of override events in activities that support them (e.g. Assign, Quiz).

Example:
<code php>
function mod_feedback_core_calendar_get_valid_event_timestart_range(\calendar_event $event, \stdClass $instance) {
$mindate = null;
$maxdate = null;

if ($event->eventtype == FEEDBACK_EVENT_TYPE_OPEN) {
// The start time of the open event can't be equal to or after the
// close time of the choice activity.
if (!empty($instance->timeclose)) {
$maxdate = [
$instance->timeclose,
get_string('openafterclose', 'feedback')
];
}
} else if ($event->eventtype == FEEDBACK_EVENT_TYPE_CLOSE) {
// The start time of the close event can't be equal to or earlier than the
// open time of the choice activity.
if (!empty($instance->timeopen)) {
$mindate = [
$instance->timeopen,
get_string('closebeforeopen', 'feedback')
];
}
}

return [$mindate, $maxdate];
}
</code>

Themes overview

2017-11-13T08:28:14Z

Ryanwyllie:

{{Template:Themes}}
Welcome to the new world of themes in Moodle!

A Moodle theme allows the user to change the look and feel of a Moodle site. Themes can be applied on the site, category, course and activity levels by users with permissions to do so. Themes can be designed for specific devices such as mobile phones or tablets. This page explains how themes work in Moodle and is intended to help you create or modify most themes for Moodle.

You can use contributed themes or create your entire own to share with the community. Themes can also be based on parent themes with only few customizations. Themes accomplish this using CSS, changing the underlying markup structure and also adding Javascript to add more advanced behaviors.

Most theme developers simply add a few changes to their new theme by basing it on an existing one. The Moodle Theme architecture is designed in such a way whereby the base theme will act as a fall-back that is used when nothing has been defined in the theme based on it. This makes it easy to create new themes that simply seek out to make minor changes.

==Whats new?==

When Moodle releases a new version. All changes that affect themes are listed in the theme/upgrade.txt file. This is the most up-to date place to find about all changes to a specific version of Moodle and will always be kept up to date.

[https://github.com/moodle/moodle/blob/master/theme/upgrade.txt View upgrade notes]

==The structure of a theme==

Some important things to know when building good themes:

# '''config.php''' - this file is required in every theme. It defines configuration settings and definitions required to make the theme work in Moodle. These include theme, file, region, default region and options.
# '''Layouts and layout files''' - in config.php there is one definition for each page type (see [[#theme_layouts_table|Appendix A: Theme layouts]] for a list of over 12 types). Each page type definition tells Moodle which layout file will be used, what block regions this page type should display and so on. The layout file contains the HTML and the minimum PHP required to display basic structure of pages.
# '''The boost theme''' - is intended to be the best theme to use as a starting point for building a new theme. It supports all the latest theme features and it tries to stay as true to the [http://getbootstrap.com/ Bootstrap] css framework as possible. [[Creating a theme based on boost]]

===Files and folders===
A theme's files are placed in a folder with under moodle/theme folder and have subfolders. They are laid out like this:

{| class="nicetable"
|-
! Directory
! File
! Description
|-
| /
| config.php
| Contains all of the configuration and definitions for each theme
|-
| /
| lib.php
| Contains speciality functions that are used by theme
|-
| /classes
| *.php
| Contains auto-loaded classes for the theme. See [[Automatic class loading]] for more details.
|-
| /classes/output
| *.php
| This is the location for the theme to define overridden renderers. See [[Output renderers]] for more details.
|-
| /
| settings.php
| Contains custom theme settings. These local settings are defined by the theme allowing an administrator to easily alter something about the way it looks or operates. (eg a background colour, or a header image)
|-
| /
| version.php
| Contains the theme name, version number and Moodle version requirements for using the theme
|-
| /fonts/
| *.woff, *.ttf, *.eot, *.svg, *.otf
| Theme fonts (since 2.6).
|-
| /fonts_core/
| *.woff, *.ttf, *.eot, *.svg, *.otf
| Contains fonts that override standard core fonts (since 2.6).
|-
| /fonts_plugins/plugintype/pluginname/
| *.woff, *.ttf, *.eot, *.svg, *.otf
| Contains fonts that override plugin fonts (since 2.6).
|-
| /amd/src/
| *.js
| All specialty JavaScript files the theme requires should be located in here. Javascript should be written as an AMD module. For more information see [[Javascript Modules]].
|-
| /lang/[langcode]/
| *.php
| Any special language files the theme requires should be located in here.
|-
| /templates/
| *.mustache
| Contains the mustache template files for the themes. (Including overridden ones). See [[Templates]] for more information.
|-
| /layout/
| *.php
| Contains the layout files for the theme.
|-
| /pix/
| *.png, *.jpg, *.gif, *.svg
| Contains any images the theme makes use of either in CSS or in the layout files.
|-
| /pix/
| favicon.ico
| The favicon to display for this theme.
|-
| /pix/
| screenshot.png
| A screenshot of the theme to be displayed in on the theme selection screen.
|-
| /pix_core/
| *.png, *.jpg, *.gif, *.svg
| Contains images that override standard core images.
|-
| /pix_plugins/plugintype/pluginname/
| *.png, *.jpg, *.gif, *.svg
| Contains images that override plugin images.
|-
| /style/
| *.css
| Default location for CSS files.
|-
| /less/
| *.less
| Default location for Less files if your theme uses less.
|-
| /scss/
| *.scss
| Default location for SCSS files if your theme uses SCSS.
|}

There are also several other places that stylesheets can be included from (see the CSS how and why section below).

It is possible to override icons used in base themes without interfering with core code by placing these in dataroot/pix and dataroot/pix_plugins. Where a theme extends a base theme and provides its own icons, these icons will still be used.

It is possible to override mustache templates used in base themes without interfering with core code by placing these in templates/[componentname]/[templatename].mustache.

==Theme options==
All theme options are set within the config.php file for the theme. The settings that are most used are: parents, sheets, layouts, and javascripts. Have a look at the '''[[#theme_options_table|theme options table]]''' for a complete list of theme options which include lesser used specialised or advanced settings.

===Basic theme config example===
Lets have a look at the boost theme configuration file and the different bits that make it up:
<code php>
defined('MOODLE_INTERNAL') || die();

require_once(__DIR__ . '/lib.php');

$THEME->name = 'boost';
$THEME->sheets = [];
$THEME->editor_sheets = [];
$THEME->scss = function($theme) {
return theme_boost_get_main_scss_content($theme);
};

$THEME->layouts = [
// Most backwards compatible layout without the blocks - this is the layout used by default.
'base' => array(
'file' => 'columns1.php',
'regions' => array(),
),
// Standard layout with blocks, this is recommended for most pages with general information.
'standard' => array(
'file' => 'columns2.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
// Main course page.
'course' => array(
'file' => 'columns2.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
'options' => array('langmenu' => true),
),
'coursecategory' => array(
'file' => 'columns2.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
// Part of course, typical for modules - default page layout if $cm specified in require_login().
'incourse' => array(
'file' => 'columns2.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
// The site home page.
'frontpage' => array(
'file' => 'columns2.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
'options' => array('nonavbar' => true),
),
// Server administration scripts.
'admin' => array(
'file' => 'columns2.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
// My dashboard page.
'mydashboard' => array(
'file' => 'columns2.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
'options' => array('langmenu' => true),
),
// My public page.
'mypublic' => array(
'file' => 'columns2.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
'login' => array(
'file' => 'login.php',
'regions' => array(),
'options' => array('langmenu' => true),
),

// Pages that appear in pop-up windows - no navigation, no blocks, no header.
'popup' => array(
'file' => 'columns1.php',
'regions' => array(),
'options' => array('nofooter' => true, 'nonavbar' => true),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'columns1.php',
'regions' => array(),
'options' => array('nofooter' => true, 'nocoursefooter' => true),
),
// Embeded pages, like iframe/object embeded in moodleform - it needs as much space as possible.
'embedded' => array(
'file' => 'embedded.php',
'regions' => array()
),
// Used during upgrade and install, and for the 'This site is undergoing maintenance' message.
// This must not have any blocks, links, or API calls that would lead to database or cache interaction.
// Please be extremely careful if you are modifying this layout.
'maintenance' => array(
'file' => 'maintenance.php',
'regions' => array(),
),
// Should display the content and basic headers only.
'print' => array(
'file' => 'columns1.php',
'regions' => array(),
'options' => array('nofooter' => true, 'nonavbar' => false),
),
// The pagelayout used when a redirection is occuring.
'redirect' => array(
'file' => 'embedded.php',
'regions' => array(),
),
// The pagelayout used for reports.
'report' => array(
'file' => 'columns2.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
// The pagelayout used for safebrowser and securewindow.
'secure' => array(
'file' => 'secure.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre'
)
];

$THEME->parents = [];
$THEME->enable_dock = false;
$THEME->csstreepostprocessor = 'theme_boost_css_tree_post_processor';
$THEME->extrascsscallback = 'theme_boost_get_extra_scss';
$THEME->prescsscallback = 'theme_boost_get_pre_scss';
$THEME->yuicssmodules = array();
$THEME->rendererfactory = 'theme_overridden_renderer_factory';
$THEME->undeletableblocktypes = '';
</code>

===Basic theme example settings explained===
First up you will notice everything is added to $THEME. This is the theme's configuration object, it is created by Moodle using default settings and is then updated by whatever settings you add to it.

; $THEME->name : The first setting, is the theme's name. This should simply be whatever your theme's name is, most likely whatever you named your theme directory.

; $THEME->sheets : An array containing the names of the CSS stylesheets to include for this theme. Boost uses scss instead of css so it doesn't list any files here. Note that it is just the name of the stylesheet and does not contain the directory or the file extension. Moodle assumes that the theme's stylesheets will be located in the styles directory of the theme and have .css as an extension.

; $THEME->editorsheets : An array containing the names of the CSS stylesheets to include for the TinyMCE text editor content area. Boost does not list any stylesheets here so TinyMCE will use plain text styles.

; $THEME->layouts : In this example, boost maps each of the 18 different layout types to one of 6 different layout files. For more information see the [[#Layouts|layouts]] section below.

; $THEME->parents : This defines the themes that the theme will extend. Boost has no parents, but if you were extending boost you would list it here like: $THEME->parents = ['boost'];

; $THEME->enable_dock : Boost does not support docking blocks. For a example of a theme with a dock for blocks, see theme_bootstrapbase.

; $THEME->csstreepostprocessor : Boost uses a function to post process the CSS. This is an advanced feature and is used in boost to automatically apply vendor prefixes to CSS styles.

; $THEME->yuicssmodules : This is an old setting that defines a list of YUI css files to load. These files interfere with existing styles and it is recommended to set this to an empty string to prevent any files being included.

; $THEME->rendererfactory : Almost all themes need this setting to be set to 'theme_overridden_renderer_factory' or the theme will not be able to customise any core renderers.

; $THEME->undeletableblocktypes : This is a comma separated list of block types that cannot be deleted in this theme. If you don't define this - the admin and settings blocks will be undeletable by default. Because Boost provides alternate ways to navigate it does not require any blocks.

'''''Note''''': When you first begin writing themes, make sure you take a look at the configuration files of the other themes that get shipped with Moodle. You will get a good picture of how everything works, and what is going on in a theme, simply by reading it and taking notice of what it is including or excluding.

==CSS==
===Locations of CSS files===
First lets look at where CSS can be included from within Moodle:
; \theme\themename\style\*.css : This is the default location for all of the stylesheets that are used by a theme and the place which should be used by a theme designer if this theme is using CSS. Alternatives to CSS are LESS and SCSS which are more powerful, flexible and easier to maintain.

New theme developers should note that the order in which CSS files are found and included creates a hierarchy. This order ensures that the rules, within a theme's style sheets, take precedence over identical rules in other files that may have been introduced before. This can both extend another files definitions (see parent array in the config file) and also ensures that the current theme's CSS rules/definitions have the last say.

There are other locations that can be used (although very rarely) to include CSS in a page. A developer of a php file can manually specify a stylesheet from anywhere within Moodle, like the database. Usually, if code is doing this, it is because there is a non-theme config or plugin setting that contains information requires special CSS information. As a theme designer you should be aware of, but not have to worry about, these locations of CSS files. Here are some examples:

; {pluginpath}\styles.css e.g. \block\blockname\styles.css or \mod\modname\styles.css : Every plugin can have its own styles.css file. This file should only contain the required CSS rules for the module and should not add anything to the look of the plugin such as colours, font sizes, or margins other than those that are truly required.<br />Theme specific styles for a plugin should be located within the themes styles directory.
; {pluginpath}\styles_themename.css : This should only ever be used by plugin developers. It allows them to write CSS that is designed for a specific theme without having to make changes to that theme. You will notice that this is never used within Moodle and is designed to be used only by contributed code.

As theme designers, we will only use the first method of introducing CSS: adding rules to a stylesheet file located in the theme's style directory.
===Better than CSS===
Browsers understand CSS well - but it is hard to write and maintain. The language does not support inheritance and reuse and does not allow configuration with variables. This is why CSS pre-processors were invented. Moodle supports 2 different types of CSS pre-processors (Less and Sass) but the Sass pre-processor is recommended by far.

For more information on Less and Sass see:
* [https://en.wikipedia.org/wiki/Less_(stylesheet_language) Less (wikipedia)]
* [https://en.wikipedia.org/wiki/Sass_(stylesheet_language) Sass (wikipedia)]

To use either one, define $THEME->lessfile = 'filename'; or $THEME->scss = 'filename'; in your themes config.php. Moodle will then use one of it's in-built CSS pre-processor to compile the CSS the first time it is loaded (or everytime if themedesignermode is enabled in $CFG).

===Moodle's core CSS organisation===
The next thing to look at is the organisation of CSS and rules within a theme. Although as a theme designer it is entirely up to you as to how you create and organise your CSS. Please note that none of the themes provided in the standard install by Moodle use CSS stylesheets directly. Instead they use either LESS or SCSS to generate the style sheets. They all list one main LESS or SCSS file named "moodle" in the less or scss folders and this file uses imports to load all other required files.

===How to write effective CSS rules within Moodle===
Writing good CSS rules is incredibly important.

Due to performance requirements and browser limitations, all of the CSS files are combined into a single CSS file that gets included every time. This means that rules need to be written in such a way as to minimise the chances of a collision leading to unwanted styles being applied. Whilst writing good CSS is something most designers strive for we have implemented several new body classes and prompt developers to use appropriate classnames.

====<body> CSS id and classes ====
The ID tag that gets applied to the body will always be a representation of the URI. For example if you are looking at a forum posting and the URI is '/mod/forum/view.php' then the body tags ID will be '#page-mod-forum-view'.

As well as the body's ID attribute the URI is also exploded to form several CSS classes that get added to the body tag, so in the above example '/mod/forum/view' you would end up with the following classes being added to the body tag '.path-mod', '.path-mod-forum'. Note that '.path-mod-forum-view' is not added as a class, this is intentionally left out to lessen confusion and duplication as rules can relate directly to the page by using the ID and do not require the final class.

The body ID and body classes described above will form the bread and butter for many of the CSS rules you will need to write for your theme, however there are also several other very handy classes that get added to the body tag that will be beneficial to you once you start your journey down the rabbit hole that is themeing. Some of the more interesting classes are listed below.

* If JavaScript is enabled then 'jsenabled' will be added as a class to the body tag allowing you to style based on JavaScript being enabled or not.
* Either 'dir-rtl' or 'dir-ltr' will be added to the body as a class depending on the direction of the language pack: rtl = right to left, ltr = left to right. This allows you to determine your text-alignment based on language if required.
* A class will be added to represent the language pack currently in use, by default en_utf8 is used by Moodle and will result in the class 'lang-en_utf8' being added to the body tag.
* The wwwroot for Moodle will also be converted to a class and added to the body tag allowing you to stylise your theme based on the URL through which it was reached. e.g. http://sam.moodle.local/moodle/ will become '.sam-moodle-local—moodle'
* If the current user is not logged then '.notloggedin' will be added to the body tag.
* The course format type will be added such as format-weeks
* The course id, context id and category id are all added as in "course-11 context-616 cmid-202 category-1"
* The pagelayout is added as "pagelayout-incourse"

What does all of this look like in practise? Well using the above example /mod/forum/view.php you would get at least the following body tag:
<code html>
<body id="page-mod-forum-view" class="format-weeks forumtype-social path-mod path-mod-forum safari dir-ltr lang-en yui-skin-sam yui3-skin-sam damyon-per-in-moodle-com--stable_master pagelayout-incourse course-11 context-616 cmid-202 category-1 jsenabled">
</code>

====Writing your rules====

By following the [[CSS coding style]] and CSS best-practices and understanding the [http://htmlhelp.com/reference/css/structure.html#cascade cascading order] of CSS a theme developer will reduce collisions and lines of CSS that is written. CSS classes have been placed where it is believed anyone may want to apply their own styles.

When starting to write rules make sure that you have a good understanding of where you want those rules to be applied, it is a good idea to make the most of the body classes mentioned above.
If you want to write a rule for a specific page make use of the body tag's ID, e.g.:

<code css>#page-mod-forum-view .forumpost {
border: 1px solid blue;
}</code>

If you want to write a rule that will be applied all throughout the forum.:

<code css>.path-mod-forum .forumpost {
border: 1px solid blue;
}</code>

The other very important thing to take into consideration is the structure leading up to the tag you want to style. Browsers apply conflicting styles with priority on the more specific selectors. It can be very beneficial to keep this in mind and write full selectors that rely on the structure of the tags leading to the tag you wish to style.

By making use of body id's and classes and writing selectors to take into account the leading structure you can greatly minimise the chance of a collision both with Moodle now and in the future.

It is also important to write as FEW rules as possible. CSS is extremely hard to maintain and lots of CSS is bad for client side performance. Themes based on the Bootstrap CSS framework can achieve most things without writing a single additional CSS rule. Please read [http://v4-alpha.getbootstrap.com/ the Bootstrap documentation] and learn how to use Bootstrap well to avoid adding unnecessary CSS rules for things already provided by the framework.

==Layouts==
Layouts are defined in '''config.php'''.

All themes are required to define the layouts they wish to be responsible for as well as create; however, many layout files are required by those layouts. If the theme is overriding another theme then it is a case of deciding which layouts this new theme should override. If the theme is a completely fresh start then you will need to define a layout for each of the different possibilities.

It is also important to note that a new theme that will base itself on another theme (overriding it) does not need to define any layouts or use any layout files if there are no changes that it wishes to make to the layouts of the existing theme.

As mentioned earlier, layouts are defined in config.php within $THEME->layouts. The following is an example of one such layout definition:
<code php>
$THEME->layouts = array(
// Standard layout with blocks, this is recommended for most pages with general information
'standard' => array(
'theme' => 'boost',
'file' => 'columns2.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre'
)
)
</code>
The first thing Moodle looks at is the name of the layout, in this case it is `standard` (the array key in PHP), it then looks at the settings for the layout, this is the theme, file, regions, and default region. There are also a couple of other options that can be set by a layout.

; theme : is the theme the layout file exists in. That's right: you can make use of layouts from other installed themes. ''Optional''
; file : is the name of the layout file this layout wants to use. ''Required''
; regions : is the different block regions (places you can put blocks) within the theme. ''Required''
; defaultregion : is the default location when adding new blocks. '''Required if regions is non-empty, otherwise optional'''
; options : an array of layout specific options described in detail below. '''Optional'''

The '''theme''' is optional. Normally the the layout file is looked for in the current theme, or, if it is not there, in the parent theme. However, you can use a layout file from any other theme by giving the theme name here.

You can define whatever regions you like. You just need to pick a name for each one. Most themes just use one or both of '''side_pre''' and '''side_post''', which is like 'left side' and 'right side', except in right to left languages, when they are reversed. If you say in config.php that your the layout provides regions called 'fred' and 'barney', then you must call $OUTPUT->blocks_for_region('fred') and $OUTPUT->blocks_for_region('barney') somewhere in the layout file.

The final setting '''options''' is a special case that only needs to be set if you want to make use of it. This setting allows the theme designer to specify special options that they would like to create that can be later accessed within the layout file. This allows the theme to make design decisions during the definition and react upon those decisions in what ever layout file is being used.

One such place this has been used is within the boost theme. If you take a look first at theme/boost/config.php you will notice that several layouts specify options '''langmenu''' and '''nonavbar''' which can both be set to either true or false. The layout options can then be used on the layout .php files, mustache templates and renderers.
<code php>
<?php
$hasnavbar = (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar());
$hasfooter = (empty($PAGE->layout_options['nofooter']));
?>
</code>

==Layout files==
Layout files are used to provide a different layout of the elements of the page for different types of pages in Moodle.

In the config.php for a theme - there is a list of 'layouts' which map a page type to a specific php page in the layout folder for the theme.

For example:
''theme/boost/config.php''
<code php>
...
'popup' => array(
'file' => 'columns1.php',
'regions' => array(),
'options' => array('nofooter' => true, 'nonavbar' => true),
),
...
</code>

This means every page that has pagetype 'popup' will be displayed with the 'theme/themename/layout/columns1.php' file, it will have no block regions and there are some options that will be available to the page in the global variable "$PAGE->layout_options".

It is possible to implement a layout file directly in php by echoing the HTML for the page, or mixing php tags with HTML - but a better way to create a layout file is to gather all the information required for the layout into a context and render it with a mustache template.

[[Templates| Read about mustache templates]]

Using templates for layout files makes a lot of sense because they are easier to read and maintain than mixing PHP and HTML in the same file.

A simple example of a layout file using a template is at:

''theme/boost/layout/columns1.php''
<code php>
<?php

$bodyattributes = $OUTPUT->body_attributes([]);

$templatecontext = [
'sitename' => format_string($SITE->shortname, true, ['context' => context_course::instance(SITEID), "escape" => false]),
'output' => $OUTPUT,
'bodyattributes' => $bodyattributes
];

echo $OUTPUT->render_from_template('theme_boost/columns1', $templatecontext);
</code>

This example puts some variables into a templatecontext and then calls "render_from_template" to render the mustache template for this layout. The template is located at: "theme/boost/templates/columns1.mustache". It is possible to put PHP classes in the context for the mustache template - and any public properties or methods which accept no arguments will be available to the template. $OUTPUT has several useful public methods which accept no arguments and is a valuable class when creating a layout template in mustache.

The mustache template for this layout is shown here:

''theme/boost/templates/columns1.mustache''
<code handlebars>
{{{ output.doctype }}}
<html {{{ output.htmlattributes }}}>
<head>
<title>{{{ output.page_title }}}</title>
<link rel="shortcut icon" href="{{{ output.favicon }}}" />
{{{ output.standard_head_html }}}
<meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>

<body {{{ bodyattributes }}}>

<div id="page-wrapper">

{{{ output.standard_top_of_body_html }}}

<div id="page" class="container-fluid">
<div id="page-content" class="row">
<div id="region-main-box" class="col-xs-12">
<section id="region-main">
<div class="card card-block">
{{{ output.course_content_header }}}
{{{ output.main_content }}}
{{{ output.course_content_footer }}}
</div>
</section>
</div>
</div>
</div>
</div>
{{{ output.standard_end_of_body_html }}}
</body>
</html>
{{#js}}
require(['theme_boost/loader']);
{{/js}}
</code>

Explaining each line of this template will answer a lot of questions. This example contains only the very minimal required functions to generate a valid layout. You should consider all of the sections below as required in every layout file (although any of the HTML tags can and should be altered).

<code handlebars>
{{{ output.doctype }}}
</code>

This is an example of calling a function on $OUTPUT in php. Because there is a public method on the output class named "doctype" which accepts no arguments - mustache will call it and return the output. We call a function to generate the doctype tag because calling this function returns us the correct HTML for the document type for this theme AND it sets a different content type header (including the charset) depending on the doc type for the theme. Setting a correct charset in every page is important to prevent a class of XSS attacks.

<code handlebars>
<html {{{ output.htmlattributes }}}>
</code>

Now we have returned our root tag - the html tag. We included a set of default attributes for the page by calling the htmlattributes function of our output class. This includes the correct language attribute for the entire page and can include an xml namespace for XHTML documents.

<code handlebars>
<head>
<title>{{{ output.page_title }}}</title>
</code>

Now we have started the head section of our document and set the title for the page. Notice the title is already escaped by the output class so we are using triple mustache tags "{{{" to avoid double escaping.

<code handlebars>
<link rel="shortcut icon" href="{{{ output.favicon }}}" />
</code>

We call a function to get the url to the favicon. The favicon is a file in the theme pix directory and it is served through the "theme/image.php" file which adds special caching headers for images.

<code handlebars>
{{{ output.standard_head_html }}}
</code>

The standard head html function performs a lot of setup that is required for our page. It internally creates the block regions, creates meta tags including keywords for SEO, initialises the common javascript modules, generates links to the style sheets and injects any additional HTML set by the $CFG->additionalhtmlhead setting.

<code handlebars>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>

</code>

This viewport meta tag is recommended by bootstrap for "proper viewport rendering and touch zooming".

<code handlebars>
<body {{{ bodyattributes }}}>
</code>

The body attributes include the language direction and standard classes for the page.

<code handlebars>

<div id="page-wrapper">

</code>

In the Boost theme we use a page-wrapper div to prevent content from disappearing under the fixed header.

<code handlebars>
{{{ output.standard_top_of_body_html }}}

</code>

The standard_top_of_body_html should be included in every layout and includes skip links for accessibility as well as initialising jquery, yui and our own static javascript files.

<code handlebars>
<div id="page" class="container-fluid">
<div id="page-content" class="row">
<div id="region-main-box" class="col-xs-12">
<section id="region-main">
<div class="card card-block">
</code>

This is standard HTML tags defining the content region for this page. The classes come from bootstrap 4.

<code handlebars>
{{{ output.course_content_header }}}
</code>

The course content header allows Moodle plugins to inject things in the top of the page. This is used for "notifications" for example (which are the alert boxes you see after submitting a form).

<code handlebars>
{{{ output.main_content }}}
</code>

The main content function returns the real content for the page.

<code handlebars>
{{{ output.course_content_footer }}}
</code>

The course content footer is used mainly by course formats to insert things after the main content.

<code handlebars>
</div>
</section>
</div>
</div>
</div>
</div>
</code>

We close all our open tags...

<code handlebars>
{{{ output.standard_end_of_body_html }}}
</code>

This function will add all of the javascript that was required while rendering the page. Javascript is added at the end of the document so that it does not block rendering the page.
<code handlebars>
</body>
</html>
</code>

We finish the HTML for our page.
<code handlebars>
{{#js}}
require(['theme_boost/loader']);
{{/js}}
</code>

This final section is required for bootstrap 4 themes and loads all the Bootstrap 4 Javascript dependencies.

If we had block regions in this layout we would need to insert them in the template. The way we would do this is by getting the HTML for the block region in our layout php file, adding it to the context and then including it in our template.

''theme/boost/layout/columns2.php''
<code php>
...
$blockshtml = $OUTPUT->blocks('side-pre');
$hasblocks = strpos($blockshtml, 'data-block=') !== false;
...
$templatecontext = [
...
'sidepreblocks' => $blockshtml,
'hasblocks' => $hasblocks,
...
];
...
echo $OUTPUT->render_from_template('theme_boost/columns2', $templatecontext);
</code>

''theme/boost/templates/columns2.mustache''
<code handlebars>
...
{{#hasblocks}}
<section data-region="blocks-column" class="hidden-print">
{{{ sidepreblocks }}}
</section>
{{/hasblocks}}
...
</code>

When writing layout files think about the different layouts and how the HTML that each makes use of will differ. You will most likely find you do not need a different layout file for each layout, most likely you will be able to reuse the layout files you create across several layouts. You can of course make use of layout options as well to further reduce the number of layout files you need to produce.

Of course as mentioned above if you are customising an existing theme then you may not need to create any layouts or layout files at all.

==Language File==

You need to create a language file for your theme with a few standard strings in it. At a minimum create a file called lang/en/theme_themename.php in your theme folder. For example, the 'boost' theme has a language file called lang/en/theme_boost.php.

You '''must''' define the following lines in your file (example is from Boost theme, adapt as required):

<code php>
$string['pluginname'] = 'Boost';
$string['region-side-pre'] = 'Right';
$string['choosereadme'] = 'Boost is a modern highly-customisable theme. This theme is intended to be used directly, or as a parent theme when creating new themes utilising Bootstrap 4.';
</code>

Without the above you will get notices for the missing strings.

==Making use of images==
Right at the start when listing the features of the new themes system one of the features mentioned was the ability to override any of the standard images within Moodle from within your theme. At this point we will look at both how to make use of your own images within your theme, and secondly how to override the images being used by Moodle.
So first up a bit about images within Moodle,

# Images you want to use within your theme '''need''' to be located within your theme's pix directory.
# You can use sub directories within the pix directory of your theme.
# Images used by Moodle's core are located within the pix directory of Moodle.
# Modules, blocks and other plugins should also store their images within a pix directory.

So making use of your own images first up. Lets assume you have added two image files to the pix directory of your theme.

* /theme/yourthemename/pix/imageone.jpg
* /theme/yourthemename/pix/subdir/imagetwo.png

Notice that one image is a JPEG image, and the second is a PNG. Also the second image is in a subdirectory.

The following code snippet illustrates how to make use of your images within your layout file so they can be inserted by your layout template.
''theme/yourtheme/layout/somelayout.php''
<code php>
...
$templatecontext = [
...
$imageone => $OUTPUT->pix_url('imageone', 'theme'),
$imagetwo => $OUTPUT->pix_url('subdir/imagetwo', 'theme'),
...
];

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

We use a method of Moodle's output library to generate the URL to the image. Its not too important how that functions works but it is important that we use it as it is what allows images within Moodle to be over-rideable.
'''DO NOT''' include the image file extension. Moodle will work it out automatically and it will not work if you do include it.

''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>

The following is how you would use the images from within CSS, SCSS or Less as background images.

<code css>
.divone {
background-image: url([[pix:theme|imageone]]);
}

.divtwo {
background-image: url([[pix:theme|subdir/imagetwo]]);
}
</code>

If this case we have to use some special notations that Moodle looks for. Whenever Moodle hands out a CSS file it first searches for all ''[[something]]'' tags and replaces them with what is required.

The final thing to notice with both of the cases above is that at no point do we include the images file extension.
The reason for this leads us into the next topic, how to override images.

From within a theme you can VERY easily override any standard image within Moodle by simply adding the replacement image to the theme's pix directory in the same sub directory structure as it is in Moodle.
So for instance we wanted to override the following two images:
# /pix/moodlelogo.gif
# /pix/i/user.gif
We would simply need to add our replacement images to the theme in the following locations
# /theme/themename/pix_core/moodlelogo.gif
# /theme/themename/pix_core/i/user.gif
''Note that we have created a '''pix_core''' directory in our theme. For a specific activity module like chat we need a '''pix_plugins/mod/chat''' directory. This directory is "pix_plugins" and then the plugin type (mod) and then the plugin name (chat).

Now the other very cool thing to mention is that Moodle looks for not just replacements of the same image type (jpg, gif, etc...) but also replacements in any image format. This is why above when working with our images we never specified the images file extension.
This means that the following would also work:
# /theme/themename/pix_core/moodlelogo.png
# /theme/themename/pix_core/i/user.bmp

For a more detailed description of how this all works see the page on [[Using images in a theme]].

==Adding custom fonts==
{{Moodle 2.6}}

CSS3 standard introduced the possibility to specify custom fonts, see [http://www.w3schools.com/css/css3_fonts.asp CSS3 Fonts tutorial].

Since 2.6 Moodle includes support for plugin or theme fonts. It is very similar to theme images and pix subdirectories.

===Font file locations===

Depending on where you intend to use the font put it into one of the following locations:
* /lib/fonts/ - fonts used in core
* /plugindir/fonts/ - fonts used by plugin
* /theme/sometheme/fonts/ - theme specific fonts

You can also override core and plugin fonts in theme:
* /theme/sometheme/fonts_core/ - overridden core fonts
* /theme/sometheme/fonts_plugins/plugintype_pluginname/ - overridden fonts of some plugin

Notes:
* subdirectories are not allowed
* use only lowercase alphanumeric characters and underscore in font file names
* WOFF (Web Open Font Format), TTF (True Type Fonts), OTF (OpenType Fonts), SVG (Scalable Vector Graphic) and EOT (Embedded OpenType) fonts are supported, but for the sake of humanity (And [https://tracker.moodle.org/browse/MDL-15169 MDL_15169] ) please use only WOFF fonts to encourage the quick death of IE8.

===CSS placeholders===

<code css>
@font-face {
font-family: ThreeDumb;
src: url([[font:mod_book|3dumb.woff]]);
}
</code>

The placeholder references file /mod/book/fonts/3dumb.woff, the new fontface could be for example used for book headings:

<code css>
.path-mod-book .book_chapter_title {
font-family: ThreeDumb;
}
</code>

If you want to use some font in theme only, you can for example:

<code css>
@font-face {
font-family: goodDogFont;
src: url([[font:theme|good_dog.woff]]);
}

a {font-family:goodDogFont;}
</code>

The font would be stored in /theme/yourtheme/fonts/good_dog.woff file.

===More free fonts===

Please respect all licenses for font redistribution, you can get some nice free fonts from [http://www.fontsquirrel.com http://www.fontsquirrel.com] for example.

===Warning===

This is not intended for forcing of something like Comic Sans on all your visitors...

==Compiling LESS on the fly==
{{Moodle 2.7}}

You can now provide a LESS file that will be compiled (and cached) on the fly. The purpose of this feature is to dynamically allow the customisation of LESS variables.

===Set up your theme===

# Create a .less file in a less folder. Eg. <code>theme/yourtheme/less/myfile.less</code>
# Edit your theme config file, and set $THEME->'''lessfile''' to the name of your file (do not include .less). Eg. <code>$THEME->lessfile = 'myfile'</code>

That's it, the LESS file will be compiled and included in the page on the fly, but that is not very useful yet.

Please note that any file referenced in $THEME->sheets that shares the same name than the LESS file will be silently ignored.

===Inheriting from a parent===

Even if your theme is inheriting from a parent, the LESS file itself will not inherit from anything, this is something you should do manually. For instance, if you want your LESS file to include all of the LESS code provided by ''theme_bootstrapbase'', usually to change the variables, you need to manually import the file like this:

<code>
@import "../../bootstrapbase/less/moodle.less";
</code>

The path needs to be relative and not absolute. You would definitely want to add that rule first in your file and add anything else below it.

===Programmatically injecting LESS===

There are two theme options to specify a callback function that you need to know about:

# $THEME->'''extralesscallback''': To return raw LESS code to be injected.
# $THEME->'''lessvariablescallback''': To return an array of variables and their values.

Typically you will want to simply inject variables, but if you need to perform more complex manipulations, you can return some raw LESS code. The variables returned by the callback are always injected last.

===Performance===

Compiling LESS on the fly is a slow operation, and even though the result is cached you should be aware of it. If you have enabled the configuration setting ''themedesignermode'' you will definintely notice the slowness as the cache only lives for a very short period of time. Ideally your theme should precompile the LESS into CSS, but if you want to provide theme settings to your user, then using this feature is for you.

===Example===

You can refer to the theme ''theme_more'' for an example on how to use this feature.

==Compiling SCSS on the fly==
{{Moodle 3.2}}

You can now provide a SCSS file that will be compiled (and cached) on the fly. The purpose of this feature is to dynamically allow the customisation of SCSS variables. See the [[SCSS|dedicated page on SCSS]].

==Unobvious Things==
===Getting Your Theme to Appear Correctly in Theme Selector===
If you follow the examples on this page to the letter, when you go to the Theme Selector page you may be discouraged to find that your theme does not appear like the other themes do. In fact, instead of your theme's name, you will see something along the lines of <nowiki>[[pluginname]]</nowiki>.

To correct this, you must add the theme/THEMENAME/lang/en/theme_THEMENAME.php file, where THEMENAME is the name of the theme folder. Inside that file, add the string "$string['pluginname'] = 'THEMENAME'; ". Make THEMENAME the name of your theme, however you want it displayed in the Theme selector.

Also, make sure to change your config.php file and version.php file to reflect the correct name:

In config.php: $THEME->name = 'NAME';

In version.php: $plugin->component = 'theme_NAME'; // Full name of the plugin (used for diagnostics)

The screenshot for the theme should be about 500x400 px.

===Required theme divs===

Some parts of Moodle may rely on particular divs, for example the div with id 'page-header'.

Consequently all themes must include at least the divs (with the same ids) that are present in the 'boost' theme.

Missing out these elements may result in unexpected behaviour within specific modules or other plugins.

==Caching==
When Moodle is not running in theme designer mode it will look for a cached version of the compiled CSS for the current theme to serve to the browser requesting the page. If the cached file doesn't yet exist then the CSS will be built and cached during the page request.

The cached CSS is located on disk in Moodle's local cache:
<Moodle data directory >/localcache/theme/<global theme revision>/<theme_name>/css/all_<theme subrevision>.css

The cache path consists of a global theme revision (themerev config value) and a per theme subrevision (themesubrev plugin config value). If either of those are incremented it will change the path to the cache file and cause a new file to be generated.

Individual theme's CSS cache can be built by using the admin CLI script:
php admin/cli/build_theme_css.php --themes boost

The script will only increment the theme subrevision of the theme(s) being built which means existing theme cache's remain untouched.

==Appendix A==
=== Theme options ===

{| class="nicetable" id="theme_options_table"
|-
! Setting
! Effect
|-
| $THEME->'''blockrtlmanipulations'''
| Allows the theme to manipulate how the blocks are displayed in a ''right-to-left'' language. Not recommended since we automatically flip CSS for rtl.
|-
| $THEME->'''csspostprocess'''
| Allows the user to provide the name of a function that all CSS should be passed to before being delivered.
|-
| $THEME->'''csstreepostprocessor''' (Since 3.2)
| Allows the user to provide the name of a function that can perform manipulations on an in-memory representation of the CSS tree. Some useful manipulations are available such as the "theme_boost\autoprefixer" which will automatically add vendor prefixes to all CSS that requires them.
|-
| $THEME->'''doctype'''
| The doctype of the served documents.
|-
| $THEME->'''editor_sheets'''
| An array of stylesheets to include just within the body of the TinyMCE text editor. This is required if you want content to resemble its final appearance in the page, while it is being edited in the text editor.
|-
| $THEME->'''enablecourseajax'''
| If set to false the course AJAX features will be disabled.
|-
| $THEME->'''enable_dock'''
| If set to true the side dock is enabled for blocks.
|-
| $THEME->'''prescsscallback'''
| The name of a function that will return some SCSS code to inject at the beginning of the SCSS file specified in $THEME->scss. (Since 3.2)
|-
| $THEME->'''extrascsscallback'''
| The name of a function that will return some SCSS code to inject at the end of the SCSS file specified in $THEME->scss. (Since 3.2)
|-
| $THEME->'''extralesscallback'''
| The name of a function that will return some LESS code to inject at the end of the LESS file specified in $THEME->lessfile. (Since 2.7)
|-
| $THEME->'''hidefromselector'''
| Used to hide a theme from the theme selector (unless theme designer mode is on). Accepts true or false.
|-
| $THEME->'''javascripts'''
| An array containing the names of JavaScript files located in /javascript/ to include in the theme. (gets included in the head). This setting should no longer be used - please use AMD [[Javascript Modules]] instead.
|-
| $THEME->'''javascripts_footer'''
| As above but will be included in the page footer. This setting should no longer be used - please use AMD [[Javascript Modules]] instead.
|-
| $THEME->'''layouts'''
| An array setting the layouts for the theme
|-
| $THEME->'''lessfile'''
| The name of a LESS file in the theme's less/ folder to compile on the fly. Sheets with the same name will be ignored. (Since 2.7)
|-
| $THEME->'''lessvariablescallback'''
| The name of a function that will modify some LESS variables before compiling the LESS file specified in $THEME->lessfile. (Since 2.7)
|-
| $THEME->'''scss'''
| The name of a SCSS file in the theme's scss/ folder to compile on the fly. Sheets with the same name will be ignored. This can also be a function which returns SCSS, in which case all import paths will be relative to the scss folder in this theme or any of it's parents. (Since 3.2)
|-
| $THEME->'''name'''
| Name of the theme. Most likely the name of the directory in which this file resides.
|-
| $THEME->'''parents'''
| An array of themes to inherit from. If the theme you inherit from inherits from a parent as well, you need to indicate the grand parent here too.
|-
| $THEME->'''parents_exclude_javascripts'''
| An array of JavaScript files NOT to inherit from the themes parents
|-
| $THEME->'''parents_exclude_sheets'''
| An array of stylesheets not to inherit from the themes parents
|-
| $THEME->'''plugins_exclude_sheets'''
| An array of plugin sheets to ignore and not include.
|-
| $THEME->'''renderfactory'''
| Sets a custom render factory to use with the theme, used when working with custom renderers. You most likely want this set to "theme_overridden_renderer_factory".
|-
| $THEME->'''sheets'''
| An array of stylesheets to include for this theme. Should be located in the theme's style directory. Not required if using less or scss.
|-
| $THEME->'''yuicssmodules'''
| An array of YUI CSS modules to be included. This setting should probably be set to '' to prevent and YUI CSS being included.
|-
| $THEME->'''undeletableblocktypes'''
| An array of Block types that must exist on all pages in this theme or this theme will be unusable. If a block type listed here is missing when a page is loaded - it will be auto-created (but only shown for themes that require it).
|-
| $THEME->'''addblockposition'''
| Either BLOCK_ADDBLOCK_POSITION_FLATNAV, BLOCK_ADDBLOCK_POSITION_DEFAULT or BLOCK_ADDBLOCK_POSITION_CUSTOM. Defines where to put the "Add a block" controls when editing is enabled.
|}

===The different layouts as of 21st April 2013===
{| class="nicetable" id="theme_layouts_table"
|-
! Layout
! Purpose
|-
| base
| Most backwards compatible layout without the blocks - this is the layout used by default.
|-
| standard
| Standard layout with blocks, this is recommended for most pages with general information.
|-
| course
| Main course page.
|-
| coursecategory
| Use for browsing through course categories.
|-
| incourse
| Default layout while browsing a course, typical for modules.
|-
| frontpage
| The site home page.
|-
| admin
| Administration pages and scripts.
|-
| mydashboard
| My dashboard page.
|-
| mypublic
| My public page.
|-
| login
| The login page.
|-
| popup
| Pages that appear in pop-up windows - no navigation, no blocks, no header.
|-
| frametop
| Used for legacy frame layouts only. No blocks and minimal footer.
|-
| embedded
| Used for embedded pages, like iframe/object embedded in moodleform - it needs as much space as possible
|-
| maintenance
| Used during upgrade and install. This must not have any blocks, and it is a good idea if it does not have links to other places - for example there should not be a home link in the footer.
|-
| print
| Used when the page is being displayed specifically for printing.
|-
| redirect
| Used when a redirection is occurring
|-
| report
| Used for reports.
|-
| secure
| Used for safebrowser and securewindow.
|}

[[Category:Plugins]]

Block myoverview

2017-05-12T02:48:05Z

Ryanwyllie: /* Themers */

==Overview==
The myoverview block was designed as a replacement to the existing block_course_overview. The block displays a subset of the calendar events, those that have a corresponding action for a user to complete by a given date, for example an assignment due (calendar event) would expect the student to submit their answer by the given date (action). The intention is for the content of the block to show the logged in user an ordered list of actions they need to complete. As each item is completed it should be removed from the list.

===What is a calendar event action?===
A calendar event action represents the action a user must take to satisfy the event. The actions should be discrete and finite. Each action is made up of 4 properties:
; name : A human readable name for the action, for example "add submission"
; url : A URL to direct the user to the page in which they can complete the action
; item count : How many items are required for this action, for example it may be a count of the number of assignments that need grading for a teacher
; actionable : Represents if the action can currently be actioned by the user. A true value means it is currently actionable and a false values means it will be actionable some time in the future

==Plugin developers==
===How do you get events to show in block_myoverview?===
Note: Due to the limitations of the calendar event data structure we only support module plugins (plugins in /mod/) in block_myoverview.

In order for your events to show in this block they will need to be [[dev:Calendar_API#Action_events|action events]]. That means they must have a few specific properties:
* The "type" property must be set to CALENDAR_EVENT_TYPE_ACTION to indicate that this calendar event is intended to be accompanied by an action
* The "timesort" property must be set to a timestamp. This value represents the time by which the user must complete the action. It is used for sorting the events and grouping them into time blocks ('Today', 'Next 7 days' etc)
* The "modulename" property must be the name of your module on disk, e.g. mod/lesson/ has "modulename" set to "lesson"

Once your events are being created with required properties you'll need to add the [[dev:Calendar_API#mod_xyz_core_calendar_provide_event_action.28.29|mod_<plugin>_core_calendar_provide_event_action callback]] to provide the appropriate action for the logged in user for a given event.

===How do you get events from your non-module plugins to show in block_myoverview?===
Unfortunately this isn't currently supported. Only plugins in the 'mod/' directory are supported due to limitations of the current calendar data structure.

===How do you stop your event from showing in block_myoverview once the user has completed the action?===
You simply return null from your [[dev:Calendar_API#mod_xyz_core_calendar_provide_event_action.28.29|mod_<plugin>_core_calendar_provide_event_action callback]] once the user satisfies the criteria for completion of the action. The action events are given to your [[dev:Calendar_API#mod_xyz_core_calendar_provide_event_action.28.29|mod_<plugin>_core_calendar_provide_event_action callback]] each time they are request by block_myoverview so the user will only see the current state of each action they must complete. When the user has nothing left to do (indicated by returning null) it is removed from the list.

Action events that don't have a corresponding action will still be displayed in the calendar.

Note: There is no need to check in your callback that the user can see your activity or that they are enrolled in the course. These checks are done prior to providing the event to the callback. By the time you see the event in the callback you know that the user at least has permission to view your activity.

===How do you get events to show in the calendar but not in block_myoverview?===
You can still create an event with it's "type" property set to CALENDAR_EVENT_TYPE_STANDARD. Anything other than CALENDAR_EVENT_TYPE_ACTION will be ignored by block_myoverview.

===How do you hide an action event from both the calendar and block_myoverview?===
You can use the [[dev:Calendar_API#mod_xyz_core_calendar_is_event_visible.28.29|mod_<plugin>_core_calendar_is_event_visible]] to control the visibility of action events globally throughout Moodle. If you return false from this callback then the action event will no appear in neither the calendar nor block_myoverview. If you do not implement this callback then it is assumed that the event should be visible.

Typically, this callback would be used to check that the user has sufficient permissions to ever be able perform the action. For example, the assign activity ensures that a user without the appropriate role shouldn't see the grading event (i.e. a student shouldn't see the teacher's grading event).

This callback is called after the [[dev:Calendar_API#mod_xyz_core_calendar_provide_event_action.28.29|mod_<plugin>_core_calendar_provide_event_action callback]] which means it has access to the properties generated in that callback. In addition, there is a default rule that any action event with an "itemcount" set to zero is deemed not to be visible.

===How do you display the item count for an action in block_myoverview?===
By default the item count will not be displayed in block myoverview. However if you would like to explicitly change this behaviour then you can implement the [[dev:Calendar_API#mod_xyz_core_calendar_event_action_shows_item_count.28.29|mod_<plugin>_core_calendar_event_action_shows_item_count]]. If the result of that callback is true then the item count will be displayed in the block UI. Some times you may want to show the number of items left to action, for example the assign grading event for teachers shows them the count of the number of submissions left to grade.

===Why isn't the action name a URL when it shows in block_myoverview?===
Whether the action name (i.e. the "name" property on your action) is rendered as plain text or as a hyperlink is determined by the "actionable" property of the action. If "actionable" is true then it means the user can complete the action now, so we render the hyperlink to take them to the place to complete it. However if "actionable" is false then it means the user is unable to complete the action now but will be able to some time in the future, so the action name is rendered in plain text.

===Why isn't your event being given to your *_provide_event_action callback?===
Some common reasons that you may not see your events in your callback:
* The callback is not located in lib.php within your module's directory. It should be in mod/<your_plugin>/lib.php.
* The callback function is not named correctly, it should be [[dev:Calendar_API#mod_xyz_core_calendar_provide_event_action.28.29|mod_<your_plugin>_core_calendar_provide_event_action]]. For example, the callback for the assign module would be named mod_assign_core_calendar_provide_event_action.
* The incorrect modulename property is being set on your calendar event.
* The calendar event is not being set to type CALENDAR_EVENT_TYPE_ACTION.
* The calendar event does not have a timesort property set.
* The logged in user does not have the capability to view your activity.
* The logged in user is not enrolled in the course that has your activity.
* The eventtype property for your event is a completion event but completion is not enabled in the course.

===Why is your event not showing in block_myoverview even though it's being passed into your *_provide_event_action callback?===
Some common reasons that you may not see events in block_myoverview even though they are hitting your callback are:
* Your callback is returning null, which indicates there is no action for the user.
* Your callback is returning an item count of zero, which indicates there is no action for the user.
* Your [[dev:Calendar_API#mod_xyz_core_calendar_is_event_visible.28.29|mod_<your_plugin>_core_calendar_is_event_visible]] is returning false.
* The timesort value is more than 20 events into the future. The myoverview block will only load 20 events at a time in the timeline sort by dates view and 10 events at a time for each course in the sort by courses view.
* In the sort by courses view only in progress courses are shown, so if your event belongs to a past or future course then it won't display on that view.

==Themers==
The myoverview block has been created using [[dev:Templates|Templates]] to allow you to apply custom styling and markup for your theme. The existing styling is heavily based on Bootstrap 4 with an effort to keep custom CSS as small as possible so any changes you make to theme Bootstrap should apply nicely to the myoverview block.

There are examples of how the templates have been overridden for the Clean theme located in theme/bootstrapbase/templates/block_myoverview/ for reference.

Block myoverview

2017-05-12T02:46:58Z

Ryanwyllie: /* Themers */

==Overview==
The myoverview block was designed as a replacement to the existing block_course_overview. The block displays a subset of the calendar events, those that have a corresponding action for a user to complete by a given date, for example an assignment due (calendar event) would expect the student to submit their answer by the given date (action). The intention is for the content of the block to show the logged in user an ordered list of actions they need to complete. As each item is completed it should be removed from the list.

===What is a calendar event action?===
A calendar event action represents the action a user must take to satisfy the event. The actions should be discrete and finite. Each action is made up of 4 properties:
; name : A human readable name for the action, for example "add submission"
; url : A URL to direct the user to the page in which they can complete the action
; item count : How many items are required for this action, for example it may be a count of the number of assignments that need grading for a teacher
; actionable : Represents if the action can currently be actioned by the user. A true value means it is currently actionable and a false values means it will be actionable some time in the future

==Plugin developers==
===How do you get events to show in block_myoverview?===
Note: Due to the limitations of the calendar event data structure we only support module plugins (plugins in /mod/) in block_myoverview.

In order for your events to show in this block they will need to be [[dev:Calendar_API#Action_events|action events]]. That means they must have a few specific properties:
* The "type" property must be set to CALENDAR_EVENT_TYPE_ACTION to indicate that this calendar event is intended to be accompanied by an action
* The "timesort" property must be set to a timestamp. This value represents the time by which the user must complete the action. It is used for sorting the events and grouping them into time blocks ('Today', 'Next 7 days' etc)
* The "modulename" property must be the name of your module on disk, e.g. mod/lesson/ has "modulename" set to "lesson"

Once your events are being created with required properties you'll need to add the [[dev:Calendar_API#mod_xyz_core_calendar_provide_event_action.28.29|mod_<plugin>_core_calendar_provide_event_action callback]] to provide the appropriate action for the logged in user for a given event.

===How do you get events from your non-module plugins to show in block_myoverview?===
Unfortunately this isn't currently supported. Only plugins in the 'mod/' directory are supported due to limitations of the current calendar data structure.

===How do you stop your event from showing in block_myoverview once the user has completed the action?===
You simply return null from your [[dev:Calendar_API#mod_xyz_core_calendar_provide_event_action.28.29|mod_<plugin>_core_calendar_provide_event_action callback]] once the user satisfies the criteria for completion of the action. The action events are given to your [[dev:Calendar_API#mod_xyz_core_calendar_provide_event_action.28.29|mod_<plugin>_core_calendar_provide_event_action callback]] each time they are request by block_myoverview so the user will only see the current state of each action they must complete. When the user has nothing left to do (indicated by returning null) it is removed from the list.

Action events that don't have a corresponding action will still be displayed in the calendar.

Note: There is no need to check in your callback that the user can see your activity or that they are enrolled in the course. These checks are done prior to providing the event to the callback. By the time you see the event in the callback you know that the user at least has permission to view your activity.

===How do you get events to show in the calendar but not in block_myoverview?===
You can still create an event with it's "type" property set to CALENDAR_EVENT_TYPE_STANDARD. Anything other than CALENDAR_EVENT_TYPE_ACTION will be ignored by block_myoverview.

===How do you hide an action event from both the calendar and block_myoverview?===
You can use the [[dev:Calendar_API#mod_xyz_core_calendar_is_event_visible.28.29|mod_<plugin>_core_calendar_is_event_visible]] to control the visibility of action events globally throughout Moodle. If you return false from this callback then the action event will no appear in neither the calendar nor block_myoverview. If you do not implement this callback then it is assumed that the event should be visible.

Typically, this callback would be used to check that the user has sufficient permissions to ever be able perform the action. For example, the assign activity ensures that a user without the appropriate role shouldn't see the grading event (i.e. a student shouldn't see the teacher's grading event).

This callback is called after the [[dev:Calendar_API#mod_xyz_core_calendar_provide_event_action.28.29|mod_<plugin>_core_calendar_provide_event_action callback]] which means it has access to the properties generated in that callback. In addition, there is a default rule that any action event with an "itemcount" set to zero is deemed not to be visible.

===How do you display the item count for an action in block_myoverview?===
By default the item count will not be displayed in block myoverview. However if you would like to explicitly change this behaviour then you can implement the [[dev:Calendar_API#mod_xyz_core_calendar_event_action_shows_item_count.28.29|mod_<plugin>_core_calendar_event_action_shows_item_count]]. If the result of that callback is true then the item count will be displayed in the block UI. Some times you may want to show the number of items left to action, for example the assign grading event for teachers shows them the count of the number of submissions left to grade.

===Why isn't the action name a URL when it shows in block_myoverview?===
Whether the action name (i.e. the "name" property on your action) is rendered as plain text or as a hyperlink is determined by the "actionable" property of the action. If "actionable" is true then it means the user can complete the action now, so we render the hyperlink to take them to the place to complete it. However if "actionable" is false then it means the user is unable to complete the action now but will be able to some time in the future, so the action name is rendered in plain text.

===Why isn't your event being given to your *_provide_event_action callback?===
Some common reasons that you may not see your events in your callback:
* The callback is not located in lib.php within your module's directory. It should be in mod/<your_plugin>/lib.php.
* The callback function is not named correctly, it should be [[dev:Calendar_API#mod_xyz_core_calendar_provide_event_action.28.29|mod_<your_plugin>_core_calendar_provide_event_action]]. For example, the callback for the assign module would be named mod_assign_core_calendar_provide_event_action.
* The incorrect modulename property is being set on your calendar event.
* The calendar event is not being set to type CALENDAR_EVENT_TYPE_ACTION.
* The calendar event does not have a timesort property set.
* The logged in user does not have the capability to view your activity.
* The logged in user is not enrolled in the course that has your activity.
* The eventtype property for your event is a completion event but completion is not enabled in the course.

===Why is your event not showing in block_myoverview even though it's being passed into your *_provide_event_action callback?===
Some common reasons that you may not see events in block_myoverview even though they are hitting your callback are:
* Your callback is returning null, which indicates there is no action for the user.
* Your callback is returning an item count of zero, which indicates there is no action for the user.
* Your [[dev:Calendar_API#mod_xyz_core_calendar_is_event_visible.28.29|mod_<your_plugin>_core_calendar_is_event_visible]] is returning false.
* The timesort value is more than 20 events into the future. The myoverview block will only load 20 events at a time in the timeline sort by dates view and 10 events at a time for each course in the sort by courses view.
* In the sort by courses view only in progress courses are shown, so if your event belongs to a past or future course then it won't display on that view.

==Themers==
The myoverview block has been created using [[dev:Templates|Templates]] to allow you to apply custom styling and markup your theme. The existing styling is heavily based on Bootstrap 4 with an effort to keep custom CSS as small as possible so any changes you make to theme Bootstrap should apply nicely to the myoverview block.

There are examples of how the templates have been overridden for the Clean theme located in theme/bootstrapbase/templates/block_myoverview/ for reference.

Block myoverview

2017-05-11T04:02:12Z

Ryanwyllie:

Block myoverview

2017-05-10T07:57:36Z

Ryanwyllie:

Templates

2017-05-10T02:19:52Z

Ryanwyllie: /* What other helpers can I use? */

{{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>{{> 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.
* <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 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.
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', source, javascript);
}).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
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.

=== {{# userdate }} ===
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 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!).

==== Using the string helper (recommended) ====
<code>
// Assuming we had a context variable named "time" set to 1293876000.
{{#userdate}} {{time}}, {{#str}} strftimedate {{/str}} {{/userdate}}
</code>
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".

==== Using context variables ====
<code>
// Assuming we had a context variable named "time" set to 1293876000.
{{#userdate}} {{time}}, %A, %d %B %Y, %I:%M %p {{/userdate}}
</code>
Will produce "Saturday, 01 January 2011, 10:00 AM"

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

==== Plain text ====
<code>
{{#shortentext}} 30, long text without any tags blah de blah blah blah what {{/shortentext}}
</code>
Will produce:
<code>
long text without any tags ...
</code>

==== HTML text ====
<code>
{{#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}}
</code>
Will produce:
<code>
<div class='frog'><p><blockquote>Long text with tags that ...</blockquote></p></div>
</code>

==== Multi-byte text ====
<code>
{{#shortentext}} 6, 𠮟𠮟𠮟𠮟𠮟𠮟𠮟𠮟𠮟𠮟𠮟𠮟 {{/shortentext}}
</code>
Will produce:
<code>
𠮟𠮟𠮟...
</code>

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

Templates

2017-05-09T07:38:43Z

Ryanwyllie: /* What other helpers can I use? */

{{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>{{> 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.
* <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 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.
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', source, javascript);
}).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
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.

=== {{# userdate }} ===
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 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!).

==== Using the string helper (recommended) ====
<code>
// Assuming we had a context variable named "time" set to 1293876000.
{{#userdate}} {{time}}, {{#str}} strftimedate {{/str}} {{/userdate}}
</code>
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".

==== Using context variables ====
<code>
// Assuming we had a context variable named "time" set to 1293876000.
{{#userdate}} {{time}}, %A, %d %B %Y, %I:%M %p {{/userdate}}
</code>
Will produce "Saturday, 01 January 2011, 10:00 AM"

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

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

AMD Modal

2017-05-09T06:26:22Z

Ryanwyllie: /* How do you write a new type of modal? */

This is currently (2017) the recommended way to create various sorts of pop-up dialogue boxes in JavaScript.

= Why should you use it? =
The AMD modal modules provide a simple interface for creating a modal within Moodle. The module will ensure all accessibility requirements are met including applying the correct aria roles, focus control, aria hiding background elements and locking keyboard navigation.

The modals will fire events for common actions that occur within the modal, e.g. show / hide, for other code to listen to and react accordingly.

Moodle ships with a couple of standard modal types for you to re-use including a simple cancel modal, a confirm (yes/no) modal and a save/cancel modal. Hopefully with more to come!

= How do you create a basic modal? =
If you'd simply like to display a modal with some simple content then all you'll need is the modal factory. The factory provides a create function that accepts some configuration for your modal that the factory will use to create the modal and optionally a trigger element (the element that will open the modal when activated). The create function will return a promise that is resolved with the created modal.

The configuration is provided as an object with key/value pairs. The options are:
{| class="nicetable"
|-
! '''key'''
! '''description'''
|-
| title
| the title to display in the modal header - note: this wont render HTML
|-
| body
| the main content to be rendered in the modal body
|-
| footer
| the content to be rendered in the modal footer
|-
| type
| one of the modal types registered with the factory
|-
| large
| a boolean to indicate if the modal should be wider than the default size
|}

Example 1
<code javascript>
require(['jquery', 'core/modal_factory'], function($, ModalFactory) {
var trigger = $('#create-modal');
ModalFactory.create({
title: 'test title',
body: '<p>test body content</p>',
footer: 'test footer content',
}, trigger)
.done(function(modal) {
// Do what you want with your new modal.
});
});
</code>

The modals will also accept a promise for the body and footer content. It is expected that the promise will be resolved with two strings, the html content and any associated javascript. This allows the modal module to work natively with the templates module, such as in the example below.

Example 2
<code javascript>
require(['jquery', 'core/modal_factory', 'core/templates'], function($, ModalFactory, Templates) {
var trigger = $('#create-modal');
ModalFactory.create({
title: 'test title',
// Can include JS which is run when modal is attached to DOM.
body: Templates.render('core/modal_test_3', {}),
footer: 'test footer content',
}, trigger)
.done(function(modal) {
// Do what you want with your modal.
});
});
</code>

Since the modals aren't actually added to the DOM until they are made visible any javascript resolved with the promise is cached and only run after all of the elements are added to the DOM, so you don't have to worry about any special handling in the javascript that is being loaded from the template.

= How do you create a different type of modal? =
Moodle comes with a few specialised types of modals for common use cases. These can be created using the factory, similar to the examples above, by specifying the type of modal in the configuration provided to the create function. Each of the modal types may have different configuration options, for example the save/cancel modal doesn't allow you to set the footer content.

Example 3
<code javascript>
require(['jquery', 'core/modal_factory', 'core/templates'], function($, ModalFactory, Templates) {
var trigger = $('#create-modal');
ModalFactory.create({
type: ModalFactory.types.SAVE_CANCEL,
title: 'Modal save cancel',
body: 'This modal is a save/cancel modal',
}, trigger)
.done(function(modal) {
// Do what you want with your modal.
});
});
</code>

Each type of modal may fire additional events to allow your code to handle the new functionality being offered. See the modal_events.js module for a list of events that can be fired. For example, if you wanted to have a save/cancel modal that you did some form validation on before saving you could do something like the example below.

Example 4
<code javascript>
require(['jquery', 'core/modal_factory', 'core/modal_events', 'core/templates'],
function($, ModalFactory, ModalEvents, Templates) {

var trigger = $('#create-modal');
ModalFactory.create({
type: ModalFactory.types.SAVE_CANCEL,
title: 'Modal save cancel',
body: 'This modal is a save/cancel modal',
}, trigger)
.done(function(modal) {
modal.getRoot().on(ModalEvents.save, function(e) {
// Stop the default save button behaviour which is to close the modal.
e.preventDefault();
// Do your form validation here.
});
});
});
</code>

= How do you write a new type of modal? =
If you'd like to write a new type of modal to be re-used throughout your code you can extend the default modal implementation and make any customisations you require. In order to create a new modal type you'll need to create a new AMD module and import the core/modal module to extend. You can also optionally create a new modal template that builds upon the core/modal template. Finally, you can register your new type with the modal registry to allow you to create your new type using the modal factory.

For example, let's create a modal that opens a login form:
First we can create the HTML for out modal by including and extending the core modal template. All we need to do is override the block defined in that template with our new title, body and footer content.

Let's assume the file is <your_module>/templates/modal_login.mustache

<code>
{{< core/modal }}
{{$title}}{{#str}} login {{/str}}{{/title}}
{{$body}}
<div class="container">
<form>
<div class="form-group row">
<label for="inputEmail" class="col-sm-2 col-form-label">{{#str}} email {{/str}}</label>
<div class="col-sm-10">
<input type="email" class="form-control" id="inputEmail" placeholder="{{#str}} email {{/str}}">
</div>
</div>
<div class="form-group row">
<label for="inputPassword" class="col-sm-2 col-form-label">{{#str}} password {{/str}}</label>
<div class="col-sm-10">
<input type="password" class="form-control" id="inputPassword" placeholder="{{#str}} password {{/str}}">
</div>
</div>
</form>
</div>
{{/body}}
{{$footer}}
<button type="button" class="btn btn-primary" data-action="login">{{#str}} login {{/str}}</button>
<button type="button" class="btn btn-secondary" data-action="cancel">{{#str}} cancel {{/str}}</button>
{{/footer}}
{{/ core/modal }}
</code>

Next we can create the new AMD module for the login modal. You can extend the existing modal module which will give you all of the core modal functionality for free allowing you to focus on writing only the specific logic you need. In this example we would only need to write the logic for handling the login.

Let's assume the file is <your_module>/amd/src/modal_login.js

<code javascript>
define(['jquery', 'core/notification', 'core/custom_interaction_events', 'core/modal', 'core/modal_registry'],
function($, Notification, CustomEvents, Modal, ModalRegistry) {

var registered = false;
var SELECTORS = {
LOGIN_BUTTON: '[data-action="login"]',
CANCEL_BUTTON: '[data-action="cancel"]',
};

/**
* Constructor for the Modal.
*
* @param {object} root The root jQuery element for the modal
*/
var ModalLogin = function(root) {
Modal.call(this, root);

if (!this.getFooter().find(SELECTORS.LOGIN_BUTTON).length) {
Notification.exception({message: 'No login button found'});
}

if (!this.getFooter().find(SELECTORS.CANCEL_BUTTON).length) {
Notification.exception({message: 'No cancel button found'});
}
};

ModalLogin.TYPE = 'your_module-login';
ModalLogin.prototype = Object.create(Modal.prototype);
ModalLogin.prototype.constructor = ModalLogin;

/**
* Set up all of the event handling for the modal.
*
* @method registerEventListeners
*/
ModalLogin.prototype.registerEventListeners = function() {
// Apply parent event listeners.
Modal.prototype.registerEventListeners.call(this);

this.getModal().on(CustomEvents.events.activate, SELECTORS.LOGIN_BUTTON, function(e, data) {
// Add your logic for when the login button is clicked. This could include the form validation,
// loading animations, error handling etc.
}.bind(this));

this.getModal().on(CustomEvents.events.activate, SELECTORS.CANCEL_BUTTON, function(e, data) {
// Add your logic for when the cancel button is clicked.
}.bind(this));
};

// Automatically register with the modal registry the first time this module is imported so that you can create modals
// of this type using the modal factory.
if (!registered) {
ModalRegistry.register(ModalLogin.TYPE, ModalLogin, '<your_module>/modal_login');
registered = true;
}

return ModalLogin;
});
</code>

Once you have both your template and javascript ready to go then all you need to do is tie them into where ever you'd like to launch the modal. For the purpose of this example let's assume that we've got a page with a login button with id="login" then you might add this javascript to the page.

<code javascript>
require(['jquery', 'core/templates', 'core/modal_factory', '<your_module>/modal_login'], function($, Templates, ModalFactory, ModalLogin) {
var trigger = $('#login');

ModalFactory.create({type: ModalLogin.TYPE}, trigger);
});
</code>

My course overview improvements

2017-02-06T06:15:39Z

Ryanwyllie:

This page will detail the technical specification for the improvements to the My course overview block.

{{Infobox Project
|name = Improvements to my course overview block.
|state = Starting
|tracker = MDL-55611
|discussion = https://tracker.moodle.org/browse/UX-8
|assignee = HQ Projects Team
}}

== Summary ==

The new design for the UI for the course overview block requires the ability for Moodle to efficiently query plugins for a list of "date based" tasks for the current user.

The existing "mod print_overview" callbacks do not have sufficient functionality (no separation of fields, inefficient, incomplete, no relation to completion API, inconsistently implemented across modules) so we will have to build a new API (and deprecate mod_xx_print_overview).

== Requirements ==
https://docs.google.com/document/d/13ukTgOBdDzkKmPhfyMH81inWkbfJL5CPsyQmLBDWq5k/edit

== Technical Details ==
=== Course Overview Block ===
The course overview block will communicate exclusively with the Todo API and will present the Todo's as described in UX-8. We need to remove the old code used to render the course overview block and have it use the new APIs.

* Mustache templates:
** General template for the block (wrapping template)
*** Timeline view
**** Sort by dates (wrapping template)
***** Template for displaying single todo (rendered in list)
**** Sort by courses (wrapping template)
***** Single course section, includes list of todos similar to "sort by dates" (can maybe re-use the template for a single todo here)
** Courses view
*** Single template can probably be re-used for "in progress", "upcoming" and "completed" views, just rendered with different data
*** As above, single template for a course
* Javascript
** Module for the course overview block that handles the high level interaction (changing between timeline and courses views etc)
** Module for timeline view (maybe even have separate modules for "sort by dates" and "sort by courses"?). Handles requesting the data and rendering the templates etc.
*** Module needs to handle paginated results (view more button being clicked)
** Module for courses view that handles requesting the data and rendering the templates
*** Module needs to handle paginated results (view more button being clicked)
** Use the new pie chart we add
** User the todo api javascript module to interact with the server external API
* CSS: Style each of the templates (try to re-use the Bootstrap classes to keep this minimal)
** Style Boost theme
** Style bootstrap base theme (e.g. clean)
** Add responsive styling (need to ask the UX team for some mock ups of smaller resolutions)
* Accessibility: Add the appropriate aria attributes to each of the templates above to make the block accessible by a screen reader (more work than it seems)
* Update blocks/course_overview/block_course_overview.php "get_content" to render a template via the renderer (need to add a new function)
* Remove the existing functions being used to render the course overview (including functions in the renderer and lib.php)
* Add behat tests for the interface that covers each permutation of the view (timeline, sort by dates, courses, courseview etc)

=== Action Event API ===
This will be a new API in core to represent the concept of "action events" in Moodle, i.e. the list of items displayed in the course overview block. A action event is made up of a calendar event and an associated action for the user.

The appropriate action will need to be calculated on a per user basis, per event, and per module because of complex permission problems. E.g. a user may have an event for an assignment that they no longer have permission to view or they may have an event for an assignment that can't be started until after another module has been completed etc.

Given the intensity of some of these calculations we'll need to look into aggressively caching results and maybe even avoid doing the calculations per request.

Since we're leveraging the existing calendar events for the static data we may not need to actually persist the todos anywhere other than caching.

* Add a todo class (pretty please can we have an actual class rather than just stdClass)
** Some properties of the class:
*** unique id (context id, component, area and item id?)
*** name - the name of the thing the todo relates to (e.g. activity name)
*** url - the url of the thing the todo relates to (e.g. view.php of the module)
*** user id - the id of the user this todo belong to
*** course id - the course if that the todo relates to
*** icon url - the icon for the todo (default to the module icon)
*** start date (optional) - when the todo starts
*** end date (optional) - when the todo must be actioned by
*** item count - how many associated items there are (e.g. 4 unread posts)
*** action name - display name of the todo (e.g. "submit assignment")
*** action url - url of the todo action (e.g. link to the assignment submission page)
*** action start date - a date after which the todo can be actioned (only display the action url after this date)
*** action state - Has this been actioned? Eg, The assignment was submitted.
* Add an API class to provide access to todos (get todos for a user, get todos for a user grouped by course etc).
** Retrieval of todos needs to suppose pagination (and pagination with filters, e.g. first 10 todos in the next 7 days, second 10 todos in the next 7 days).
* Add a data access layer that abstracts away all of the SQL so that we don't have that logic everywhere (ideally).
** The API class would benefit from this.
** It can also hide the fact that we're piggy backing on the calendar events, just in case we want to change that in the future.
** It can also handle all of the caching
** Support pagination as above
* Add a standard interface for plugins to implement which will perform the required calculations and permission checks to generate the correct action based on the given user and event(s).
** The core action event API can't (and shouldn't) know every place that will want to create a action event, so we need to provide a standard way for each plugin to register itself as something that will create an action event and an interface for them to do the data manipulation required.
* Add an external API class.
** This class shouldn't contain any business logic (that all lives in the API class).
** It needs to do is call into the API class to get the appropriate todos and then create the correct renderables from the action event.
** All functions should be accessible via ajax. This is the class that the course overview block (and mobile app) will use.
* Add some renderables for the action event
** The action events should probably just be renderable / template-able themselves
** These will be used by the external API class.
* Improve performance using caching (this will be trial and error with the performance testing)
* Write unit tests for all new API functions and external API functions
* Add a javascript module to interact with the action event API (no bespoke ajax requests everywhere please)

=== Chart.js ===
* Add a new chart type (pie chart) to Moodle's chart API for use in the templates above

=== Calendar Event API ===
We'll be using the existing calendar events as the basis for the "action events". The current calendar event data structure contains most of the data that we'll need so we'll leverage that rather than create duplicate data. The API will need to be extended in order to support the more complex data requests we'll need.

* Add a display/order by date field to the calendar event table to allow us to do the date sorting (e.g. get me all events in the next 7 days) without having to do the start date + duration calculation
* Add indexes to the event table if they are missing
** display/order by date
** course id
** user id
* Add functions to the calendar event API to retrieve groups of events for a given user(s)
** currently it seems the API only loads one at a time so you need to do direct SQL in the calling code
** API should probably handle grouping of results, e.g. events for a user would be the distinct set of any course level events + group event override + user event override, where each has higher precedence than the last in the result set
** API needs to support order by new date field
** API needs to support limit and offset
* Add unit tests for new API functions

=== Calendar Block ===
* Make sure all of the action events are showing up in the calendar for the user
** Note: we *should* get this for free since we are simply creating calendar events
* Make sure we are only displaying appropriate events (ie. if there is a user override then show that for the user, not multiple).

=== Course Completion Tracking ===
* Develop a way to track completion on for all courses
** This needs to take into account all activities within the course, even ones that don't have any completion tracking enabled
* Add an API to query the completion status of a course that implements the agreed approach
* Do we need to persist the course progress somewhere or can it be calculated at run time?
** Assess performance of both options
* If we need to persist the completion then we need to add hooks into all places that can alter the completion value and update the persistence so that the data is always accurate

==== Notes ====
There are different ways of calculating the completion percentage for a course and some will be more informative than others, depending on the type of usage of the course.

Some possible options are:
* The number of completed+visible activities / The number of visible activities
* The number of completed activities / The number of activities
* The current week / the number of weeks
* The (current date - course start date) / (course end date - course start date) * Requires a course end date
* The current course grade / the required course grade (don’t expose hidden grades)
* The enrolment duration / the required enrolment duration

Because each course completion criteria requires a different calculation, one possible method is:

'''If course completion is enabled'''

for each course completion criteria - get the current and total possible values for completion

'''if all are required:'''

normalise and sum/average the values

'''if any is required'''

calculate the highest percentage completion

'''If only activity completion is enabled (and not course completion)'''

calculate the completion percentage purely on the number of activities complete / the total number of activities. (Ignoring activities with no completion - should we ignore activities the current user cannot see via access restrictions?)

'''If course completion is not enabled'''

Try and calculation the completion based purely on the course start / end date

'''To calculate the current and total values for each completion criteria:'''
* Activity completion - number of activities complete / number of activities required to be completed
* Completion of other courses - number of courses complete / number of courses required to be completed
* Enrolment Date - the current date - course start date / the enrolled until date - course start date. If there is no course start date use the enrolment start date. Max of 1.
* Enroled duration - the number of days enrolled / the number of days required to be enrolled. Max of 1.
* Unenrollment. 0 if enrolled, 1 if unenrolled.
* Course grade - current course grade / required course grade. Max of 1.
* Manual self completion. 0 if not complete, 1 if complete
* Manual completion by others. 0 if not complete, 1 if complete

=== General Moodle stuff ===
* Remove all uses of the "print_overview" callback thingo we're using through Moodle for modules to add stuff to the course overview block
* Find all of the places in Moodle that need to generate create a todo and have them create appropriate calendar events
** A list has been started here https://docs.google.com/document/d/1qfl2MEzdZcNlT2rvBSsIgWhRZsloRnsb2m5TALFn_C8/edit
* Find all of the places that may affect the status of a calendar event and update the event to make sure it is accurate (eg. editing a module, submitting an assignment, changing course dates etc)
* Add an implementation of the callback interface thingo to each module that will be creating a todo
** This implementation will take a calendar event and the user and do all of the appropriate checks to see if the user should see the todo, etc
** It will then create the appropriate todo from the calendar event and add all of the action stuff.

=== General Testing ===
* We need to do some performance testing on the overview with a site that has thousands of events and hundreds of courses to ensure that everything renders in a timely manner.

My course overview improvements

2016-12-13T03:08:53Z

Ryanwyllie:

This page will detail the technical specification for the improvements to the My course overview block.

{{Infobox Project
|name = Improvements to my course overview block.
|state = Starting
|tracker = MDL-55611
|discussion = https://tracker.moodle.org/browse/UX-8
|assignee = HQ Projects Team
}}

== Summary ==

The new design for the UI for the course overview block requires the ability for Moodle to efficiently query plugins for a list of "date based" tasks for the current user.

The existing "mod print_overview" callbacks do not have sufficient functionality (no separation of fields, inefficient, incomplete, no relation to completion API, inconsistently implemented across modules) so we will have to build a new API (and deprecate mod_xx_print_overview).

== Requirements ==

=== Course Overview Block ===
The course overview block will communicate exclusively with the Todo API and will present the Todo's as described in UX-8. We need to remove the old code used to render the course overview block and have it use the new APIs.

* Mustache templates:
** General template for the block (wrapping template)
*** Timeline view
**** Sort by dates (wrapping template)
***** Template for displaying single todo (rendered in list)
**** Sort by courses (wrapping template)
***** Single course section, includes list of todos similar to "sort by dates" (can maybe re-use the template for a single todo here)
** Courses view
*** Single template can probably be re-used for "in progress", "upcoming" and "completed" views, just rendered with different data
*** As above, single template for a course
* Javascript
** Module for the course overview block that handles the high level interaction (changing between timeline and courses views etc)
** Module for timeline view (maybe even have separate modules for "sort by dates" and "sort by courses"?). Handles requesting the data and rendering the templates etc.
*** Module needs to handle paginated results (view more button being clicked)
** Module for courses view that handles requesting the data and rendering the templates
*** Module needs to handle paginated results (view more button being clicked)
** Use the new pie chart we add
** User the todo api javascript module to interact with the server external API
* CSS: Style each of the templates (try to re-use the Bootstrap classes to keep this minimal)
** Style Boost theme
** Style bootstrap base theme (e.g. clean)
** Add responsive styling (need to ask the UX team for some mock ups of smaller resolutions)
* Accessibility: Add the appropriate aria attributes to each of the templates above to make the block accessible by a screen reader (more work than it seems)
* Update blocks/course_overview/block_course_overview.php "get_content" to render a template via the renderer (need to add a new function)
* Remove the existing functions being used to render the course overview (including functions in the renderer and lib.php)
* Add behat tests for the interface that covers each permutation of the view (timeline, sort by dates, courses, courseview etc)

=== Todo API ===
This will be a new API in core to represent the concept of "todos" in Moodle, i.e. the list of items displayed in the course overview block. A todo is made up of a calendar event and an associated action for the user.

The appropriate action will need to be calculated on a per user basis, per event, and per module because of complex permission problems. E.g. a user may have an event for an assignment that they no longer have permission to view or they may have an event for an assignment that can't be started until after another module has been completed etc.

Given the intensity of some of these calculations we'll need to look into aggressively caching results and maybe even avoid doing the calculations per request.

Since we're leveraging the existing calendar events for the static data we may not need to actually persist the todos anywhere other than caching.

* Add a todo class (pretty please can we have an actual class rather than just stdClass)
** Some properties of the class:
*** unique id (context id, component, area and item id?)
*** name - the name of the thing the todo relates to (e.g. activity name)
*** url - the url of the thing the todo relates to (e.g. view.php of the module)
*** user id - the id of the user this todo belong to
*** course id - the course if that the todo relates to
*** icon url - the icon for the todo (default to the module icon)
*** start date (optional) - when the todo starts
*** end date (optional) - when the todo must be actioned by
*** item count - how many associated items there are (e.g. 4 unread posts)
*** action name - display name of the todo (e.g. "submit assignment")
*** action url - url of the todo action (e.g. link to the assignment submission page)
*** action start date - a date after which the todo can be actioned (only display the action url after this date)
* Add an API class to provide access to todos (get todos for a user, get todos for a user grouped by course etc).
** Retrieval of todos needs to suppose pagination (and pagination with filters, e.g. first 10 todos in the next 7 days, second 10 todos in the next 7 days).
* Add a data access layer that abstracts away all of the SQL so that we don't have that logic everywhere (ideally).
** The API class would benefit from this.
** It can also hide the fact that we're piggy backing on the calendar events, just in case we want to change that in the future.
** It can also handle all of the caching
** Support pagination as above
* Add a standard interface for plugins to implement which will perform the required calculations and permission checks to generate the correct action based on the given user and event(s).
** The core todo API can't (and shouldn't) know every place that will want to create a todo, so we need to provide a standard way for each plugin to register itself as something that will create a todo and an interface for them to do the data manipulation required.
* Add an external API class.
** This class shouldn't contain any business logic (that all lives in the API class).
** It needs to do is call into the API class to get the appropriate todos and then create the correct renderables from the todo.
** All functions should be accessible via ajax. This is the class that the course overview block (and mobile app) will use.
* Add some renderables for the todo
** The todos should probably just be renderable / template-able themselves
** These will be used by the external API class.
* Improve performance using caching (this will be trial and error with the performance testing)
* Write unit tests for all new API functions and external API functions
* Add a javascript module to interact with the Todo API (no bespoke ajax requests everywhere please)

=== Chart.js ===
* Add a new chart type (pie chart) to Moodle's chart API for use in the templates above

=== Calendar Event API ===
We'll be using the existing calendar events as the basis for the "todos". The current calendar event data structure contains most of the data that we'll need so we'll leverage that rather than create duplicate data. The API will need to be extended in order to support the more complex data requests we'll need.

* Add a display/order by date field to the calendar event table to allow us to do the date sorting (e.g. get me all events in the next 7 days) without having to do the start date + duration calculation
* Add indexes to the event table if they are missing
** display/order by date
** course id
** user id
* Add functions to the calendar event API to retrieve groups of events for a given user(s)
** currently it seems the API only loads one at a time so you need to do direct SQL in the calling code
** API should probably handle grouping of results, e.g. events for a user would be the distinct set of any course level events + group event override + user event override, where each has higher precedence than the last in the result set
** API needs to support order by new date field
** API needs to support limit and offset
* Add unit tests for new API functions

=== Calendar Block ===
* Make sure all of the todos are showing up in the calendar for the user
** Note: we *should* get this for free since we are simply creating calendar events

=== Course Completion Tracking ===
* Develop a way to track completion on for all courses
** This needs to take into account all activities within the course, even ones that don't have any completion tracking enabled
* Add an API to query the completion status of a course that implements the agreed approach
* Do we need to persist the course progress somewhere or can it be calculated at run time?
** Assess performance of both options
* If we need to persist the completion then we need to add hooks into all places that can alter the completion value and update the persistence so that the data is always accurate

=== General Moodle stuff ===
* Remove all uses of the "print_overview" callback thingo we're using through Moodle for modules to add stuff to the course overview block
* Find all of the places in Moodle that need to generate create a todo and have them create appropriate calendar events
** A list has been started here https://docs.google.com/document/d/1qfl2MEzdZcNlT2rvBSsIgWhRZsloRnsb2m5TALFn_C8/edit
* Find all of the places that may affect the status of a calendar event and update the event to make sure it is accurate (eg. editing a module, submitting an assignment, changing course dates etc)
* Add an implementation of the callback interface thingo to each module that will be creating a todo
** This implementation will take a calendar event and the user and do all of the appropriate checks to see if the user should see the todo, etc
** It will then create the appropriate todo from the calendar event and add all of the action stuff.

=== General Testing ===
* We need to do some performance testing on the overview with a site that has thousands of events and hundreds of courses to ensure that everything renders in a timely manner.

=== Proof Of Concept Code ===
I've knocked together a little proof of concept type branch that does a skeleton implementation of some of this stuff. You can find it here https://github.com/moodle/moodle/compare/e6cb76d...ryanwyllie:todos_poc_2

Please review it and add any comments or what ever.

== Questions for the UX team ==
* How many items to display in "Next 7 days"? Is there a limit, or we always show all of the items?
* In the prototype 6c (the one that we are supposed to develop from) the todo disappears from the list when it is actioned. Is this the correct behaviour? What happens to the corresponding event in the calendar? Does that also get removed?
* What do we show when a todo is only available for a certain duration? E.g. chat where it's open for only 3 days. Only having the end date seems weird in that case.
* Is the list of courses paginated in the courses view? Is there a "More" button to load more courses?
* What happens with courses which do not have a start date, and end date? Will they show in "In progress" for as long as I am enrolled in them? Note that if I unenrol from the course, I will lose access to it.
* Are all the three tabs (in progress, upcoming, completed) always shown, even if they are empty?
* When an activity combines both a ''due date'' and an ''expected completed on'' date (e.g. assignment module with completion), what is the date of the task?

My course overview improvements

2016-12-13T01:22:27Z

Ryanwyllie:

This page will detail the technical specification for the improvements to the My course overview block.

{{Infobox Project
|name = Improvements to my course overview block.
|state = Starting
|tracker = MDL-55611
|discussion = https://tracker.moodle.org/browse/UX-8
|assignee = HQ Projects Team
}}

== Summary ==

The new design for the UI for the course overview block requires the ability for Moodle to efficiently query plugins for a list of "date based" tasks for the current user.

The existing "mod print_overview" callbacks do not have sufficient functionality (no separation of fields, inefficient, incomplete, no relation to completion API, inconsistently implemented across modules) so we will have to build a new API (and deprecate mod_xx_print_overview).

== Requirements ==

=== Course Overview Block ===
The course overview block will communicate exclusively with the Todo API and will present the Todo's as described in UX-8. We need to remove the old code used to render the course overview block and have it use the new APIs.

* Mustache templates:
** General template for the block (wrapping template)
*** Timeline view
**** Sort by dates (wrapping template)
***** Template for displaying single todo (rendered in list)
**** Sort by courses (wrapping template)
***** Single course section, includes list of todos similar to "sort by dates" (can maybe re-use the template for a single todo here)
** Courses view
*** Single template can probably be re-used for "in progress", "upcoming" and "completed" views, just rendered with different data
*** As above, single template for a course
* Javascript
** Add a module to interact with the Todo API (no bespoke ajax requests everywhere please)
** Module for the course overview block that handles the high level interaction (changing between timeline and courses views etc)
** Module for timeline view (maybe even have separate modules for "sort by dates" and "sort by courses"?). Handles requesting the data and rendering the templates etc.
*** Module needs to handle paginated results (view more button being clicked)
** Module for courses view that handles requesting the data and rendering the templates
*** Module needs to handle paginated results (view more button being clicked)
** Use the new pie chart we add
* CSS: Style each of the templates (try to re-use the Bootstrap classes to keep this minimal)
** Style Boost theme
** Style bootstrap base theme (e.g. clean)
** Add responsive styling (need to ask the UX team for some mock ups of smaller resolutions)
* Accessibility: Add the appropriate aria attributes to each of the templates above to make the block accessible by a screen reader (more work than it seems)
* Update blocks/course_overview/block_course_overview.php "get_content" to render a template via the renderer (need to add a new function)
* Remove the existing functions being used to render the course overview (including functions in the renderer and lib.php)
* Add behat tests for the interface that covers each permutation of the view (timeline, sort by dates, courses, courseview etc)

=== Todo API ===
This will be a new API in core to represent the concept of "todos" in Moodle, i.e. the list of items displayed in the course overview block. A todo is made up of a calendar event and an associated action for the user.

The appropriate action will need to be calculated on a per user basis, per event, and per module because of complex permission problems. E.g. a user may have an event for an assignment that they no longer have permission to view or they may have an event for an assignment that can't be started until after another module has been completed etc.

Given the intensity of some of these calculations we'll need to look into aggressively caching results and maybe even avoid doing the calculations per request.

Since we're leveraging the existing calendar events for the static data we may not need to actually persist the todos anywhere other than caching.

* Add a todo class (pretty please can we have an actual class rather than just stdClass)
** Some properties of the class:
*** unique id (context id, component, area and item id?)
*** name - the name of the thing the todo relates to (e.g. activity name)
*** url - the url of the thing the todo relates to (e.g. view.php of the module)
*** user id - the id of the user this todo belong to
*** course id - the course if that the todo relates to
*** icon url - the icon for the todo (default to the module icon)
*** start date (optional) - when the todo starts
*** end date (optional) - when the todo must be actioned by
*** item count - how many associated items there are (e.g. 4 unread posts)
*** action name - display name of the todo (e.g. "submit assignment")
*** action url - url of the todo action (e.g. link to the assignment submission page)
*** action start date - a date after which the todo can be actioned (only display the action url after this date)
* Add an API class to provide access to todos (get todos for a user, get todos for a user grouped by course etc).
** Retrieval of todos needs to suppose pagination (and pagination with filters, e.g. first 10 todos in the next 7 days, second 10 todos in the next 7 days).
* Add a data access layer that abstracts away all of the SQL so that we don't have that logic everywhere (ideally).
** The API class would benefit from this.
** It can also hide the fact that we're piggy backing on the calendar events, just in case we want to change that in the future.
** It can also handle all of the caching
** Support pagination as above
* Add a standard interface for plugins to implement which will perform the required calculations and permission checks to generate the correct action based on the given user and event(s).
** The core todo API can't (and shouldn't) know every place that will want to create a todo, so we need to provide a standard way for each plugin to register itself as something that will create a todo and an interface for them to do the data manipulation required.
* Add an external API class.
** This class shouldn't contain any business logic (that all lives in the API class).
** It needs to do is call into the API class to get the appropriate todos and then create the correct renderables from the todo.
** All functions should be accessible via ajax. This is the class that the course overview block (and mobile app) will use.
* Add some renderables for the todo
** The todos should probably just be renderable / template-able themselves
** These will be used by the external API class.
* Improve performance using caching (this will be trial and error with the performance testing)
* Write unit tests for all new API functions and external API functions

=== Chart.js ===
* Add a new chart type (pie chart) to Moodle's chart API for use in the templates above

=== Calendar Event API ===
We'll be using the existing calendar events as the basis for the "todos". The current calendar event data structure contains most of the data that we'll need so we'll leverage that rather than create duplicate data. The API will need to be extended in order to support the more complex data requests we'll need.

* Add a display/order by date field to the calendar event table to allow us to do the date sorting (e.g. get me all events in the next 7 days) without having to do the start date + duration calculation
* Add indexes to the event table if they are missing
** display/order by date
** course id
** user id
* Add functions to the calendar event API to retrieve groups of events for a given user(s)
** currently it seems the API only loads one at a time so you need to do direct SQL in the calling code
** API should probably handle grouping of results, e.g. events for a user would be the distinct set of any course level events + group event override + user event override, where each has higher precedence than the last in the result set
** API needs to support order by new date field
** API needs to support limit and offset
* Add unit tests for new API functions

=== Calendar Block ===
* Make sure all of the todos are showing up in the calendar for the user
** Note: we *should* get this for free since we are simply creating calendar events

=== Course Completion Tracking ===
* Develop a way to track completion on for all courses
** This needs to take into account all activities within the course, even ones that don't have any completion tracking enabled
* Add an API to query the completion status of a course that implements the agreed approach
* Do we need to persist the course progress somewhere or can it be calculated at run time?
** Assess performance of both options
* If we need to persist the completion then we need to add hooks into all places that can alter the completion value and update the persistence so that the data is always accurate

=== General Moodle stuff ===
* Remove all uses of the "print_overview" callback thingo we're using through Moodle for modules to add stuff to the course overview block
* Find all of the places in Moodle that need to generate create a todo and have them create appropriate calendar events
** A list has been started here https://docs.google.com/document/d/1qfl2MEzdZcNlT2rvBSsIgWhRZsloRnsb2m5TALFn_C8/edit
* Find all of the places that may affect the status of a calendar event and update the event to make sure it is accurate (eg. editing a module, submitting an assignment, changing course dates etc)
* Add an implementation of the callback interface thingo to each module that will be creating a todo
** This implementation will take a calendar event and the user and do all of the appropriate checks to see if the user should see the todo, etc
** It will then create the appropriate todo from the calendar event and add all of the action stuff.

=== General Testing ===
* We need to do some performance testing on the overview with a site that has thousands of events and hundreds of courses to ensure that everything renders in a timely manner.

=== Proof Of Concept Code ===
I've knocked together a little proof of concept type branch that does a skeleton implementation of some of this stuff. You can find it here https://github.com/moodle/moodle/compare/e6cb76d...ryanwyllie:todos_poc_2

Please review it and add any comments or what ever.

== Questions for the UX team ==
* How many items to display in "Next 7 days"? Is there a limit, or we always show all of the items?
* In the prototype 6c (the one that we are supposed to develop from) the todo disappears from the list when it is actioned. Is this the correct behaviour? What happens to the corresponding event in the calendar? Does that also get removed?
* What do we show when a todo is only available for a certain duration? E.g. chat where it's open for only 3 days. Only having the end date seems weird in that case.
* Is the list of courses paginated in the courses view? Is there a "More" button to load more courses?
* What happens with courses which do not have a start date, and end date? Will they show in "In progress" for as long as I am enrolled in them? Note that if I unenrol from the course, I will lose access to it.
* Are all the three tabs (in progress, upcoming, completed) always shown, even if they are empty?

My course overview improvements

2016-12-13T01:18:51Z

Ryanwyllie:

This page will detail the technical specification for the improvements to the My course overview block.

{{Infobox Project
|name = Improvements to my course overview block.
|state = Starting
|tracker = MDL-55611
|discussion = https://tracker.moodle.org/browse/UX-8
|assignee = HQ Projects Team
}}

== Summary ==

The new design for the UI for the course overview block requires the ability for Moodle to efficiently query plugins for a list of "date based" tasks for the current user.

The existing "mod print_overview" callbacks do not have sufficient functionality (no separation of fields, inefficient, incomplete, no relation to completion API, inconsistently implemented across modules) so we will have to build a new API (and deprecate mod_xx_print_overview).

== Requirements ==

=== Course Overview Block ===
The course overview block will communicate exclusively with the Todo API and will present the Todo's as described in UX-8. We need to remove the old code used to render the course overview block and have it use the new APIs.

* Mustache templates:
** General template for the block (wrapping template)
*** Timeline view
**** Sort by dates (wrapping template)
***** Template for displaying single todo (rendered in list)
**** Sort by courses (wrapping template)
***** Single course section, includes list of todos similar to "sort by dates" (can maybe re-use the template for a single todo here)
** Courses view
*** Single template can probably be re-used for "in progress", "upcoming" and "completed" views, just rendered with different data
*** As above, single template for a course
* Javascript
** Add a module to interact with the Todo API (no bespoke ajax requests everywhere please)
** Module for the course overview block that handles the high level interaction (changing between timeline and courses views etc)
** Module for timeline view (maybe even have separate modules for "sort by dates" and "sort by courses"?). Handles requesting the data and rendering the templates etc.
*** Module needs to handle paginated results (view more button being clicked)
** Module for courses view that handles requesting the data and rendering the templates
*** Module needs to handle paginated results (view more button being clicked)
** Use the new pie chart we add
* CSS: Style each of the templates (try to re-use the Bootstrap classes to keep this minimal)
** Style Boost theme
** Style bootstrap base theme (e.g. clean)
** Add responsive styling (need to ask the UX team for some mock ups of smaller resolutions)
* Accessibility: Add the appropriate aria attributes to each of the templates above to make the block accessible by a screen reader (more work than it seems)
* Update blocks/course_overview/block_course_overview.php "get_content" to render a template via the renderer (need to add a new function)
* Remove the existing functions being used to render the course overview (including functions in the renderer and lib.php)
* Add behat tests for the interface that covers each permutation of the view (timeline, sort by dates, courses, courseview etc)

=== Todo API ===
This will be a new API in core to represent the concept of "todos" in Moodle, i.e. the list of items displayed in the course overview block. A todo is made up of a calendar event and an associated action for the user.

The appropriate action will need to be calculated on a per user basis, per event, and per module because of complex permission problems. E.g. a user may have an event for an assignment that they no longer have permission to view or they may have an event for an assignment that can't be started until after another module has been completed etc.

Given the intensity of some of these calculations we'll need to look into aggressively caching results and maybe even avoid doing the calculations per request.

Since we're leveraging the existing calendar events for the static data we may not need to actually persist the todos anywhere other than caching.

* Add a todo class (pretty please can we have an actual class rather than just stdClass)
** Some properties of the class:
*** unique id (context id, component, area and item id?)
*** name - the name of the thing the todo relates to (e.g. activity name)
*** url - the url of the thing the todo relates to (e.g. view.php of the module)
*** user id - the id of the user this todo belong to
*** course id - the course if that the todo relates to
*** icon url - the icon for the todo (default to the module icon)
*** start date (optional) - when the todo starts
*** end date (optional) - when the todo must be actioned by
*** item count - how many associated items there are (e.g. 4 unread posts)
*** action name - display name of the todo (e.g. "submit assignment")
*** action url - url of the todo action (e.g. link to the assignment submission page)
*** action start date - a date after which the todo can be actioned (only display the action url after this date)
* Add an API class to provide access to todos (get todos for a user, get todos for a user grouped by course etc).
** Retrieval of todos needs to suppose pagination (and pagination with filters, e.g. first 10 todos in the next 7 days, second 10 todos in the next 7 days).
* Add a data access layer that abstracts away all of the SQL so that we don't have that logic everywhere (ideally).
** The API class would benefit from this.
** It can also hide the fact that we're piggy backing on the calendar events, just in case we want to change that in the future.
** It can also handle all of the caching
** Support pagination as above
* Add a standard interface for plugins to implement which will perform the required calculations and permission checks to generate the correct action based on the given user and event(s).
** The core todo API can't (and shouldn't) know every place that will want to create a todo, so we need to provide a standard way for each plugin to register itself as something that will create a todo and an interface for them to do the data manipulation required.
* Add an external API class.
** This class shouldn't contain any business logic (that all lives in the API class).
** It needs to do is call into the API class to get the appropriate todos and then create the correct renderables from the todo.
** All functions should be accessible via ajax. This is the class that the course overview block (and mobile app) will use.
* Add some renderables for the todo
** The todos should probably just be renderable / template-able themselves
** These will be used by the external API class.
* Improve performance using caching (this will be trial and error with the performance testing)
* Write unit tests for all new API functions and external API functions

=== Chart.js ===
* Add a new chart type (pie chart) to Moodle's chart API for use in the templates above

=== Calendar Event API ===
We'll be using the existing calendar events as the basis for the "todos". The current calendar event data structure contains most of the data that we'll need so we'll leverage that rather than create duplicate data. The API will need to be extended in order to support the more complex data requests we'll need.

* Add a display/order by date field to the calendar event table to allow us to do the date sorting (e.g. get me all events in the next 7 days) without having to do the start date + duration calculation
* Add indexes to the event table if they are missing
** display/order by date
** course id
** user id
* Add functions to the calendar event API to retrieve groups of events for a given user(s)
** currently it seems the API only loads one at a time so you need to do direct SQL in the calling code
** API should probably handle grouping of results, e.g. events for a user would be the distinct set of any course level events + group event override + user event override, where each has higher precedence than the last in the result set
** API needs to support order by new date field
** API needs to support limit and offset
* Add unit tests for new API functions

=== Calendar Block ===
* Make sure all of the todos are showing up in the calendar for the user
** Note: we *should* get this for free since we are simply creating calendar events

=== Course Completion Tracking ===
* Develop a way to track completion on for all courses
** This needs to take into account all activities within the course, even ones that don't have any completion tracking enabled
* Add an API to query the completion status of a course that implements the agreed approach
* Do we need to persist the course progress somewhere or can it be calculated at run time?
** Assess performance of both options
* If we need to persist the completion then we need to add hooks into all places that can alter the completion value and update the persistence so that the data is always accurate

=== General Moodle stuff ===
* Remove all uses of the "print_overview" callback thingo we're using through Moodle for modules to add stuff to the course overview block
* Find all of the places in Moodle that need to generate create a todo and have them create appropriate calendar events
** A list has been started here https://docs.google.com/document/d/1qfl2MEzdZcNlT2rvBSsIgWhRZsloRnsb2m5TALFn_C8/edit
* Find all of the places that may affect the status of a calendar event and update the event to make sure it is accurate (eg. editing a module, submitting an assignment, changing course dates etc)
* Add an implementation of the callback interface thingo to each module that will be creating a todo
** This implementation will take a calendar event and the user and do all of the appropriate checks to see if the user should see the todo, etc
** It will then create the appropriate todo from the calendar event and add all of the action stuff.

=== General Testing ===
* We need to do some performance testing on the overview with a site that has thousands of events and hundreds of courses to ensure that everything renders in a timely manner.

== Questions for the UX team ==
* How many items to display in "Next 7 days"? Is there a limit, or we always show all of the items?
* In the prototype 6c (the one that we are supposed to develop from) the todo disappears from the list when it is actioned. Is this the correct behaviour? What happens to the corresponding event in the calendar? Does that also get removed?
* What do we show when a todo is only available for a certain duration? E.g. chat where it's open for only 3 days. Only having the end date seems weird in that case.
* Is the list of courses paginated in the courses view? Is there a "More" button to load more courses?
* What happens with courses which do not have a start date, and end date? Will they show in "In progress" for as long as I am enrolled in them? Note that if I unenrol from the course, I will lose access to it.
* Are all the three tabs (in progress, upcoming, completed) always shown, even if they are empty?

Useful core Javascript modules

2016-12-02T05:23:03Z

Ryanwyllie:

{{Moodle 2.9}}

== Configuration settings (core/config) ==

Example of using config module:
<code javascript>
require(['core/config’], function(mdlcfg) {
console.log(mdlcfg.wwwroot); // outputs the wwwroot of moodle to console
});
</code>

== Language strings (core/str) ==

Example of using language strings module (retrieved via ajax, if the string is not yet loaded)
<code javascript>
require([‘core/str’], function(str) {
str.get_string('edita', 'core', stringargument).done(function(s) {
console.log(s);
}).fail(console.log(e));
});
</code>

The string will be retrieved via AJAX request on the first use and cached in browser local storage until purge caches or site upgrade

IT IS NOT RECOMMENDED to call:
<code php>
$PAGE->requires->string_for_js('edita', 'core'); // You do not need this!
</code>

Because:
* The list of strings used now needs to be maintained in 2 places
* The strings are always sent, and bloat the page size even if they are not used
* All strings fetched via the AJAX method above are cached in browser local storage anyway, so these strings will never be used 99% of the time

==Notifications (core/notification)==

Examples:
<code javascript>
require(['core/notification’], function(notification) {
notification.alert('Hello', 'Welcome to my site!', 'Continue');
});
</code>

Strings and notifications:
<code javascript>
require(['core/str', 'core/notification’], function(str, notification) {
str.get_strings([
{'key' : 'delete'},
{'key' : 'confirmdeletetag', component : 'tag'},
{'key' : 'yes'},
{'key' : 'no'},
]).done(function(s) {
notification.confirm(s[0], s[1], s[2], s[3], function() {
window.location.href = href;
});
}
).fail(notification.exception);
});
</code>

== URL module (core/url) ==

<code javascript>
require(['core/url'], function(url) {
url.fileUrl(relativeScript, slashArg);
url.relativeUrl(relativePath);
url.imageUrl(imagename, component);
});
</code>

== Tree (core/tree) ==
{{Moodle 3.1}}
If you want to add a hierarchical interface, you should use the tree module. It will handle user interaction and accessibility for you.

<code javascript>
define(['jquery', 'core/tree'], function($, Tree) {
return {
init: function() {
new Tree("css/jquery selector of the tree container");
}
};
});
</code>

Read more about the [[Tree]] module

== Modal (core/modal) ==
If you'd like to add a modal to your page the modal modules will handle all of the magic for you, all you need to bring is your content!
<code javascript>
require(['jquery', 'core/modal_factory'], function($, ModalFactory) {
var trigger = $('#create-modal');
ModalFactory.create({
title: 'test title',
body: '<p>test body content</p>',
footer: 'test footer content',
}, trigger)
.done(function(modal) {
// Do what you want with your new modal.
});
});
</code>

Read more about the [[AMD_Modal]] module

==See also==
* [[Javascript Modules]]
* [[Fragment]]

[[Category:AJAX]]
[[Category:Javascript]]

Moodle 3.2 release notes

2016-12-01T07:15:26Z

Ryanwyllie:

[[Releases]] > {{FULLPAGENAME}}

Release date: 28 November 2016 (not yet released)

{{Work in progress}}

Here is [https://tracker.moodle.org/secure/IssueNavigator!executeAdvanced.jspa?jqlQuery=project+%3D+mdl+AND+resolution+%3D+fixed+AND+fixVersion+in+%28%223.2%22%29+ORDER+BY+priority+DESC&runQuery=true&clear=true the full list of fixed issues in 3.2].

==Server requirements==

These are just the minimum supported versions. We recommend keeping all of your software up-to-date.

* Moodle upgrade: Moodle 2.7 or later (if upgrading from earlier versions, you must upgrade to 2.7.14 as a first step)
* PHP version: minimum PHP 5.6.5 (important! minimum PHP version has changed since Moodle 3.1). PHP 7.0 is supported but has some [https://docs.moodle.org/dev/Moodle_and_PHP7#Can_I_use_PHP7_yet.3F engine limitations]. PHP 7.1 will be supported when released.

=== Database requirements ===

Moodle supports the following database servers. Again, version numbers are just the minimum supported version. We recommend running the latest stable version of any software.

{| class="nicetable"
|-
! Database
! Minimum version
! Recommended
|-
| [http://www.postgresql.org/ PostgreSQL]
| 9.1
| Latest
|-
| [http://www.mysql.com/ MySQL]
| 5.5.31
| Latest
|-
| [https://mariadb.org/ MariaDB]
| 5.5.31
| Latest
|-
| [http://www.microsoft.com/en-us/server-cloud/products/sql-server/ Microsoft SQL Server]
| 2008
| Latest
|-
| [http://www.oracle.com/us/products/database/overview/index.html Oracle Database]
| 10.2
| Latest
|}

==Client requirements==

=== Browser support ===
Moodle is compatible with any standards compliant web browser. We regularly test Moodle with the following browsers:

Desktop:
* Chrome
* Firefox
* Safari
* Edge
* Internet Explorer

Mobile:
* MobileSafari
* Google Chrome

For the best experience and optimum security, we recommend that you keep your browser up to date. https://whatbrowser.org

Note: Legacy browsers with known compatibility issues with Moodle 3.2:
* Internet Explorer 10 and below
* Safari 7 and below

==Major features==

Coming soon.

=== For developers ===

* MDL-55071, MDL-55074 - New "Boost" Bootstrap 4 theme, block and navigation changes
* MDL-38158 - Introduction of Media players plugin type ([https://docs.moodle.org/dev/Media_players documentation])
* MDL-55727 - Create AMD modal module ([https://docs.moodle.org/dev/AMD_Modal documentation])
* MDL-49599 - Deprecate old boxnet v1 API
* MDL-53306 - Add hook to be executed before user login in authentication plugins
* MDL-55048 - Grunt and npm build dependencies now require node version 4 or above
* MDL-47162 - Add course id to message eventdata
* MDL-50937 - Update to JQuery 3.1
* MDL-48114 - Add Meta-Information to composer.json
* MDL-54987 - Introduce a new chart API and library ([https://docs.moodle.org/dev/Charts_API documentation])
* MDL-52127 - Linting for Javascript with ESLint
* MDL-55058 - Linting for CSS with stylelint
* MDL-55072 - Upgrades to Behat so it can work with different themes
* MDL-55141 - Add debugging option when running scheduled tasks from CLI ([https://docs.moodle.org/en/Administration_via_command_line#Scheduled_tasks documentation])
* MDL-31243 - Refactor similar SQL generation code from get_users_by_capability & get_enrolled_uses to make get_with_capability_sql
* MDL-54941 - Add filesize as a new field returned in all the Web Services returning file information
* MDL-55091 - Upgrade phpunit to 5.x
* MDL-56082 - Expose external authentication methods (loginpage_idp_list) in login block ([https://docs.moodle.org/dev/Authentication_plugins#loginpage_idp_list.28.29 documentation])

==See also==
*[[Moodle 3.1 release notes]]

[[Category:Release notes]]
[[Category:Moodle 3.2]]

[[fr:Notes de mise à jour de Moodle 3.2]]
[[es:Notas de Moodle 3.2]]

AMD Modal

2016-12-01T06:44:06Z

Ryanwyllie: /* How do you create a basic modal? */

= Why should you use it? =
The AMD modal modules provide a simple interface for creating a modal within Moodle. The module will ensure all accessibility requirements are met including applying the correct aria roles, focus control, aria hiding background elements and locking keyboard navigation.

The modals will fire events for common actions that occur within the modal, e.g. show / hide, for other code to listen to and react accordingly.

Moodle ships with a couple of standard modal types for you to re-use including a simple cancel modal, a confirm (yes/no) modal and a save/cancel modal. Hopefully with more to come!

= How do you create a basic modal? =
If you'd simply like to display a modal with some simple content then all you'll need is the modal factory. The factory provides a create function that accepts some configuration for your modal that the factory will use to create the modal and optionally a trigger element (the element that will open the modal when activated). The create function will return a promise that is resolved with the created modal.

The configuration is provided as an object with key/value pairs. The options are:
{| class="nicetable"
|-
! '''key'''
! '''description'''
|-
| title
| the title to display in the modal header - note: this wont render HTML
|-
| body
| the main content to be rendered in the modal body
|-
| footer
| the content to be rendered in the modal footer
|-
| type
| one of the modal types registered with the factory
|-
| large
| a boolean to indicate if the modal should be wider than the default size
|}

Example 1
<code javascript>
require(['jquery', 'core/modal_factory'], function($, ModalFactory) {
var trigger = $('#create-modal');
ModalFactory.create({
title: 'test title',
body: '<p>test body content</p>',
footer: 'test footer content',
}, trigger)
.done(function(modal) {
// Do what you want with your new modal.
});
});
</code>

The modals will also accept a promise for the body and footer content. It is expected that the promise will be resolved with two strings, the html content and any associated javascript. This allows the modal module to work natively with the templates module, such as in the example below.

Example 2
<code javascript>
require(['jquery', 'core/modal_factory', 'core/templates'], function($, ModalFactory, Templates) {
var trigger = $('#create-modal');
ModalFactory.create({
title: 'test title',
// Can include JS which is run when modal is attached to DOM.
body: Templates.render('core/modal_test_3', {}),
footer: 'test footer content',
}, trigger)
.done(function(modal) {
// Do what you want with your modal.
});
});
</code>

Since the modals aren't actually added to the DOM until they are made visible any javascript resolved with the promise is cached and only run after all of the elements are added to the DOM, so you don't have to worry about any special handling in the javascript that is being loaded from the template.

= How do you create a different type of modal? =
Moodle comes with a few specialised types of modals for common use cases. These can be created using the factory, similar to the examples above, by specifying the type of modal in the configuration provided to the create function. Each of the modal types may have different configuration options, for example the save/cancel modal doesn't allow you to set the footer content.

Example 3
<code javascript>
require(['jquery', 'core/modal_factory', 'core/templates'], function($, ModalFactory, Templates) {
var trigger = $('#create-modal');
ModalFactory.create({
type: ModalFactory.types.SAVE_CANCEL,
title: 'Modal save cancel',
body: 'This modal is a save/cancel modal',
}, trigger)
.done(function(modal) {
// Do what you want with your modal.
});
});
</code>

Each type of modal may fire additional events to allow your code to handle the new functionality being offered. See the modal_events.js module for a list of events that can be fired. For example, if you wanted to have a save/cancel modal that you did some form validation on before saving you could do something like the example below.

Example 4
<code javascript>
require(['jquery', 'core/modal_factory', 'core/modal_events', 'core/templates'],
function($, ModalFactory, ModalEvents, Templates) {

var trigger = $('#create-modal');
ModalFactory.create({
type: ModalFactory.types.SAVE_CANCEL,
title: 'Modal save cancel',
body: 'This modal is a save/cancel modal',
}, trigger)
.done(function(modal) {
modal.getRoot().on(ModalEvents.save, function(e) {
// Stop the default save button behaviour which is to close the modal.
e.preventDefault();
// Do your form validation here.
});
});
});
</code>

= How do you write a new type of modal? =
If you'd like to write a new type of modal to be re-used throughout your code you can extend the default modal implementation and make any customisations you require. In order to create a new modal type you'll need to create a new AMD module and import the core/modal module to extend. You can also optionally create a new modal template that builds upon the core/modal template.

For example, let's create a modal that opens a login form:
First we can create the HTML for out modal by including and extending the core modal template. All we need to do is override the block defined in that template with our new title, body and footer content.

Let's assume the file is <your_module>/templates/modal_login.mustache

<code>
{{< core/modal }}
{{$title}}{{#str}} login {{/str}}{{/title}}
{{$body}}
<div class="container">
<form>
<div class="form-group row">
<label for="inputEmail" class="col-sm-2 col-form-label">{{#str}} email {{/str}}</label>
<div class="col-sm-10">
<input type="email" class="form-control" id="inputEmail" placeholder="{{#str}} email {{/str}}">
</div>
</div>
<div class="form-group row">
<label for="inputPassword" class="col-sm-2 col-form-label">{{#str}} password {{/str}}</label>
<div class="col-sm-10">
<input type="password" class="form-control" id="inputPassword" placeholder="{{#str}} password {{/str}}">
</div>
</div>
</form>
</div>
{{/body}}
{{$footer}}
<button type="button" class="btn btn-primary" data-action="login">{{#str}} login {{/str}}</button>
<button type="button" class="btn btn-secondary" data-action="cancel">{{#str}} cancel {{/str}}</button>
{{/footer}}
{{/ core/modal }}
</code>

Next we can create the new AMD module for the login modal. You can extend the existing modal module which will give you all of the core modal functionality for free allowing you to focus on writing only the specific logic you need. In this example we would only need to write the logic for handling the login.

Let's assume the file is <your_module>/amd/src/modal_login.js

<code javascript>
define(['jquery', 'core/notification', 'core/custom_interaction_events', 'core/modal'],
function($, Notification, CustomEvents, Modal) {

var SELECTORS = {
LOGIN_BUTTON: '[data-action="login"]',
CANCEL_BUTTON: '[data-action="cancel"]',
};

/**
* Constructor for the Modal.
*
* @param {object} root The root jQuery element for the modal
*/
var ModalLogin = function(root) {
Modal.call(this, root);

if (!this.getFooter().find(SELECTORS.LOGIN_BUTTON).length) {
Notification.exception({message: 'No login button found'});
}

if (!this.getFooter().find(SELECTORS.CANCEL_BUTTON).length) {
Notification.exception({message: 'No cancel button found'});
}
};

ModalLogin.prototype = Object.create(Modal.prototype);
ModalLogin.prototype.constructor = ModalLogin;

/**
* Set up all of the event handling for the modal.
*
* @method registerEventListeners
*/
ModalLogin.prototype.registerEventListeners = function() {
// Apply parent event listeners.
Modal.prototype.registerEventListeners.call(this);

this.getModal().on(CustomEvents.events.activate, SELECTORS.LOGIN_BUTTON, function(e, data) {
// Add your logic for when the login button is clicked. This could include the form validation,
// loading animations, error handling etc.
}.bind(this));

this.getModal().on(CustomEvents.events.activate, SELECTORS.CANCEL_BUTTON, function(e, data) {
// Add your logic for when the cancel button is clicked.
}.bind(this));
};

return ModalLogin;
});
</code>

Once you have both your template and javascript ready to go then all you need to do is tie them into where ever you'd like to launch the modal. For the purpose of this example let's assume that we've got a page with a login button with id="login" then you might add this javascript to the page.

<code javascript>
require(['jquery', 'core/templates', '<your_module>/modal_login'], function($, Templates, ModalLogin) {
var button = $('#login');
var modal = null;

// Load the HTML from your login modal.
Templates.render('<your_module>/modal_login').done(function(html) {
// Create the modal with the HTML.
modal = new ModalLogin(html);
});

// Show the modal when the login button is clicked.
button.click(function() {
modal.show();
});
});
</code>

AMD Modal

2016-12-01T04:36:05Z

Ryanwyllie: Created page with "= Why should you use it? = The AMD modal modules provide a simple interface for creating a modal within Moodle. The module will ensure all accessibility requirements are met i..."

= Why should you use it? =
The AMD modal modules provide a simple interface for creating a modal within Moodle. The module will ensure all accessibility requirements are met including applying the correct aria roles, focus control, aria hiding background elements and locking keyboard navigation.

The modals will fire events for common actions that occur within the modal, e.g. show / hide, for other code to listen to and react accordingly.

Moodle ships with a couple of standard modal types for you to re-use including a simple cancel modal, a confirm (yes/no) modal and a save/cancel modal. Hopefully with more to come!

= How do you create a basic modal? =
If you'd simply like to display a modal with some simple content then all you'll need is the modal factory. The factory provides a create function that accepts some configuration for your modal that the factory will use to create the modal and optionally a trigger element (the element that will open the modal when activated). The create function will return a promise that is resolved with the created modal.

The configuration is provided as an object with key/value pairs. The options are:
title - the title to display in the modal header - note: this wont render HTML
body - the main content to be rendered in the modal body
footer - the content to be rendered in the modal footer
type - one of the modal types registered with the factory
large - a boolean to indicate if the modal should be wider than the default size

Example 1
<code javascript>
require(['jquery', 'core/modal_factory'], function($, ModalFactory) {
var trigger = $('#create-modal');
ModalFactory.create({
title: 'test title',
body: '<p>test body content</p>',
footer: 'test footer content',
}, trigger)
.done(function(modal) {
// Do what you want with your new modal.
});
});
</code>

The modals will also accept a promise for the body and footer content. It is expected that the promise will be resolved with two strings, the html content and any associated javascript. This allows the modal module to work natively with the templates module, such as in the example below.

Example 2
<code javascript>
require(['jquery', 'core/modal_factory', 'core/templates'], function($, ModalFactory, Templates) {
var trigger = $('#create-modal');
ModalFactory.create({
title: 'test title',
// Can include JS which is run when modal is attached to DOM.
body: Templates.render('core/modal_test_3', {}),
footer: 'test footer content',
}, trigger)
.done(function(modal) {
// Do what you want with your modal.
});
});
</code>

Since the modals aren't actually added to the DOM until they are made visible any javascript resolved with the promise is cached and only run after all of the elements are added to the DOM, so you don't have to worry about any special handling in the javascript that is being loaded from the template.

= How do you create a different type of modal? =
Moodle comes with a few specialised types of modals for common use cases. These can be created using the factory, similar to the examples above, by specifying the type of modal in the configuration provided to the create function. Each of the modal types may have different configuration options, for example the save/cancel modal doesn't allow you to set the footer content.

Example 3
<code javascript>
require(['jquery', 'core/modal_factory', 'core/templates'], function($, ModalFactory, Templates) {
var trigger = $('#create-modal');
ModalFactory.create({
type: ModalFactory.types.SAVE_CANCEL,
title: 'Modal save cancel',
body: 'This modal is a save/cancel modal',
}, trigger)
.done(function(modal) {
// Do what you want with your modal.
});
});
</code>

Each type of modal may fire additional events to allow your code to handle the new functionality being offered. See the modal_events.js module for a list of events that can be fired. For example, if you wanted to have a save/cancel modal that you did some form validation on before saving you could do something like the example below.

Example 4
<code javascript>
require(['jquery', 'core/modal_factory', 'core/modal_events', 'core/templates'],
function($, ModalFactory, ModalEvents, Templates) {

var trigger = $('#create-modal');
ModalFactory.create({
type: ModalFactory.types.SAVE_CANCEL,
title: 'Modal save cancel',
body: 'This modal is a save/cancel modal',
}, trigger)
.done(function(modal) {
modal.getRoot().on(ModalEvents.save, function(e) {
// Stop the default save button behaviour which is to close the modal.
e.preventDefault();
// Do your form validation here.
});
});
});
</code>

= How do you write a new type of modal? =
If you'd like to write a new type of modal to be re-used throughout your code you can extend the default modal implementation and make any customisations you require. In order to create a new modal type you'll need to create a new AMD module and import the core/modal module to extend. You can also optionally create a new modal template that builds upon the core/modal template.

For example, let's create a modal that opens a login form:
First we can create the HTML for out modal by including and extending the core modal template. All we need to do is override the block defined in that template with our new title, body and footer content.

Let's assume the file is <your_module>/templates/modal_login.mustache

<code>
{{< core/modal }}
{{$title}}{{#str}} login {{/str}}{{/title}}
{{$body}}
<div class="container">
<form>
<div class="form-group row">
<label for="inputEmail" class="col-sm-2 col-form-label">{{#str}} email {{/str}}</label>
<div class="col-sm-10">
<input type="email" class="form-control" id="inputEmail" placeholder="{{#str}} email {{/str}}">
</div>
</div>
<div class="form-group row">
<label for="inputPassword" class="col-sm-2 col-form-label">{{#str}} password {{/str}}</label>
<div class="col-sm-10">
<input type="password" class="form-control" id="inputPassword" placeholder="{{#str}} password {{/str}}">
</div>
</div>
</form>
</div>
{{/body}}
{{$footer}}
<button type="button" class="btn btn-primary" data-action="login">{{#str}} login {{/str}}</button>
<button type="button" class="btn btn-secondary" data-action="cancel">{{#str}} cancel {{/str}}</button>
{{/footer}}
{{/ core/modal }}
</code>

Next we can create the new AMD module for the login modal. You can extend the existing modal module which will give you all of the core modal functionality for free allowing you to focus on writing only the specific logic you need. In this example we would only need to write the logic for handling the login.

Let's assume the file is <your_module>/amd/src/modal_login.js

<code javascript>
define(['jquery', 'core/notification', 'core/custom_interaction_events', 'core/modal'],
function($, Notification, CustomEvents, Modal) {

var SELECTORS = {
LOGIN_BUTTON: '[data-action="login"]',
CANCEL_BUTTON: '[data-action="cancel"]',
};

/**
* Constructor for the Modal.
*
* @param {object} root The root jQuery element for the modal
*/
var ModalLogin = function(root) {
Modal.call(this, root);

if (!this.getFooter().find(SELECTORS.LOGIN_BUTTON).length) {
Notification.exception({message: 'No login button found'});
}

if (!this.getFooter().find(SELECTORS.CANCEL_BUTTON).length) {
Notification.exception({message: 'No cancel button found'});
}
};

ModalLogin.prototype = Object.create(Modal.prototype);
ModalLogin.prototype.constructor = ModalLogin;

/**
* Set up all of the event handling for the modal.
*
* @method registerEventListeners
*/
ModalLogin.prototype.registerEventListeners = function() {
// Apply parent event listeners.
Modal.prototype.registerEventListeners.call(this);

this.getModal().on(CustomEvents.events.activate, SELECTORS.LOGIN_BUTTON, function(e, data) {
// Add your logic for when the login button is clicked. This could include the form validation,
// loading animations, error handling etc.
}.bind(this));

this.getModal().on(CustomEvents.events.activate, SELECTORS.CANCEL_BUTTON, function(e, data) {
// Add your logic for when the cancel button is clicked.
}.bind(this));
};

return ModalLogin;
});
</code>

Once you have both your template and javascript ready to go then all you need to do is tie them into where ever you'd like to launch the modal. For the purpose of this example let's assume that we've got a page with a login button with id="login" then you might add this javascript to the page.

<code javascript>
require(['jquery', 'core/templates', '<your_module>/modal_login'], function($, Templates, ModalLogin) {
var button = $('#login');
var modal = null;

// Load the HTML from your login modal.
Templates.render('<your_module>/modal_login').done(function(html) {
// Create the modal with the HTML.
modal = new ModalLogin(html);
});

// Show the modal when the login button is clicked.
button.click(function() {
modal.show();
});
});
</code>

Templates

2015-09-08T05:36:34Z

Ryanwyllie:

{{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 make 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 "{{tag}}". There are a few variations of these tags that behave differently.
* <code xml>{{raiden}}</code> This is a simple variable substitution. The variable named "variable" 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 not "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 black variables defined within the template you're including. You can override the black 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 :) .

== 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(js);
});

// 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? ==
There is a string helper for loading language strings.

Example:
<code xml>
{{#str}} iscool, mod_cool, David Beckham {{/str}}
</code>
The first 2 parameters are the string id and the component name, the rest of the section is the content for the $a variable. So this example would call get_string('iscool', 'mod_cool', 'David Beckham');

Variables are allowed in the text for the $a param.
Example:
<code xml>
{{#str}} iscool, mod_cool, {{name}} {{/str}}
</code>

For strings that accept complex $a params, you can use a json object here instead:
<code xml>
{{#str}} iscool, mod_cool, { firstname: 'David', lastname: 'Beckham'}{{/str}}
</code>

There is a pix icon helper for generating pix icon tags.
Example:
<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.

Templates

2015-09-08T05:22:09Z

Ryanwyllie:

{{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 make 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 "{{tag}}". There are a few variations of these tags that behave differently.
* <code xml>{{raiden}}</code> This is a simple variable substitution. The variable named "variable" 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 not "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 black variables defined within the template you're including. You can override the black 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 :) .

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

== 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(js);
});

// 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? ==
There is a string helper for loading language strings.

Example:
<code xml>
{{#str}} iscool, mod_cool, David Beckham {{/str}}
</code>
The first 2 parameters are the string id and the component name, the rest of the section is the content for the $a variable. So this example would call get_string('iscool', 'mod_cool', 'David Beckham');

Variables are allowed in the text for the $a param.
Example:
<code xml>
{{#str}} iscool, mod_cool, {{name}} {{/str}}
</code>

For strings that accept complex $a params, you can use a json object here instead:
<code xml>
{{#str}} iscool, mod_cool, { firstname: 'David', lastname: 'Beckham'}{{/str}}
</code>

There is a pix icon helper for generating pix icon tags.
Example:
<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>

Templates

2015-08-28T08:54:16Z

Ryanwyllie: