MoodleDocs - User contributions [en]

Templates

2015-07-28T20:30:46Z

Jgilgen:

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

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.renderTemplate('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]]

String API

2015-07-28T20:08:48Z

Jgilgen: More explicit directions on how to use a substituting value

==Overview==
The String API is how you get language text strings to use in the user interface. It handles internationalisation issues, and will use a number of settings and environment variables to present the best text to every user. Moodle has a mechanism that allows a number of places to be searched (in order) to find language strings. This enables language strings to be packaged with plugins and avoids the step of having to copy the language files over to the language directory when a plugin is installed.

Moodle also provide general string functions like substr, strlen etc. for multibyte safe, string operations. It uses mbstring or iconv for UTF-8 strings and falls back to typo3.

==Basic concepts==
When it is required to lookup a string or point to a help file, two basic items of information are required.
# Name of the plugin language file in which it can be found.
# Name of the string (or the help filename). For example, get_string('editingquiz','quiz') returns "Editing quiz" in the current language.
===Adding language file to plugin===
Language support for plugin(s) is added by creating a '''lang''' subdirectory in the plugin directory. The structure of the '''lang''' directory is then the same as the "main" language directory with one exception - the help directory name should '''not''' have the ''type_'' part of the module name (this might be a bug really!).

Plugin language file name needs to start with the generic type for the plugin. For example all questiontype plugins '''must''' be prefixed '''qtype_''', all authentication plugins '''auth_'''. Moodle uses this prefix to identify the [https://docs.moodle.org/dev/Places_to_search_for_lang_strings#Defining_the_search_path.28s.29 language search path.]

Example for adding language support file for Drag & Drop optional question type
Description: Drag & Drop optional question type
Module type: qtype_
Module name: qtype_dragdrop
Language file location (English): contrib/plugins/question/type/dragdrop/lang/en/qtype_dragdrop.php

Note:
* Module names cannot have numbers in them (only A-Z, a-z and underscore). This might be an issue to consider if you are moving from an existing architecture.
===Adding name of string in language file===
Name of the string is added to a pre-defined array $string. If you want to a string "Editing Quiz" with string name "editingquiz" in Drag & Drop plugin then add the following in qtype_dragdrop.php language file.
<pre>
<?php
//string name added for 'Editing Quiz'
$string['editingquiz'] = 'Editing Quiz';
//Help string for 'Editing Quiz' (optional)
$string['editingquiz_help'] = 'Help for editing quiz';
?>
</pre>
Note:
* Help string name should be suffixed with '''_help'''. Look at [[Help strings]] for more details.

==Files==
String functions are defined in
# lib/moodlelib.php - locale related functions
# lib/textlib.class.php - general string functions (substr, strlen etc.)

==Functions and examples==
There are three main functions, used in moodle for getting/displaying the localised string, based on user preferred language.
===get_string()===
Returns a localised string for current user.

Example for displaying string "This is my plug-in" in any language that supports on your site, then you need to use the following identifier in language file (located in appropriate lang directory)
$string['plugintitle'] = 'This is my plug-in';
If you want to display this string in any supported language, then you would use this function.
echo get_string('module_pluginlangfilename', 'plugintitle');

If you want to substitute value in the language string then use '''{$a}''' for substituting value. $a is an object, string or number that can be used within translation strings. The variable has to be $a, and it has to be in single quotes. For example, if you want to display answer number in Drag & drop plugin then add
$string['answerno'] = 'Answer {$a}'; //Substituting string/integer
$string['answerno'] = 'Answer {$a->name}'; //Substituting object member
in qtype_dragdrop.php (Drag & Drop language file). And call it using
//Get string by substituting integer.
get_string('answerno', 'qtype_dragdrop', $number);
//Get string by substituting object member integer
$user->number = 10;
get_string('answerno', 'qtype_dragdrop', $user);

In Moodle 2.3 there is a new argument to this function $lazyload. Setting $lazyload to true causes get_string to return a lang_string object rather than the string itself.
$stringobject = get_string('answerno', 'qtype_dragdrop', $number, true);

The fetching of the string is then put off until the string object is first used. The object can be used by calling it's out method or by casting the object to a string, either directly e.g.
(string)$stringobject
or indirectly by using the string within another string or echoing it out e.g.
echo $stringobject;
return "<p>{$stringobject}</p>";
Note: using $lazyload and attempting to use the string as an array key will cause a fatal error as objects cannot be used as array keys.
===get_strings()===
Converts an array of string names to localised strings for a specific plugin. lazy loading is not supported in this function.
$txt = get_strings(array('enable', 'disable', 'up', 'down', 'none'), 'qtype_dragdrop');
echo $txt->up; //Display localised string for up
echo $txt->down //Display localised string for down
===print_string()===
Prints out a translated string by using '''get_string()''' function

===lang_string class===
In Moodle 2.3 a special class (lang_string) is used to create an object representation of a string request. In this case string processing doesn't occur until the object is first used. The class was created especially to aid performance in areas where strings were required to be generated but were not necessarily used. As an example the admin navigation tree when generated uses over 1500 strings, of which normally only 1/3 are ever actually printed at any time. The performance advantage is achieved by not actually processing strings that aren't being used, as such reducing the processing required for the page.

lang_string class can be used in two ways
# Setting $lazyload (forth argument of the get_string function), to true.
$string = get_string('yes', 'qtype_dragdrop', null, true);
# Direct instantiation
$string = new lang_string('yes', 'qtype_dragdrop', null, 'en');
==textlib (core_text) class==
textlib class provide pool of safe functions to operate on UTF-8 text. textlib provide set of static functions to operate on strings and gets included in setup.php

{{Moodle 2.6}}In Moodle 2.6 the textlib class was renamed to '''core_text'''.

===asort()===
Locale aware sorting, the key associations are kept, values are sorted alphabetically.
===code2utf8===
Returns the utf8 string corresponding to the unicode value
===convert===
Converts the text between different encodings. It uses iconv extension with //TRANSLIT parameter, fall back to typo3
===encode_mimeheader===
Generate a correct base64 encoded header to be used in MIME mail messages.
===entities_to_utf8===
Converts all the numeric entities &#nnnn; or &#xnnn; to UTF-8
===specialtoascii===
Converts upper unicode characters to plain ascii, the returned string may contain unconverted unicode characters.
===strlen===
Multibyte safe strlen() function, uses iconv for utf-8, falls back to typo3.
===strpos===
Find the position of the first occurrence of a substring in a string. UTF-8 ONLY safe strpos(), uses iconv.
===strrpos===
Find the position of the last occurrence of a substring in a string. UTF-8 ONLY safe strrpos(), uses iconv.
===strtolower===
Multibyte safe strtolower() function, uses mbstring, falls back to typo3.
===strtotitle===
Makes first letter of each word capital - words must be separated by spaces.
===strtoupper===
Multibyte safe strtoupper() function, uses mbstring, falls back to typo3.
===substr===
Multibyte safe substr() function, uses iconv for utf-8, falls back to typo3.
===trim_utf8_bom===
Removes the BOM from unicode string. [http://unicode.org/faq/utf_bom.html more info]
===utf8_to_entities===
Converts all Unicode chars > 127 to numeric entities &#nnnn; or &#xnnn;

==FAQ==
===When should I use a lang_string object?===
The lang_string object is designed to be used in any situation where a string may not be needed, but needs to be generated. The admin navigation tree is a good example of where lang_string objects should be used. A more practical example would be any class that requries strings that may not be printed (after all classes get renderer by renderers and who knows what they will do ;))
===When should I not use a lang_string object?===
Don't use lang_strings when you are going to use a string immediately. There is no need as it will be processed immediately and there will be no advantage, and in fact perhaps a negative hit as a class has to be instantiated for a lang_string object, however get_string won't require that.
===Limitation of lang_string===
lang_string object cannot be used as an array offset. Doing so will result in PHP throwing an error. (You can use it as an object property!)
===How to compare strings properties in two object===
collatorlib_property_comparison class can be used to compare properties of two objects

==See also==
* [[Core APIs]]
* [[Languages]]
* [[Languages/AMOS]]
* [[Places to search for lang strings]]
* [[Help strings]]

[[Category:API]]