MoodleDocs - User contributions [en]

Developer meeting July 2015

2015-07-19T23:40:57Z

Jethac: /* Agenda */

[[Developer meetings]] > July 2015 meeting notes

{| class="nicetable"
|-
| Time
| [http://www.timeanddate.com/worldclock/fixedtime.html?year=2015&month=7&day=21&hour=07&min=0&sec=0 07:00 UTC on Tuesday, 21 July 2015] [http://www.google.com/calendar/event?action=TEMPLATE&text=Moodle+General+developer+meeting&dates=20150721T070000Z/20150721T090000Z&details=&location= <span class="btn btn-info">Add to my calendar</span>]
|-
| Meeting room
| [https://www.youtube.com/watch?v=pgPBohzErr4 Live stream at YouTube]
|-
| Forum discussion
| [https://moodle.org/mod/forum/discuss.php?d=316807 Thread in GDF at moodle.org]
|-
| Chat
| [https://moodle.org/local/chatlogs/info.php Regular dev chat]
|-
| Twitter
| [https://twitter.com/search?q=%23moodledev #moodledev]
|-
| Social event page
| [https://plus.google.com/events/c63rl8n5jdjldr9slcd1tdcqmg0 Google+ page]
|-
| Meeting notes
| [https://devpad.moodle.org/p/gdm150721 devpad]
|}

== Agenda ==

* Moodle Mobile 2 - Juan Leyva
* Summary report of the recent Moodle hackfests (Dublin, Melbourne) - David Mudrák, Andrew Nicols
* Moodle Association and how it is supposed to affect the Moodle development in the future - Martin Dougiamas
* Moodle HQ's personal projects week products - HQ devs
** Improved East Asian support (ruby tags in Atto and in fullname()) - Jetha Chan
* Work in progress on Learning plans and outcomes project for Moodle 3.0 - Damyon (to be confirmed)
* ...

Please feel encouraged to raise topics you would like to present / discuss during the meeting. Contact [https://moodle.org/user/profile.php?id=1601 David Mudrák] for details.

User:Damyon Wiese/Templates

2015-03-18T09:23:51Z

Jethac: /* How do I call a template from javascript? */

= 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 are section 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>{{> 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.

== 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 [User:Damyon_Wiese/Javascript_Modules 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.
});

// 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 create a new script tag and append 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 words 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 words 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);
retrn self::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.

User:Damyon Wiese/Templates

2015-03-18T07:09:27Z

Jethac: /* How do templates work with renderers? */

= 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 are section 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>{{> 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.

== 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 [User:Damyon_Wiese/Javascript_Modules 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.renderTemplate('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.
});

// 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 create a new script tag and append 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 words 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 words 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);
retrn self::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.

Timezone information

2015-02-04T05:08:31Z

Jethac: Created page with "Timezone information in Moodle is manually kept up-to-date with the IANA's Olson database as new information is released. This page contains information on this process. == G..."

Timezone information in Moodle is manually kept up-to-date with the IANA's Olson database as new information is released. This page contains information on this process.

== Getting new information from the IANA ==
There are two ways you can get information from the IANA - by downloading the latest release and manually concatenating specific files together, or by running a Python script built for that purpose.

=== Manual retrieval ===
* Go to [http://www.iana.org/time-zones the IANA's Time Zone Database site] and get the latest data file (e.g. tzdata*****.tar.gz).
* Extract the file to an appropriate location.
* Create a new text file, naming it '''olson.txt''' and concatenate the following files in the following order:
** africa
** antarctica
** asia
** australasia
** europe
** northamerica
** southamerica
** etcetera

=== Automatic retrieval ===
* Run the following Python 2.7 script: https://gist.github.com/jethac/ee03aff52176fb7cc9fe
* Rename the generated .txt file as '''olson.txt'''

== Importing information into Moodle ==
* Place the generated olson.txt file into {dataroot}/temp/olson.txt, where {dataroot} is the path to your Moodle's moodledata folder
* In a browser, go to '''Site administration''' -> '''Location''' -> '''Update timezones''' and confirm
** The contents of your '''timezone''' database table will be flushed and regenerated from the olson.txt

== Exporting information ==
* Using a DB admin tool (e.g. phpMyAdmin, pgadmin3), generate a CSV file from your '''timezone''' database table with the following settings:
** commas as field separators
** non-quoted values
** unix line feeds
** first line as field names
* Replace {moodleroot}/lib/timezone.txt with the contents of the CSV file
* Commit to git and fill out the tracker fields as necessary

The integrators have a separate process that copies the {moodleroot}/lib/timezone.txt out of HEAD to https://download.moodle.org/timezone/, so you shouldn't have to do anything more.

Theme upgrade notes

2014-12-08T06:09:34Z

Jethac: Created page with "As the project evolves, theme designers and maintainers should take care that their themes accommodate functionality additions and changes. == Moodle 2.8 == Moodle 2.8 contai..."

As the project evolves, theme designers and maintainers should take care that their themes accommodate functionality additions and changes.

== Moodle 2.8 ==
Moodle 2.8 contains large changes, including but not limited to

* an all-new user menu, and
* an overhauled gradebook.

These changes bring with them new considerations for theme developers, who will need to adjust their themes accordingly.

=== User menu ===
The user menu is a new renderer function - $OUTPUT->user_menu() - that leverages the action_menu renderable to create a dropdown menu containing user-centric links (my home, my profile, etc). The user menu encapsulates the same status checks and exposes the same information as the existing $OUTPUT->login_info() function, with the addition of user pictures.

It is important to note that the user menu depends upon a new function in /user/lib.php, entitled user_get_user_navigation_info. It is possible for the upgrade step to fail if $CFG->dirroot is overridden by a site's config.php incorrectly.

==== Including the user menu in a backwards-compatible way ====
As this is a new feature for 2.8, you may want to build your theme such that it falls back to use $OUTPUT->login_info if the user menu is not present, e.g.

<code php>
<?php
if (method_exists($OUTPUT, 'user_menu')) {
echo $OUTPUT->user_menu(); // user menu, for Moodle 2.8
} else {
echo $OUTPUT->login_info(); // login_info, Moodle 2.7 and before
}
?>
</code>

This will allow you to write a theme that works on both 2.8 and on previous versions of Moodle.

==== Styling edge cases ====
When styling the user menu, it is important to cover additional use cases under which the user menu changes. These are:

* when Javascript is disabled
* when a user is "logged in as" another user
* when a user is using a right-to-left language

Ensure any custom styles you write take into account these circumstances; for reference you may wish to consult the existing styles, which are in /theme/bootstrapbase/less/moodle/modules.less.

=== Grader report ===
The new grader report is a significant change from its predecessor (please see [https://docs.moodle.org/dev/Grader_report_2014]) and may require some adjustments to your theme.

==== Overflowing ====
Put simply, the grader report now expects to be directly on the page, overflowing the window bounds if necessary - as the user scrolls more of the table into view, floating row and column headers appear and move with the window to provide context as to their position in the table.

This has unfortunate effects on themes where the grader report is situated within an element with the overflow: hidden rule set, or with a value provided for width or max-width. In order to use the new grader report as designed, allow it to spill out unconstrained - the floating headers will not kick in otherwise and pose a usability concern.

Creating a theme

2014-12-03T09:24:04Z

Jethac: /* The page header */

{{Template:Themes}}This document describes how to create a theme for Moodle 2.x.x. It assumes you have some understanding of how themes within Moodle work as well as a good understanding of HTML and CSS.

===Theme designer mode===

Under normal operation Moodle does several things in the name of performance, one of these is to combine all of the CSS into one file, minimize it, cache it on the server, and then serve it. After the first request the cached version is served to greatly improve page performance.

What this means for you as a themer? When you make changes they will not be seen immediately. In fact you will need to tell Moodle to rebuild the cache that it is serving.
This isn't practical for designing themes of course so the '''theme designer mode''' was added. When enabled it tells Moodle not to combine or cache the CSS that gets delivered. This has the downside that page load times will take significantly longer, however you will see your changes immediately every time.

Theme designer mode may be enabled via ''Administration > Appearance > Themes > [[Theme settings]]''.

'''Warning''': Internet Explorer versions 6 and 7 have BIG problems when a site attempts to link to more than 31 stylesheets, in which case either a limited number or no styles get applied. Because Moodle sends up all of the CSS all of the time with theme designer mode turned on there is a very high chance you will get more than 31 stylesheets being included. This will, of course, cause major problems for Internet Explorer until theme designer mode is turned off.

==Getting started==

The first thing you need to do is create the directories and files you will be using, the first thing to create is the actual directory for your theme. This should be the name of your theme, in my case it's 'excitement'. The directory should be located within the theme directory of Moodle, ./moodle/theme/excitement/ will be the directory I create.

Now within that directory we can immediately create several files that we know we are going to need.

So the files that we want to create are:
; config.php : All of our settings will go here.
; /style/ : This directory will contain all of our stylesheets.
; /style/excitement.css : All of our css will go in here.
; /pix/ : Into this directory we'll put a screen shot of our theme as well as our favicon and any images we use in CSS.
; /layout/ : Our layout files will end up in this directory.
; /layout/standard.php : This will be our one basic layout file.
; /lang/en/ : The file we put here will make our theme name show properly on the Theme Selector page. You need a few standard entries. Copy the one from the Standard theme and modify is easiest.

So after this setup step you should have a directory structure similar to what is shown below.

[[image:Learn_to_theme_01.jpg]]

==Configuring our theme==

Open config.php in your favourite editor and start by adding the opening PHP tags '''<nowiki><?php</nowiki>'''.

Now we need to add the settings:

<code php>
$THEME->name = 'excitement';
</code>
Very simply this tells Moodle the name of your theme, and if you ever have several config.php files open this will help you identify which one you are looking at.

Next, the parents for this theme.
<code php>
$THEME->parents = array('base');
</code>
This tells Moodle that my new theme ''`excitement`' wants to extend the base theme.

A theme can extend any number of themes. Rather than creating an entirely new theme and copying all of the CSS, you can simply create a new theme, extend the theme you like and just add the changes you want to your theme.

Also worth noting is the purpose of the base theme: it provides us with a basic layout and just enough CSS to make everything fall into place.

Now we will tell Moodle about our stylesheets:
<code php>
$THEME->sheets = array('excitement');
</code>

The final thing we need to add into our theme's config.php file is the definition of the layouts for our theme:
(in the code below, replace 'general.php' with 'standard.php' because that is the file that is previously created)
<code php>
$THEME->layouts = array(
// Most backwards compatible layout without the blocks - this is the layout used by default
'base' => array(
'file' => 'general.php',
'regions' => array(),
),
// Standard layout with blocks, this is recommended for most pages with general information
'standard' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
),
// part of course, typical for modules - default page layout if $cm specified in require_login()
'incourse' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
),
// Server administration scripts.
'admin' => array(
'file' => 'general.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
// My dashboard page
'mydashboard' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
),
'login' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('langmenu'=>true),
),

// Pages that appear in pop-up windows - no navigation, no blocks, no header.
'popup' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true, 'nologininfo'=>true, 'nocourseheaderfooter'=>true),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.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(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true, 'nocourseheaderfooter'=>true),
),
// Used during upgrade and install, and for the 'This site is undergoing maintenance' message.
// This must not have any blocks, and it is good idea if it does not have links to
// other places - for example there should not be a home link in the footer...
'maintenance' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('noblocks'=>true, 'nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true, 'nocourseheaderfooter'=>true),
),
// Should display the content and basic headers only.
'print' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('noblocks'=>true, 'nofooter'=>true, 'nonavbar'=>false, 'nocustommenu'=>true, 'nocourseheaderfooter'=>true),
),
// The pagelayout used when a redirection is occuring.
'redirect' => array(
'file' => 'embedded.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true, 'nocourseheaderfooter'=>true),
),
// The pagelayout used for reports.
'report' => array(
'file' => 'report.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
// The pagelayout used for safebrowser and securewindow.
'secure' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true, 'nologinlinks'=>true, 'nocourseheaderfooter'=>true),
),
);

/** List of javascript files that need to be included on each page */
$THEME->javascripts = array();
$THEME->javascripts_footer = array();

</code>

What you are looking at is the different layouts for our theme. Why are there so many? Because, that is how many there are in Moodle. There is one for every general type of page. With my ''`excitement`'' theme I have chosen to use my own layout. Unless there was a specific reason to do so, normally you would not need to create your own layouts, you could extend the base theme, and use its layouts, meaning you would only have to write CSS to achieve your desired look.

For each layout above, you will notice the following four things are being set:
; file : This is the name of the layout file we want to use, it should always be located in the above themes layout directory. For us this is of course standard.php as we only have one layout file.
; regions : This is an array of block regions that our theme has. Each entry in here can be used to put blocks in when that layout is being used.
; defaultregion : If a layout has regions it should have a default region, this is where blocks get put when first added. It is also where the "add block" block is shown when editing is on.
; options : These are special settings, anything that gets put into the options array is available later on when we are writing our layout file.

There are additional settings that can be defined in the config.php file - see [[Themes 2.0|Themes 2.0]] for the full list.

==Configuring the language file==
Open theme_base.php file from '''base/lang/en/theme_base.php'''

Save it as '''excitement/lang/en/theme_excitement.php'''.

Change
<code php>
$string['pluginname'] = 'Base';
</code>
to
<code php>
$string['pluginname'] = 'Excitement';
</code>

After making these changes and perhaps clearing theme caches and/or purging all caches, the new theme name should now show properly in the Theme Selector: ''Site Administration > Appearance > Themes > Theme Selector''

You can also edit the theme description:

<code php>
$string['choosereadme'] = 'Write your theme description here.';
</code>

You need to leave the following two lines in place (you can change the wording if you need to) to avoid notices when editing blocks etc.:

<code php>
$string['region-side-post'] = 'Right';
$string['region-side-pre'] = 'Left';
</code>

==Writing the layout file==

The excitement theme has just one layout file.

The downside of this is that I have to make the layout file do everything I want which means I need to make use of some options (as defined in the layouts in config.php).

The upside is that I only need to maintain one file.

Other than maintenance, using multiple layout files provides many advantages to real world themes in that you can easily tweak and customise specific layouts to achieve the goals of the organisation using the theme.

Before learning more it is good to understand the two primary objects that will be used in your layout files: $OUTPUT and $PAGE.

'''$OUTPUT''' is an instance of the <code>core_renderer</code> class which is defined in lib/outputrenderers.php. Each method is clearly documented there, along with which is appropriate for use within the layout files.

'''$PAGE''' is an instance of the <code>moodle_page</code> class defined in lib/pagelib.php. Most of the things you will want to use are the properties that are all documented at the top of the file. If you are not familiar with PHP properties, you access them like $PAGE->activityname, just like fields of an ordinary PHP object. (However, behind the scenes the value you get is produced by calling a function. Also, you cannot change these values, they are '''read-only'''. However, you don't need to understand all that if you are just using these properties in your theme.)

So lets start writing standard.php, the layout file for my ''`excitement`'' theme.

===The top of the layout file===

<code php>
<?php
$hassidepre = $PAGE->blocks->region_has_content('side-pre', $OUTPUT);
$hassidepost = $PAGE->blocks->region_has_content('side-post', $OUTPUT);
echo $OUTPUT->doctype(); ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title ?></title>
<?php echo $OUTPUT->standard_head_html() ?>
</head>
</code>

Lets look at the code that goes into this section:
<code php>
<?php
echo $OUTPUT->doctype(); ?>
</code>
This is very important and is required to go at the very top of the page. This tells Moodle to print out the document type tag that is determined by the settings within Moodle.

<code php>
<html <?php echo $OUTPUT->htmlattributes() ?>>
</code>
Here we open the HTML tag and then ask Moodle to print the attributes that should go inside it.

<code php>
<title><?php echo $PAGE->title ?></title>
</code>
Simply creates the title tag and asks Moodle to fill it in.

<code php>
<?php echo $OUTPUT->standard_head_html() ?>
</code>
Here we are asking Moodle to print all of the other tags and content that need to go into the head. This includes stylesheets, script tags, and inline JavaScript code.

===The page header===

<code php>
<body id="<?php p($PAGE->bodyid); ?>" class="<?php p($PAGE->bodyclasses); ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<div id="page">
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
<div id="page-header">
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
if (method_exists($OUTPUT, 'user_menu')) {
echo $OUTPUT->user_menu(); // user menu, for Moodle 2.8
} else {
echo $OUTPUT->login_info(); // login_info, Moodle 2.7 and before
}
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div>
<?php } ?>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</div>
<?php } ?>
</code>

So there is a bit more going on here obviously.

<code php>
<body id="<?php p($PAGE->bodyid); ?>" class="<?php p($PAGE->bodyclasses); ?>">
</code>
Again much like what we did for the opening HTML tag in the head we have started writing the opening body tag and are then asking Moodle to give us the ID we should use for the body tag as well as the classes we should use.

<code php>
<?php echo $OUTPUT->standard_top_of_body_html() ?>
</code>
This very important call writes some critical bits of JavaScript into the page. It should always be located after the body tag as soon as possible.

<code php>
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
......
<?php } ?>
</code>
Here we are checking whether or not we need to print the header for the page. There are three checks we need to make here:
# '''$PAGE->heading''' : This checks to make sure that there is a heading for the page. This will have been set by the script and normally describes the page in a couple of words.
# '''empty($PAGE->layout_options['nonavbar'])''' : Now this check is looking at the layout options that we set in our config.php file. It is looking to see if the layout set 'nonavbar' => true.
# '''$PAGE->has_navbar()''' The third check is to check with the page whether it has a navigation bar to display.
If either there is a heading for this page or there is a navigation bar to display then we will display a heading.

Leading on from this lets assume that there is a header to print.
<code php>
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
.....
<?php } ?>
</code>
This line is simply saying if the page has a heading print it. In this case we run the first check above again just to make sure there is a heading, we then open a heading tag that we choose and ask the page to print the heading.

<code php>
<div class="headermenu"><?php
if (method_exists($OUTPUT, 'user_menu')) {
echo $OUTPUT->user_menu(); // user menu, for Moodle 2.8
} else {
echo $OUTPUT->login_info(); // login_info, Moodle 2.7 and before
}
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div>
</code>
Here we are looking to print the menu and content that you see at the top of the page (usually to the right). We start by getting Moodle to print the login information for the current user. If the user is logged in this will be their name and a link to their profile, if not then it will be a link to login. Note that on Moodle 2.8 and above, a new user menu renderable is available that visually shows the same information as the login info renderable, as well as a dropdown menu with user-centric actions.

Next we check our page options to see whether a language menu should be printed. If in the layout definition within config.php it sets '''langmenu => true''' then we will print the language menu, a drop down box that lets the user change the language that Moodle displays in.

Finally the page also has a heading menu that can be printed. This heading menu is special HTML that the page you are viewing wants to add. It can be anything from drop down boxes to buttons and any number of each.

<code php>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</code>
The final part of the header.

Here we want to print the navigation bar for the page if there is one. To find out if there is one we run checks number 2 and 3 again and proceed if they pass.

Assuming there is a header then there are two things that we need to print. The first is the navigation bar. This is a component that the OUTPUT library knows about. The second is a button to show on the page.

In both cases we choose to wrap them in a div tag with a class attribute to enable theming on those elements.

Well that is it for the header. There is a lot of PHP compared to the other sections of the layout file but it does not change and can be copied and pasted between themes.

===The page content===

I am going with the default two block regions plus the main content.

Because I have based this theme and layout file on the base theme the HTML looks a little intense. This is because it is a floating div layout where the content comes first and then we get the columns (even though one column will be to the left of the content.) Don't worry too much about it. When it comes to writing your own theme you can go about it as you choose.

<code php>
<div id="page-content">
<div id="region-main-box">
<div id="region-post-box">
<div id="region-main-wrap">
<div id="region-main">
<div class="region-content">
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</div>
</div>
</div>
<?php if ($hassidepre) { ?>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<?php } ?>

<?php if ($hassidepost) { ?>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
<?php } ?>
</div>
</div>
</div>
</code>

In regards to PHP this section is very easy. There are only three lines for the whole section one to get the main content and one for each block region.
<code php>
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</code>
This line prints the main content for the page.
PLEASE NOTE: In Moodle 2.2 onwards "core_renderer::MAIN_CONTENT_TOKEN" changed to "$OUTPUT->main_content()".

<code php>
<?php if ($hassidepre) { ?>
....
<?php } ?>
</code>
These lines of code check the variables we created earlier on to decide whether we should show the pre block region. If you try to display a block region that isn't there or has no content then Moodle will give you an error message so these lines are very important.

For those who get an error message if it is "unknown block region side-pre" or "unknown block region side-post" then this is the issue you are experiencing. Simply add the following lines and all will be fine.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</code>
This line gets all of the blocks and more particularly the content for the block region '''side-pre'''. This block region will be displayed to the left of the content.

<code php>
<?php if ($hassidepost) { ?>
....
<?php } ?>
</code>
Again we should make this check for every block region as there are some pages that have no blocks what-so-ever.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</code>
Here we are getting the other block region '''side-post''' which will be displayed to the right of the content.

===The page footer===
Here we want to print the footer for the page, any content required by Moodle, and then close the last tags.
<code php>
<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</div>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>

The section of code is responsible for printing the footer for the page.
<code php>
<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</code>
The first thing we do before printing the footer is check that we actually want to print it. This is done by checking the options for the layout as defined in the config.php file. If '''nofooter => true''' is set the we don't want to print the footer and should skip over this body of code.

Assuming we want to print a footer we proceed to create a div to house its content and then print the bits of the content that will make it up.
There are four things that the typical page footer will want to print:
; echo page_doc_link(get_string('moodledocslink')) : This will print a link to the Moodle.org help page for this particular page.
; echo $OUTPUT->login_info(); : This is the same as at the top of the page and will print the login information for the current user.
; echo $OUTPUT->home_link(); : This prints a link back to the Moodle home page for this site.
; echo $OUTPUT->standard_footer_html(); : This prints special HTML that is determined by the settings for the site. Things such as performance information or debugging will be printed by this line if they are turned on.

And the final line of code for our layout file is:
<code php>
<?php echo $OUTPUT->standard_end_of_body_html(); ?>
</code>
This is one of the most important lines of code in the layout file. It asks Moodle to print any required content into the page, and there will likely be a lot although most of it will not be visual.

It will instead be things such as inline scripts and JavaScript files required to go at the bottom of the page. If you forget this line its likely no JavaScript will work!

We've now written our layout file and it is all set to go. The complete source is below for reference. Remember if you want more practical examples simply look at the layout files located within the layout directory of other themes.

<code php>
<?php
$hassidepre = $PAGE->blocks->region_has_content('side-pre', $OUTPUT);
$hassidepost = $PAGE->blocks->region_has_content('side-post', $OUTPUT);
echo $OUTPUT->doctype() ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title; ?></title>
<link rel="shortcut icon" href="<?php echo $OUTPUT->pix_url('favicon', 'theme')?>" />
<?php echo $OUTPUT->standard_head_html() ?>
</head>

<body id="<?php p($PAGE->bodyid); ?>" class="<?php p($PAGE->bodyclasses); ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<div id="page">
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
<div id="page-header">
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div><?php } ?>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</div>
<?php } ?>

<div id="page-content">
<div id="region-main-box">
<div id="region-post-box">
<div id="region-main-wrap">
<div id="region-main">
<div class="region-content">
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</div>
</div>
</div>
<?php if ($hassidepre) { ?>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<?php } ?>

<?php if ($hassidepost) { ?>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
<?php } ?>
</div>
</div>
</div>

<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</div>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>

==Adding some CSS==
With config.php and standard.php both complete the theme is now usable and starting to look like a real theme, however if you change to it using the theme selector you will notice that it still lacks any style.

This of course is where CSS comes in. When writing code Moodle developers are strongly encouraged to not use inline styles anywhere. This is fantastic for us as themers because there is nothing (or at least very little) in Moodle that cannot be styled using CSS.

===Moodle CSS basics===

In Moodle 2.0 all of the CSS for the whole of Moodle is delivered all of the time! This was done for performance reasons. Moodle now reads in all of the CSS, combines it into one file, shrinks it removing any white space, caches it, and then delivers it.

'''What this means for you as a themer?'''

You will need to write good CSS that won't clash with any other CSS within Moodle.

Moodle is so big and complex,there is no way to ensure that classes don't get reused. What we can control however is the classes and id that get added to the body tag for every page. When writing CSS it is highly encouraged to make full use of these body classes, using them will help ensure the CSS you write has the least chance of causing conflicts.

You should also take the time to look at how the Moodle themes use CSS. Look at their use of the body classes and how they separate the CSS for the theme into separate files based on the region of Moodle it applies to.

Check out [[Themes 2.0|Themes 2.0]] and [[CSS coding style]] for more information about writing good CSS.

===Starting to write excitement.css===

<code css>
a {
text-decoration: none;
}

.addcoursebutton .singlebutton {
text-align: center;
}

h1.headermain {
color: #fff;
}

h2.main {
border-bottom: 3px solid #013D6A;
color: #013D6A;
text-align: center;
}

h2.headingblock {
font-size: 18pt;
margin-top: 0;
background-color: #013D6A;
color: #FFF;
text-align: center;
}

#page-header {
background-color: #013D6A;
}

#page-header .headermenu {
color: #FFF;
}

#page-header .headermenu a {
color: #FDFF2A;
}

.navbar {
padding-left: 1em;
}

.breadcrumb li {
color: #FFF;
}

.breadcrumb li a {
color: #FFF;
}

.block {
background-color: #013D6A;
}

.block .header .title {
color: #FFF;
}

.block .header .title .block_action input {
background-color: #FFF;
}

.block .content {
border: 1px solid #000;
padding: 5px;
background-color: #FFF;
}

.block .content .block_tree p {
font-size: 80%;
}

.block_settings_navigation_tree .content .footer {
text-align: center;
}

.block_settings_navigation_tree .content .footer .adminsearchform {
margin-left: 5%;
width: 90%;
font-size: 9pt;
}

.block_settings_navigation_tree .content .footer .adminsearchform #adminsearchquery {
width: 95%;
}

.block_calendar_month .content .calendar-controls a {
color: #013D6A;
font-weight: bold;
}

.block_calendar_month .content .minicalendar td {
border-color: #FFF;
}

.block_calendar_month .content .minicalendar .day {
color: #FFF;
background-color: #013D6A;
}

.block_calendar_month .content .minicalendar .day a {
color: #FFF000;
}

.block_calendar_month .content .minicalendar .weekdays th {
border-width: 0;
font-weight: bold;
color: #013D6A;
}

.block_calendar_month .content .minicalendar .weekdays abbr {
border-width: 0;
text-decoration: none;
}
</code>
[[image:Learn_to_theme_02.jpg|400px|thumb|Excitement theme screenshot]]
This isn't all of the CSS for the theme, but just enough to style the front page when the user is not logged in.
Remember this theme extends the base theme so there is already CSS for layout as well.

Note:
* The CSS is laid out in a single line format. This is done within the core themes for Moodle. It makes it quicker to read the selectors and see what is being styled.
* I have written my selectors to take into account the structure of the HTML (more than just the one tag I want to style). This helps further to reduce the conflicts that I may encounter.
* I use generic classes like ''.sideblock'' only where I want to be generic, as soon as I want to be specific I use the unique classes such as ''.block_calendar_month''

<br style="clear:right;" />

===Using images within CSS===

I will add two image files to the pix directory of my theme:
; /theme/excitement/pix/background.png : This will be the background image for my theme.
; /theme/excitement/pix/gradient.jpg : This will be a gradient I use for the header and headings.
I quickly created both of these images using gimp and simply saved them to the pix directory.
<code css>
html {
background-image: url([[pix:theme|background]]);
}

h2.headingblock,
#page-header,
.sideblock,
.block_calendar_month .content .minicalendar .day {
background-image: url([[pix:theme|gradient]]);
background-repeat: repeat-x;
background-color: #0273C8;
}
</code>
[[image:Learn_to_theme_03.jpg‎|400px|thumb|Excitement theme screenshot]]
The CSS above is the two new rules that I had to write to use my images within CSS.

The first rule sets the background image for the page to background.png

The second rule sets the background for headings, and the sideblocks to use gradient.jpg

You will notice that I did not need to write a path to the image. This is because Moodle has this special syntax that can be used and will be replaced when the CSS is parsed before delivery.
The advantage of using this syntax over writing the path in is that the path may change depending on where you are or what theme is being used.

Other themers may choose to extend your theme with their own; if you use this syntax then all they need to do to override the image is to create one with the same name in their themes directory.

You will also notice that I don't need to add the image files extension. This is because Moodle is smart enough to work out what extension the file uses. It also allows themers to override images with different formats.

<br style="clear:right" />
The following is the complete CSS for my theme:
<div style="overflow:auto;height:860px;">
<code css>
a {text-decoration: none;}
.addcoursebutton .singlebutton {text-align: center;}

h1.headermain {color: #fff;}
h2.main {border-bottom: 3px solid #013D6A;color: #013D6A;text-align: center;}
h2.headingblock {font-size: 18pt;margin-top: 0;background-color: #013D6A;color: #FFF;text-align: center;}
#page-header {background-color: #013D6A;border-bottom:5px solid #013D6A;}
#page-header .headermenu {color: #FFF;}
#page-header .headermenu a {color: #FDFF2A;}

.sideblock {background-color: #013D6A;}
.sideblock .header .title {color: #FFF;}
.sideblock .header .title .block_action input {background-color: #FFF;}
.sideblock .content {border: 1px solid #000;padding: 5px;background-color: #FFF;}
.sideblock .content .block_tree p {font-size: 80%;}

.block_settings_navigation_tree .content .footer {text-align: center;}
.block_settings_navigation_tree .content .footer .adminsearchform {margin-left: 5%;width: 90%;font-size: 9pt;}
.block_settings_navigation_tree .content .footer .adminsearchform #adminsearchquery {width: 95%;}

.block_calendar_month .content .calendar-controls a {color: #013D6A;font-weight: bold;}
.block_calendar_month .content .minicalendar td {border-color: #FFF;}
.block_calendar_month .content .minicalendar .day {color: #FFF;background-color: #013D6A;}
.block_calendar_month .content .minicalendar .day a {color: #FFF000;}
.block_calendar_month .content .minicalendar .weekdays th {border-width: 0;font-weight: bold;color: #013D6A;}
.block_calendar_month .content .minicalendar .weekdays abbr {border-width: 0;text-decoration: none;}

html {background-image:url([[pix:theme|background]]);}

h2.headingblock,
#page-header,
.sideblock,
.block_calendar_month .content .minicalendar .day {background-image:url([[pix:theme|gradient]]);
background-repeat:repeat-x;background-color: #0273C8;}
</code>
</div>

==Adding a screenshot and favicon==
The final thing to do at this point is add both a screenshot for this theme as well as a favicon for it.
The screenshot will be shown in the theme selector screen and should be named ''screenshot.jpg''.
The favicon will be used when someone bookmarks this page.
Both images should be located in your themes pix directory as follows:
* /theme/excitement/pix/screenshot.jpg
* /theme/excitement/pix/favicon.ico

In the case of my theme I have taken a screenshot and added it to that directory, and because I don't really want to do anything special with the favicon I have copied it from /theme/base/pix/favicon.ico so that at least it will be recognisable as Moodle.

[[es:Desarollo:Temas 2.0 creando tu primer tema]]

Themes overview

2014-12-03T09:20:50Z

Jethac: /* Layout files */

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

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 2.0

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.

==What's new in 2.7==
{{Moodle 2.7}}

===Compiling LESS===

Themes now have the ability to compile a LESS file on the fly. This was intended to be used for dynamic injection of LESS code or variables. (MDL-44357)

==What's new in 2.6==
{{Moodle 2.6}}

===Fonts===

CSS3 fonts can be now used in plugins, core and moodle themes. It is very similar to images in pix subdirectories (MDL-23493).

===Chat Activity===

The Chat room window is now also styled via bootstrapbase. Themes based on bootstrapbase can now directly style or use 'customcss' to style the chat window now. (MDL-42711)

==What's new in 2.5==
{{Moodle 2.5}}

There is a new Bootstrap base theme. See [[Clean theme]] for more information.

==What's new in 2.4==
{{Moodle 2.4}}

===HTML 5 doctype===

By default Moodle is sending HTML5 doctype. Themes designers may decide to force old xhtml strict mode, but it is strongly discouraged and the site will not pass strictness validation. (MDL-34299)

===Internet Explorer standards mode===

Since 2.4 Moodle automatically sends X-UA-Compatible edge header, this should prevent Internet Explorer from switching to quirks or compatibility modes (MDL-36524). There is also a new workaround for intranet servers which previously identified recent IE browsers as IE7. (MDL-36481)

===SVG icons===

Most modern browsers support SVG icons. The benefit is that SVG scales perfectly to any screen resolution or zoom. It is now possible to add icons in SVG format to pix directories, Moodle uses SVG in supported browsers and PNG in legacy browsers. (MDL-22955)

Please note that IE9 does not handle scaling of standard SVG icons properly, you may have to manually execute a special script from theme/base/cli/svgtool.php to alter the icons to be compatible with buggy IE9. (MDL-36436)

==What's new in 2.0==

The theme system was completely redesigned in Moodle 2.0. Known issues have been addressed and new features have been added to meet community requests.

Unfortunately it was not possible to maintain backward compatibility, so all Moodle 1.x themes need to be recreated for Moodle 2.0.

Major changes include:
* Clearer and more consistent CSS classes and IDs throughout all pages in Moodle
* Introduction of layout files (templates) describing overall layout HTML for many different types of pages in Moodle.
* Introduction of renderers, which produce the smaller "parts" of a HTML page. Advanced themes can choose to override these too if they choose.
* Introduction of standard methods for adding Javascript to themes.
* Easier control over icons and images in Moodle.
* The old "standard" theme has been split into two themes:
**'''base''' - contains absolutely basic layout, and
**'''standard''' - which adds CSS to the base theme to make it look like the old standard theme.
* Performance tuning: In normal production mode CSS files are combined into a single optimised file, and both CSS and JavaScript files are minimised to ensure there are no wasted connections or traffic. Files are heavily cached, but also versioned, so that users never need to clear their caches.

==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. (If you know Moodle 1.9, it's like a combination of header.html and footer.html).
# '''The base theme''' - is not intended to be used for production sites. It sets up the simplest possible generic layout and includes only CSS essential to that layout ''or'' to Moodle as a whole. It tries not to make any unnecessary rules and makes as few assumptions as possible. It's the perfect base on which to start designing a theme, as there are very few colours, borders, margins, and alignments to override. You can just start adding what you need.

===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 classes and functions that are used by theme
|-
| /
| renderers.php
| Contains any custom renderers for the theme.
|-
| /
| settings.php
| Contains custom theme settings. These local settings are defined by the theme allowing the theme user 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).
|-
| /javascript/
| *.js
| All specialty JavaScript files the theme requires should be located in here.
|-
| /lang/
|
| Any special language files the theme requires should be located in here.
|-
| /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.
|}

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.

==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 a basic theme configuration file and the different bits that make it up:
<code php>
$THEME->name = 'newtheme';

$THEME->parents = array(
'base'
);

$THEME->sheets = array(
'admin',
'blocks',
'calendar',
'course',
'grade',
'message',
'question',
'user'
);

$THEME->layouts = array(
'base' => array(
'theme' => 'newtheme',
'file' => 'general.php',
'regions' => array(),
),
'standard' => array(
'theme' => 'newtheme',
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
)
//.......
);

$THEME->javascripts_footer = array(
'navigation'
);
</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->parents : This defines the themes that the theme will extend. In this case it is extending only the base theme.

; $THEME->sheets : An array containing the names of the CSS stylesheets to include for this theme. 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->layouts : In this example, two layouts have been defined to override the layouts from the base theme. For more information see the [[#Layouts|layouts]] section below.

; $THEME->javascripts_footer : The final setting is to include a JavaScript file. Much like stylesheets, you only need to provide the files name. Moodle will assume it is in your themes JavaScript directory and be a .js file.

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

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.

===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 within the themes provided in the standard install by Moodle there is a very clear organisation of CSS.

First is the pagelayout.css file. This contains the CSS required to give the layouts their look and feel. It doesn't contain any rules that affect the content generated by Moodle.

Next is the core.css file. If you open up core you will notice that it contains all manner of general (usually simple) rules that don't relate to a specific section of Moodle but to Moodle as a whole.

There can also be rules that relate to specific sections. However, this is done only when there are only a handful of rules for that section. These small clusters of rules are grouped together and separated by comments identifying for which section each relates.

Finally there are all the other CSS files, you will notice that there is a file for each section of Moodle that has a significant collection of rules.

:For those who are familiar with Moodle 1.9 theme's, this organisation will be a big change. In 1.9, CSS was organised by its nature (for example: colours, layout, other).

===How to write effective CSS rules within Moodle===
In Moodle 2.0, 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 ====
As of Moodle 2.0 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.

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 html4strict><body id=”page-mod-forum-view” class=”path-mod path-mod-forum” /></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.

==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. The standard theme in Moodle is a good example of this as it extends the base theme simply adding CSS to achieve its look and feel.

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' => 'base',
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post'
)
)
</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 base theme. If you take a look first at theme/base/config.php you will notice that several layouts specify options '''nonavbar''' and '''nofooter''' which can both be set to either true or false. Then if we take a look at theme/base/layout/general.php you will spot lines like the following:
<code php>
<?php
$hasnavbar = (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar());
$hasfooter = (empty($PAGE->layout_options['nofooter']));
?>
............
<?php if ($hasnavbar) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</code>
What you are seeing here is the use of those settings from the layout within the layout file. In this case it is being used to toggle the display of the navigation bar and page footer.

==Layout files==
A layout file is a file that contains the core HTML structure for a layout including the header, footer, content and block regions. For those of you who are familiar with themes in Moodle 1.9 this is simply header.html and footer.html combined. Of course it is not all HTML, there are bits of HTML and content that Moodle needs to put into the page, within each layout file this will be done by a couple of simple PHP calls to get bits and pieces including content.

Before learning more it is good to understand the two primary objects that will be used in your layout files: $OUTPUT and $PAGE.

'''$OUTPUT''' is an instance of the <code>core_renderer</code> class which is defined in lib/outputrenderers.php. Each method is clearly documented there, along with which is appropriate for use within the layout files.

'''$PAGE''' is an instance of the <code>moodle_page</code> class defined in lib/pagelib.php. Most of the things you will want to use are the properties that are all documented at the top of the file. If you are not familiar with PHP properties, you access them like $PAGE->activityname, just like fields of an ordinary PHP object. (However, behind the scenes the value you get is produced by calling a function. Also, you cannot change these values, they are '''read-only'''. However, you don't need to understand all that if you are just using these properties in your theme.)

The following is a very simple layout file to illustrate the different bits that make it up:
<code php>
<?php echo $OUTPUT->doctype() ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title ?></title>
<?php echo $OUTPUT->standard_head_html() ?>
</head>
<body id="<?php p($PAGE->bodyid) ?>" class="<?php p($PAGE->bodyclasses) ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<table id="page">
<tr>
<td colspan="3">
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
if (method_exists($OUTPUT, 'user_menu')) {
echo $OUTPUT->user_menu(); // user menu, for Moodle 2.8
} else {
echo $OUTPUT->login_info(); // login_info, Moodle 2.7 and before
}
echo $PAGE->headingmenu;
?></div>
</td>
</tr>
<tr>
<td>
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</td>
<td>
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</td>
<td>
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</td>
</tr>
<tr>
<td colspan="3">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</td>
</tr>
</table>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>

We assume you know enough HTML to understand the basic structure above, but let's explain the PHP code since that is less obvious.
<code php>
<?php echo $OUTPUT->doctype() ?>
</code>
This occurs at the VERY top of the page, it must be the first bit of output and is responsible for adding the (X)HTML document type definition to the page. This of course is determined by the settings of the site and is one of the things that the theme designer has no control over.

<code php>
<html <?php echo $OUTPUT->htmlattributes() ?>>
</code>
Here we have started writing the opening html tag and have asked Moodle to give us the HTML attributes that should be applied to it. This again is determined by several settings within the actual HTML install.

<code php>
<?php echo $PAGE->title ?>
</code>
This gets us the title for the page.

<code php>
<?php echo $OUTPUT->standard_head_html() ?>
</code>
This very important call gets us the standard head HTML that needs to be within the HEAD tag of the page. This is where CSS and JavaScript requirements for the top of the page will be output as well as any special script or style tags.

<code php>
<body id="<?php p($PAGE->bodyid); ?>" class="<?php p($PAGE->bodyclasses); ?>">
</code>
Much like the html tag above we have started writing the body tag and have asked for Moodle to get us the desired ID and classes that should be applied to it.

<code php>
<h1 class="headermain"><?php echo $PAGE->heading; ?></h1>
<div class="headermenu"><?php
if (method_exists($OUTPUT, 'user_menu')) {
echo $OUTPUT->user_menu(); // user menu, for Moodle 2.8 onwards
} else {
echo $OUTPUT->login_info(); // login_info, Moodle 2.7 and before
}
echo $PAGE->headingmenu; ?></div>
</code>
Here we are creating the header for the page. In this case we want the heading for the page, a user menu (for Moodle 2.8+) or login information (the current users username or a link to log in if they are not logged in), and we want the heading menu if there is one.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</code>
Here we get the HTML to display the blocks that have been added to the page. In this case we have asked for all blocks that have been added to the area labelled ''side-pre''.

<code php>
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</code>
This is one of the most important calls within the file, it determines where the actual content for the page gets inserted.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</code>
Here we get the HTML to display the blocks that have been added to the page. In this case we have asked for all blocks that have been added to the area labelled ''side-post''.

<code php>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</code>
This final bit of code gets the content for the footer of the page. It gets the login information which is the same as in the header, a home link, and the standard footer HTML which like the standard head HTML contains all of the script and style tags required by the page and requested to go in the footer.

'''''Note''''': Within Moodle 2.0 most of the JavaScript for the page will be included in the footer. This greatly helps reduce the loading time of the page.

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 'standard' theme has a language file called lang/en/theme_standard.php.

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

<code php>
$string['pluginname'] = 'Standard';
$string['region-side-post'] = 'Right';
$string['region-side-pre'] = 'Left';
$string['choosereadme'] = 'This theme is a very basic white theme, with a minimum amount of
CSS added to the base theme to make it actually usable.';
</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 HTML, such as if you wanted to use them within a layout file.
<code php>
<img src="<?php echo $OUTPUT->pix_url('imageone', 'theme');?>" alt="" />
<img src="<?php echo $OUTPUT->pix_url('subdir/imagetwo', 'theme');?>" alt="" />
</code>

'''DO NOT''' include the image file extension. Moodle will work it out automatically and it will not work if you do include it.

In this case rather than writing out the URL to the image we use a method of Moodle's output library. 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.

The following is how you would use the images from within CSS 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 module images we need a '''pix_mod''' directory.

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.

==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 'base' theme.

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

==Appendix A==
===Theme options as of 8th April 2014===

{| 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.
|-
| $THEME->'''csspostprocess'''
| Allows the user to provide the name of a function that all CSS should be passed to before being delivered.
|-
| $THEME->'''doctype'''
| The doctype of the served documents.
|-
| $THEME->'''editor_sheets'''
| An array of stylesheets to include within the body of the 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->'''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->'''filter_mediaplugin_colors'''
| Used to control the colours used in the small media player for the filters
|-
| $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)
|-
| $THEME->'''javascripts_footer'''
| As above but will be included in the page footer.
|-
| $THEME->'''larrow'''
| Overrides the left arrow image used throughout Moodle
|-
| $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->'''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->'''rarrow'''
| Overrides the right arrow image used throughout Moodle
|-
| $THEME->'''renderfactory'''
| Sets a custom render factory to use with the theme, used when working with custom renderers.
|-
| $THEME->'''resource_mp3player_colors'''
| Controls the colours for the MP3 player
|-
| $THEME->'''sheets'''
| An array of stylesheets to include for this theme. Should be located in the theme's style directory.
|-
| $THEME->'''supportscssoptimisation'''
| When set to 'FALSE' then the theme will not be affected by the 'CSS Optimiser'. The 'CSS Optimiser' is enabled in Development > Experimental > Experimental settings. When it is enabled CSS will be run through an optimisation process before being cached. The optimiser processes the CSS removing duplicate rules and styles, as well as white space removable and reformatting. Please note turning this on at the same time as theme designer mode is awful for performance but will help theme designers create optimised CSS.
|-
| $THEME->'''yuicssmodules'''
| An array of YUI CSS modules to be included.
|}

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

==See also==
* [[Theme changes in 2.0]]
* [[Adding courses and categories to the custom menu]]
* [[Making a horizontal dock]]
* [[Adding theme upgrade code]]
* [[Styling and customising the dock]]
* [[Changing topic or weekly outline to Page heading]]
* [[jQuery]]

===Moodle 2.2+===

* [[Themes 2.2 how to clone a Moodle 2.2 theme]]

===Moodle Bootstrap Themes - Moodle 2.5+===

* [[Themes 2.5 How to copy and customise the Simple (bootstrap) theme]]

[[de:Designs 2.0]]
[[es:Temas 2.0]]

[[Category:Plugins]]

Themes overview

2014-12-03T09:19:06Z

Jethac: /* Layout files */

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

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 2.0

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.

==What's new in 2.7==
{{Moodle 2.7}}

===Compiling LESS===

Themes now have the ability to compile a LESS file on the fly. This was intended to be used for dynamic injection of LESS code or variables. (MDL-44357)

==What's new in 2.6==
{{Moodle 2.6}}

===Fonts===

CSS3 fonts can be now used in plugins, core and moodle themes. It is very similar to images in pix subdirectories (MDL-23493).

===Chat Activity===

The Chat room window is now also styled via bootstrapbase. Themes based on bootstrapbase can now directly style or use 'customcss' to style the chat window now. (MDL-42711)

==What's new in 2.5==
{{Moodle 2.5}}

There is a new Bootstrap base theme. See [[Clean theme]] for more information.

==What's new in 2.4==
{{Moodle 2.4}}

===HTML 5 doctype===

By default Moodle is sending HTML5 doctype. Themes designers may decide to force old xhtml strict mode, but it is strongly discouraged and the site will not pass strictness validation. (MDL-34299)

===Internet Explorer standards mode===

Since 2.4 Moodle automatically sends X-UA-Compatible edge header, this should prevent Internet Explorer from switching to quirks or compatibility modes (MDL-36524). There is also a new workaround for intranet servers which previously identified recent IE browsers as IE7. (MDL-36481)

===SVG icons===

Most modern browsers support SVG icons. The benefit is that SVG scales perfectly to any screen resolution or zoom. It is now possible to add icons in SVG format to pix directories, Moodle uses SVG in supported browsers and PNG in legacy browsers. (MDL-22955)

Please note that IE9 does not handle scaling of standard SVG icons properly, you may have to manually execute a special script from theme/base/cli/svgtool.php to alter the icons to be compatible with buggy IE9. (MDL-36436)

==What's new in 2.0==

The theme system was completely redesigned in Moodle 2.0. Known issues have been addressed and new features have been added to meet community requests.

Unfortunately it was not possible to maintain backward compatibility, so all Moodle 1.x themes need to be recreated for Moodle 2.0.

Major changes include:
* Clearer and more consistent CSS classes and IDs throughout all pages in Moodle
* Introduction of layout files (templates) describing overall layout HTML for many different types of pages in Moodle.
* Introduction of renderers, which produce the smaller "parts" of a HTML page. Advanced themes can choose to override these too if they choose.
* Introduction of standard methods for adding Javascript to themes.
* Easier control over icons and images in Moodle.
* The old "standard" theme has been split into two themes:
**'''base''' - contains absolutely basic layout, and
**'''standard''' - which adds CSS to the base theme to make it look like the old standard theme.
* Performance tuning: In normal production mode CSS files are combined into a single optimised file, and both CSS and JavaScript files are minimised to ensure there are no wasted connections or traffic. Files are heavily cached, but also versioned, so that users never need to clear their caches.

==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. (If you know Moodle 1.9, it's like a combination of header.html and footer.html).
# '''The base theme''' - is not intended to be used for production sites. It sets up the simplest possible generic layout and includes only CSS essential to that layout ''or'' to Moodle as a whole. It tries not to make any unnecessary rules and makes as few assumptions as possible. It's the perfect base on which to start designing a theme, as there are very few colours, borders, margins, and alignments to override. You can just start adding what you need.

===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 classes and functions that are used by theme
|-
| /
| renderers.php
| Contains any custom renderers for the theme.
|-
| /
| settings.php
| Contains custom theme settings. These local settings are defined by the theme allowing the theme user 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).
|-
| /javascript/
| *.js
| All specialty JavaScript files the theme requires should be located in here.
|-
| /lang/
|
| Any special language files the theme requires should be located in here.
|-
| /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.
|}

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.

==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 a basic theme configuration file and the different bits that make it up:
<code php>
$THEME->name = 'newtheme';

$THEME->parents = array(
'base'
);

$THEME->sheets = array(
'admin',
'blocks',
'calendar',
'course',
'grade',
'message',
'question',
'user'
);

$THEME->layouts = array(
'base' => array(
'theme' => 'newtheme',
'file' => 'general.php',
'regions' => array(),
),
'standard' => array(
'theme' => 'newtheme',
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
)
//.......
);

$THEME->javascripts_footer = array(
'navigation'
);
</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->parents : This defines the themes that the theme will extend. In this case it is extending only the base theme.

; $THEME->sheets : An array containing the names of the CSS stylesheets to include for this theme. 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->layouts : In this example, two layouts have been defined to override the layouts from the base theme. For more information see the [[#Layouts|layouts]] section below.

; $THEME->javascripts_footer : The final setting is to include a JavaScript file. Much like stylesheets, you only need to provide the files name. Moodle will assume it is in your themes JavaScript directory and be a .js file.

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

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.

===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 within the themes provided in the standard install by Moodle there is a very clear organisation of CSS.

First is the pagelayout.css file. This contains the CSS required to give the layouts their look and feel. It doesn't contain any rules that affect the content generated by Moodle.

Next is the core.css file. If you open up core you will notice that it contains all manner of general (usually simple) rules that don't relate to a specific section of Moodle but to Moodle as a whole.

There can also be rules that relate to specific sections. However, this is done only when there are only a handful of rules for that section. These small clusters of rules are grouped together and separated by comments identifying for which section each relates.

Finally there are all the other CSS files, you will notice that there is a file for each section of Moodle that has a significant collection of rules.

:For those who are familiar with Moodle 1.9 theme's, this organisation will be a big change. In 1.9, CSS was organised by its nature (for example: colours, layout, other).

===How to write effective CSS rules within Moodle===
In Moodle 2.0, 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 ====
As of Moodle 2.0 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.

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 html4strict><body id=”page-mod-forum-view” class=”path-mod path-mod-forum” /></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.

==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. The standard theme in Moodle is a good example of this as it extends the base theme simply adding CSS to achieve its look and feel.

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' => 'base',
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post'
)
)
</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 base theme. If you take a look first at theme/base/config.php you will notice that several layouts specify options '''nonavbar''' and '''nofooter''' which can both be set to either true or false. Then if we take a look at theme/base/layout/general.php you will spot lines like the following:
<code php>
<?php
$hasnavbar = (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar());
$hasfooter = (empty($PAGE->layout_options['nofooter']));
?>
............
<?php if ($hasnavbar) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</code>
What you are seeing here is the use of those settings from the layout within the layout file. In this case it is being used to toggle the display of the navigation bar and page footer.

==Layout files==
A layout file is a file that contains the core HTML structure for a layout including the header, footer, content and block regions. For those of you who are familiar with themes in Moodle 1.9 this is simply header.html and footer.html combined. Of course it is not all HTML, there are bits of HTML and content that Moodle needs to put into the page, within each layout file this will be done by a couple of simple PHP calls to get bits and pieces including content.

Before learning more it is good to understand the two primary objects that will be used in your layout files: $OUTPUT and $PAGE.

'''$OUTPUT''' is an instance of the <code>core_renderer</code> class which is defined in lib/outputrenderers.php. Each method is clearly documented there, along with which is appropriate for use within the layout files.

'''$PAGE''' is an instance of the <code>moodle_page</code> class defined in lib/pagelib.php. Most of the things you will want to use are the properties that are all documented at the top of the file. If you are not familiar with PHP properties, you access them like $PAGE->activityname, just like fields of an ordinary PHP object. (However, behind the scenes the value you get is produced by calling a function. Also, you cannot change these values, they are '''read-only'''. However, you don't need to understand all that if you are just using these properties in your theme.)

The following is a very simple layout file to illustrate the different bits that make it up:
<code php>
<?php echo $OUTPUT->doctype() ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title ?></title>
<?php echo $OUTPUT->standard_head_html() ?>
</head>
<body id="<?php p($PAGE->bodyid) ?>" class="<?php p($PAGE->bodyclasses) ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<table id="page">
<tr>
<td colspan="3">
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
if (method_exists($OUTPUT, 'user_menu)) {
echo $OUTPUT->user_menu(); // user menu, for Moodle 2.8
} else {
echo $OUTPUT->login_info(); // login_info, Moodle 2.7 and before
}
echo $PAGE->headingmenu;
?></div>
</td>
</tr>
<tr>
<td>
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</td>
<td>
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</td>
<td>
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</td>
</tr>
<tr>
<td colspan="3">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</td>
</tr>
</table>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>

We assume you know enough HTML to understand the basic structure above, but let's explain the PHP code since that is less obvious.
<code php>
<?php echo $OUTPUT->doctype() ?>
</code>
This occurs at the VERY top of the page, it must be the first bit of output and is responsible for adding the (X)HTML document type definition to the page. This of course is determined by the settings of the site and is one of the things that the theme designer has no control over.

<code php>
<html <?php echo $OUTPUT->htmlattributes() ?>>
</code>
Here we have started writing the opening html tag and have asked Moodle to give us the HTML attributes that should be applied to it. This again is determined by several settings within the actual HTML install.

<code php>
<?php echo $PAGE->title ?>
</code>
This gets us the title for the page.

<code php>
<?php echo $OUTPUT->standard_head_html() ?>
</code>
This very important call gets us the standard head HTML that needs to be within the HEAD tag of the page. This is where CSS and JavaScript requirements for the top of the page will be output as well as any special script or style tags.

<code php>
<body id="<?php p($PAGE->bodyid); ?>" class="<?php p($PAGE->bodyclasses); ?>">
</code>
Much like the html tag above we have started writing the body tag and have asked for Moodle to get us the desired ID and classes that should be applied to it.

<code php>
<h1 class="headermain"><?php echo $PAGE->heading; ?></h1>
<div class="headermenu"><?php echo $OUTPUT->login_info(); echo $PAGE->headingmenu; ?></div>
</code>
Here we are creating the header for the page. In this case we want the heading for the page, we want to display the login information which will be the current users username or a link to log in if they are not logged in, and we want the heading menu if there is one.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</code>
Here we get the HTML to display the blocks that have been added to the page. In this case we have asked for all blocks that have been added to the area labelled ''side-pre''.

<code php>
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</code>
This is one of the most important calls within the file, it determines where the actual content for the page gets inserted.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</code>
Here we get the HTML to display the blocks that have been added to the page. In this case we have asked for all blocks that have been added to the area labelled ''side-post''.

<code php>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</code>
This final bit of code gets the content for the footer of the page. It gets the login information which is the same as in the header, a home link, and the standard footer HTML which like the standard head HTML contains all of the script and style tags required by the page and requested to go in the footer.

'''''Note''''': Within Moodle 2.0 most of the JavaScript for the page will be included in the footer. This greatly helps reduce the loading time of the page.

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 'standard' theme has a language file called lang/en/theme_standard.php.

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

<code php>
$string['pluginname'] = 'Standard';
$string['region-side-post'] = 'Right';
$string['region-side-pre'] = 'Left';
$string['choosereadme'] = 'This theme is a very basic white theme, with a minimum amount of
CSS added to the base theme to make it actually usable.';
</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 HTML, such as if you wanted to use them within a layout file.
<code php>
<img src="<?php echo $OUTPUT->pix_url('imageone', 'theme');?>" alt="" />
<img src="<?php echo $OUTPUT->pix_url('subdir/imagetwo', 'theme');?>" alt="" />
</code>

'''DO NOT''' include the image file extension. Moodle will work it out automatically and it will not work if you do include it.

In this case rather than writing out the URL to the image we use a method of Moodle's output library. 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.

The following is how you would use the images from within CSS 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 module images we need a '''pix_mod''' directory.

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.

==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 'base' theme.

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

==Appendix A==
===Theme options as of 8th April 2014===

{| 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.
|-
| $THEME->'''csspostprocess'''
| Allows the user to provide the name of a function that all CSS should be passed to before being delivered.
|-
| $THEME->'''doctype'''
| The doctype of the served documents.
|-
| $THEME->'''editor_sheets'''
| An array of stylesheets to include within the body of the 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->'''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->'''filter_mediaplugin_colors'''
| Used to control the colours used in the small media player for the filters
|-
| $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)
|-
| $THEME->'''javascripts_footer'''
| As above but will be included in the page footer.
|-
| $THEME->'''larrow'''
| Overrides the left arrow image used throughout Moodle
|-
| $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->'''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->'''rarrow'''
| Overrides the right arrow image used throughout Moodle
|-
| $THEME->'''renderfactory'''
| Sets a custom render factory to use with the theme, used when working with custom renderers.
|-
| $THEME->'''resource_mp3player_colors'''
| Controls the colours for the MP3 player
|-
| $THEME->'''sheets'''
| An array of stylesheets to include for this theme. Should be located in the theme's style directory.
|-
| $THEME->'''supportscssoptimisation'''
| When set to 'FALSE' then the theme will not be affected by the 'CSS Optimiser'. The 'CSS Optimiser' is enabled in Development > Experimental > Experimental settings. When it is enabled CSS will be run through an optimisation process before being cached. The optimiser processes the CSS removing duplicate rules and styles, as well as white space removable and reformatting. Please note turning this on at the same time as theme designer mode is awful for performance but will help theme designers create optimised CSS.
|-
| $THEME->'''yuicssmodules'''
| An array of YUI CSS modules to be included.
|}

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

==See also==
* [[Theme changes in 2.0]]
* [[Adding courses and categories to the custom menu]]
* [[Making a horizontal dock]]
* [[Adding theme upgrade code]]
* [[Styling and customising the dock]]
* [[Changing topic or weekly outline to Page heading]]
* [[jQuery]]

===Moodle 2.2+===

* [[Themes 2.2 how to clone a Moodle 2.2 theme]]

===Moodle Bootstrap Themes - Moodle 2.5+===

* [[Themes 2.5 How to copy and customise the Simple (bootstrap) theme]]

[[de:Designs 2.0]]
[[es:Temas 2.0]]

[[Category:Plugins]]

Creating a theme

2014-12-03T09:17:35Z

Jethac: /* The page header */

{{Template:Themes}}This document describes how to create a theme for Moodle 2.x.x. It assumes you have some understanding of how themes within Moodle work as well as a good understanding of HTML and CSS.

===Theme designer mode===

Under normal operation Moodle does several things in the name of performance, one of these is to combine all of the CSS into one file, minimize it, cache it on the server, and then serve it. After the first request the cached version is served to greatly improve page performance.

What this means for you as a themer? When you make changes they will not be seen immediately. In fact you will need to tell Moodle to rebuild the cache that it is serving.
This isn't practical for designing themes of course so the '''theme designer mode''' was added. When enabled it tells Moodle not to combine or cache the CSS that gets delivered. This has the downside that page load times will take significantly longer, however you will see your changes immediately every time.

Theme designer mode may be enabled via ''Administration > Appearance > Themes > [[Theme settings]]''.

'''Warning''': Internet Explorer versions 6 and 7 have BIG problems when a site attempts to link to more than 31 stylesheets, in which case either a limited number or no styles get applied. Because Moodle sends up all of the CSS all of the time with theme designer mode turned on there is a very high chance you will get more than 31 stylesheets being included. This will, of course, cause major problems for Internet Explorer until theme designer mode is turned off.

==Getting started==

The first thing you need to do is create the directories and files you will be using, the first thing to create is the actual directory for your theme. This should be the name of your theme, in my case it's 'excitement'. The directory should be located within the theme directory of Moodle, ./moodle/theme/excitement/ will be the directory I create.

Now within that directory we can immediately create several files that we know we are going to need.

So the files that we want to create are:
; config.php : All of our settings will go here.
; /style/ : This directory will contain all of our stylesheets.
; /style/excitement.css : All of our css will go in here.
; /pix/ : Into this directory we'll put a screen shot of our theme as well as our favicon and any images we use in CSS.
; /layout/ : Our layout files will end up in this directory.
; /layout/standard.php : This will be our one basic layout file.
; /lang/en/ : The file we put here will make our theme name show properly on the Theme Selector page. You need a few standard entries. Copy the one from the Standard theme and modify is easiest.

So after this setup step you should have a directory structure similar to what is shown below.

[[image:Learn_to_theme_01.jpg]]

==Configuring our theme==

Open config.php in your favourite editor and start by adding the opening PHP tags '''<nowiki><?php</nowiki>'''.

Now we need to add the settings:

<code php>
$THEME->name = 'excitement';
</code>
Very simply this tells Moodle the name of your theme, and if you ever have several config.php files open this will help you identify which one you are looking at.

Next, the parents for this theme.
<code php>
$THEME->parents = array('base');
</code>
This tells Moodle that my new theme ''`excitement`' wants to extend the base theme.

A theme can extend any number of themes. Rather than creating an entirely new theme and copying all of the CSS, you can simply create a new theme, extend the theme you like and just add the changes you want to your theme.

Also worth noting is the purpose of the base theme: it provides us with a basic layout and just enough CSS to make everything fall into place.

Now we will tell Moodle about our stylesheets:
<code php>
$THEME->sheets = array('excitement');
</code>

The final thing we need to add into our theme's config.php file is the definition of the layouts for our theme:
(in the code below, replace 'general.php' with 'standard.php' because that is the file that is previously created)
<code php>
$THEME->layouts = array(
// Most backwards compatible layout without the blocks - this is the layout used by default
'base' => array(
'file' => 'general.php',
'regions' => array(),
),
// Standard layout with blocks, this is recommended for most pages with general information
'standard' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
),
// part of course, typical for modules - default page layout if $cm specified in require_login()
'incourse' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
),
// Server administration scripts.
'admin' => array(
'file' => 'general.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
// My dashboard page
'mydashboard' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
),
'login' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('langmenu'=>true),
),

// Pages that appear in pop-up windows - no navigation, no blocks, no header.
'popup' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true, 'nologininfo'=>true, 'nocourseheaderfooter'=>true),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.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(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true, 'nocourseheaderfooter'=>true),
),
// Used during upgrade and install, and for the 'This site is undergoing maintenance' message.
// This must not have any blocks, and it is good idea if it does not have links to
// other places - for example there should not be a home link in the footer...
'maintenance' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('noblocks'=>true, 'nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true, 'nocourseheaderfooter'=>true),
),
// Should display the content and basic headers only.
'print' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('noblocks'=>true, 'nofooter'=>true, 'nonavbar'=>false, 'nocustommenu'=>true, 'nocourseheaderfooter'=>true),
),
// The pagelayout used when a redirection is occuring.
'redirect' => array(
'file' => 'embedded.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true, 'nocourseheaderfooter'=>true),
),
// The pagelayout used for reports.
'report' => array(
'file' => 'report.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
// The pagelayout used for safebrowser and securewindow.
'secure' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true, 'nologinlinks'=>true, 'nocourseheaderfooter'=>true),
),
);

/** List of javascript files that need to be included on each page */
$THEME->javascripts = array();
$THEME->javascripts_footer = array();

</code>

What you are looking at is the different layouts for our theme. Why are there so many? Because, that is how many there are in Moodle. There is one for every general type of page. With my ''`excitement`'' theme I have chosen to use my own layout. Unless there was a specific reason to do so, normally you would not need to create your own layouts, you could extend the base theme, and use its layouts, meaning you would only have to write CSS to achieve your desired look.

For each layout above, you will notice the following four things are being set:
; file : This is the name of the layout file we want to use, it should always be located in the above themes layout directory. For us this is of course standard.php as we only have one layout file.
; regions : This is an array of block regions that our theme has. Each entry in here can be used to put blocks in when that layout is being used.
; defaultregion : If a layout has regions it should have a default region, this is where blocks get put when first added. It is also where the "add block" block is shown when editing is on.
; options : These are special settings, anything that gets put into the options array is available later on when we are writing our layout file.

There are additional settings that can be defined in the config.php file - see [[Themes 2.0|Themes 2.0]] for the full list.

==Configuring the language file==
Open theme_base.php file from '''base/lang/en/theme_base.php'''

Save it as '''excitement/lang/en/theme_excitement.php'''.

Change
<code php>
$string['pluginname'] = 'Base';
</code>
to
<code php>
$string['pluginname'] = 'Excitement';
</code>

After making these changes and perhaps clearing theme caches and/or purging all caches, the new theme name should now show properly in the Theme Selector: ''Site Administration > Appearance > Themes > Theme Selector''

You can also edit the theme description:

<code php>
$string['choosereadme'] = 'Write your theme description here.';
</code>

You need to leave the following two lines in place (you can change the wording if you need to) to avoid notices when editing blocks etc.:

<code php>
$string['region-side-post'] = 'Right';
$string['region-side-pre'] = 'Left';
</code>

==Writing the layout file==

The excitement theme has just one layout file.

The downside of this is that I have to make the layout file do everything I want which means I need to make use of some options (as defined in the layouts in config.php).

The upside is that I only need to maintain one file.

Other than maintenance, using multiple layout files provides many advantages to real world themes in that you can easily tweak and customise specific layouts to achieve the goals of the organisation using the theme.

Before learning more it is good to understand the two primary objects that will be used in your layout files: $OUTPUT and $PAGE.

'''$OUTPUT''' is an instance of the <code>core_renderer</code> class which is defined in lib/outputrenderers.php. Each method is clearly documented there, along with which is appropriate for use within the layout files.

'''$PAGE''' is an instance of the <code>moodle_page</code> class defined in lib/pagelib.php. Most of the things you will want to use are the properties that are all documented at the top of the file. If you are not familiar with PHP properties, you access them like $PAGE->activityname, just like fields of an ordinary PHP object. (However, behind the scenes the value you get is produced by calling a function. Also, you cannot change these values, they are '''read-only'''. However, you don't need to understand all that if you are just using these properties in your theme.)

So lets start writing standard.php, the layout file for my ''`excitement`'' theme.

===The top of the layout file===

<code php>
<?php
$hassidepre = $PAGE->blocks->region_has_content('side-pre', $OUTPUT);
$hassidepost = $PAGE->blocks->region_has_content('side-post', $OUTPUT);
echo $OUTPUT->doctype(); ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title ?></title>
<?php echo $OUTPUT->standard_head_html() ?>
</head>
</code>

Lets look at the code that goes into this section:
<code php>
<?php
echo $OUTPUT->doctype(); ?>
</code>
This is very important and is required to go at the very top of the page. This tells Moodle to print out the document type tag that is determined by the settings within Moodle.

<code php>
<html <?php echo $OUTPUT->htmlattributes() ?>>
</code>
Here we open the HTML tag and then ask Moodle to print the attributes that should go inside it.

<code php>
<title><?php echo $PAGE->title ?></title>
</code>
Simply creates the title tag and asks Moodle to fill it in.

<code php>
<?php echo $OUTPUT->standard_head_html() ?>
</code>
Here we are asking Moodle to print all of the other tags and content that need to go into the head. This includes stylesheets, script tags, and inline JavaScript code.

===The page header===

<code php>
<body id="<?php p($PAGE->bodyid); ?>" class="<?php p($PAGE->bodyclasses); ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<div id="page">
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
<div id="page-header">
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
if (method_exists($OUTPUT, 'user_menu')) {
echo $OUTPUT->user_menu(); // user menu, for Moodle 2.8
} else {
echo $OUTPUT->login_info(); // login_info, Moodle 2.7 and before
}
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div>
<?php } ?>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</div>
<?php } ?>
</code>

So there is a bit more going on here obviously.

<code php>
<body id="<?php p($PAGE->bodyid); ?>" class="<?php p($PAGE->bodyclasses); ?>">
</code>
Again much like what we did for the opening HTML tag in the head we have started writing the opening body tag and are then asking Moodle to give us the ID we should use for the body tag as well as the classes we should use.

<code php>
<?php echo $OUTPUT->standard_top_of_body_html() ?>
</code>
This very important call writes some critical bits of JavaScript into the page. It should always be located after the body tag as soon as possible.

<code php>
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
......
<?php } ?>
</code>
Here we are checking whether or not we need to print the header for the page. There are three checks we need to make here:
# '''$PAGE->heading''' : This checks to make sure that there is a heading for the page. This will have been set by the script and normally describes the page in a couple of words.
# '''empty($PAGE->layout_options['nonavbar'])''' : Now this check is looking at the layout options that we set in our config.php file. It is looking to see if the layout set 'nonavbar' => true.
# '''$PAGE->has_navbar()''' The third check is to check with the page whether it has a navigation bar to display.
If either there is a heading for this page or there is a navigation bar to display then we will display a heading.

Leading on from this lets assume that there is a header to print.
<code php>
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
.....
<?php } ?>
</code>
This line is simply saying if the page has a heading print it. In this case we run the first check above again just to make sure there is a heading, we then open a heading tag that we choose and ask the page to print the heading.

<code php>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div>
</code>
Here we are looking to print the menu and content that you see at the top of the page (usually to the right). We start by getting Moodle to print the login information for the current user. If the user is logged in this will be their name and a link to their profile, if not then it will be a link to login.

Next we check our page options to see whether a language menu should be printed. If in the layout definition within config.php it sets '''langmenu => true''' then we will print the language menu, a drop down box that lets the user change the language that Moodle displays in.

Finally the page also has a heading menu that can be printed. This heading menu is special HTML that the page you are viewing wants to add. It can be anything from drop down boxes to buttons and any number of each.

<code php>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</code>
The final part of the header.

Here we want to print the navigation bar for the page if there is one. To find out if there is one we run checks number 2 and 3 again and proceed if they pass.

Assuming there is a header then there are two things that we need to print. The first is the navigation bar. This is a component that the OUTPUT library knows about. The second is a button to show on the page.

In both cases we choose to wrap them in a div tag with a class attribute to enable theming on those elements.

Well that is it for the header. There is a lot of PHP compared to the other sections of the layout file but it does not change and can be copied and pasted between themes.

===The page content===

I am going with the default two block regions plus the main content.

Because I have based this theme and layout file on the base theme the HTML looks a little intense. This is because it is a floating div layout where the content comes first and then we get the columns (even though one column will be to the left of the content.) Don't worry too much about it. When it comes to writing your own theme you can go about it as you choose.

<code php>
<div id="page-content">
<div id="region-main-box">
<div id="region-post-box">
<div id="region-main-wrap">
<div id="region-main">
<div class="region-content">
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</div>
</div>
</div>
<?php if ($hassidepre) { ?>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<?php } ?>

<?php if ($hassidepost) { ?>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
<?php } ?>
</div>
</div>
</div>
</code>

In regards to PHP this section is very easy. There are only three lines for the whole section one to get the main content and one for each block region.
<code php>
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</code>
This line prints the main content for the page.
PLEASE NOTE: In Moodle 2.2 onwards "core_renderer::MAIN_CONTENT_TOKEN" changed to "$OUTPUT->main_content()".

<code php>
<?php if ($hassidepre) { ?>
....
<?php } ?>
</code>
These lines of code check the variables we created earlier on to decide whether we should show the pre block region. If you try to display a block region that isn't there or has no content then Moodle will give you an error message so these lines are very important.

For those who get an error message if it is "unknown block region side-pre" or "unknown block region side-post" then this is the issue you are experiencing. Simply add the following lines and all will be fine.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</code>
This line gets all of the blocks and more particularly the content for the block region '''side-pre'''. This block region will be displayed to the left of the content.

<code php>
<?php if ($hassidepost) { ?>
....
<?php } ?>
</code>
Again we should make this check for every block region as there are some pages that have no blocks what-so-ever.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</code>
Here we are getting the other block region '''side-post''' which will be displayed to the right of the content.

===The page footer===
Here we want to print the footer for the page, any content required by Moodle, and then close the last tags.
<code php>
<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</div>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>

The section of code is responsible for printing the footer for the page.
<code php>
<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</code>
The first thing we do before printing the footer is check that we actually want to print it. This is done by checking the options for the layout as defined in the config.php file. If '''nofooter => true''' is set the we don't want to print the footer and should skip over this body of code.

Assuming we want to print a footer we proceed to create a div to house its content and then print the bits of the content that will make it up.
There are four things that the typical page footer will want to print:
; echo page_doc_link(get_string('moodledocslink')) : This will print a link to the Moodle.org help page for this particular page.
; echo $OUTPUT->login_info(); : This is the same as at the top of the page and will print the login information for the current user.
; echo $OUTPUT->home_link(); : This prints a link back to the Moodle home page for this site.
; echo $OUTPUT->standard_footer_html(); : This prints special HTML that is determined by the settings for the site. Things such as performance information or debugging will be printed by this line if they are turned on.

And the final line of code for our layout file is:
<code php>
<?php echo $OUTPUT->standard_end_of_body_html(); ?>
</code>
This is one of the most important lines of code in the layout file. It asks Moodle to print any required content into the page, and there will likely be a lot although most of it will not be visual.

It will instead be things such as inline scripts and JavaScript files required to go at the bottom of the page. If you forget this line its likely no JavaScript will work!

We've now written our layout file and it is all set to go. The complete source is below for reference. Remember if you want more practical examples simply look at the layout files located within the layout directory of other themes.

<code php>
<?php
$hassidepre = $PAGE->blocks->region_has_content('side-pre', $OUTPUT);
$hassidepost = $PAGE->blocks->region_has_content('side-post', $OUTPUT);
echo $OUTPUT->doctype() ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title; ?></title>
<link rel="shortcut icon" href="<?php echo $OUTPUT->pix_url('favicon', 'theme')?>" />
<?php echo $OUTPUT->standard_head_html() ?>
</head>

<body id="<?php p($PAGE->bodyid); ?>" class="<?php p($PAGE->bodyclasses); ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<div id="page">
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
<div id="page-header">
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div><?php } ?>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</div>
<?php } ?>

<div id="page-content">
<div id="region-main-box">
<div id="region-post-box">
<div id="region-main-wrap">
<div id="region-main">
<div class="region-content">
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</div>
</div>
</div>
<?php if ($hassidepre) { ?>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<?php } ?>

<?php if ($hassidepost) { ?>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
<?php } ?>
</div>
</div>
</div>

<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</div>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>

==Adding some CSS==
With config.php and standard.php both complete the theme is now usable and starting to look like a real theme, however if you change to it using the theme selector you will notice that it still lacks any style.

This of course is where CSS comes in. When writing code Moodle developers are strongly encouraged to not use inline styles anywhere. This is fantastic for us as themers because there is nothing (or at least very little) in Moodle that cannot be styled using CSS.

===Moodle CSS basics===

In Moodle 2.0 all of the CSS for the whole of Moodle is delivered all of the time! This was done for performance reasons. Moodle now reads in all of the CSS, combines it into one file, shrinks it removing any white space, caches it, and then delivers it.

'''What this means for you as a themer?'''

You will need to write good CSS that won't clash with any other CSS within Moodle.

Moodle is so big and complex,there is no way to ensure that classes don't get reused. What we can control however is the classes and id that get added to the body tag for every page. When writing CSS it is highly encouraged to make full use of these body classes, using them will help ensure the CSS you write has the least chance of causing conflicts.

You should also take the time to look at how the Moodle themes use CSS. Look at their use of the body classes and how they separate the CSS for the theme into separate files based on the region of Moodle it applies to.

Check out [[Themes 2.0|Themes 2.0]] and [[CSS coding style]] for more information about writing good CSS.

===Starting to write excitement.css===

<code css>
a {
text-decoration: none;
}

.addcoursebutton .singlebutton {
text-align: center;
}

h1.headermain {
color: #fff;
}

h2.main {
border-bottom: 3px solid #013D6A;
color: #013D6A;
text-align: center;
}

h2.headingblock {
font-size: 18pt;
margin-top: 0;
background-color: #013D6A;
color: #FFF;
text-align: center;
}

#page-header {
background-color: #013D6A;
}

#page-header .headermenu {
color: #FFF;
}

#page-header .headermenu a {
color: #FDFF2A;
}

.navbar {
padding-left: 1em;
}

.breadcrumb li {
color: #FFF;
}

.breadcrumb li a {
color: #FFF;
}

.block {
background-color: #013D6A;
}

.block .header .title {
color: #FFF;
}

.block .header .title .block_action input {
background-color: #FFF;
}

.block .content {
border: 1px solid #000;
padding: 5px;
background-color: #FFF;
}

.block .content .block_tree p {
font-size: 80%;
}

.block_settings_navigation_tree .content .footer {
text-align: center;
}

.block_settings_navigation_tree .content .footer .adminsearchform {
margin-left: 5%;
width: 90%;
font-size: 9pt;
}

.block_settings_navigation_tree .content .footer .adminsearchform #adminsearchquery {
width: 95%;
}

.block_calendar_month .content .calendar-controls a {
color: #013D6A;
font-weight: bold;
}

.block_calendar_month .content .minicalendar td {
border-color: #FFF;
}

.block_calendar_month .content .minicalendar .day {
color: #FFF;
background-color: #013D6A;
}

.block_calendar_month .content .minicalendar .day a {
color: #FFF000;
}

.block_calendar_month .content .minicalendar .weekdays th {
border-width: 0;
font-weight: bold;
color: #013D6A;
}

.block_calendar_month .content .minicalendar .weekdays abbr {
border-width: 0;
text-decoration: none;
}
</code>
[[image:Learn_to_theme_02.jpg|400px|thumb|Excitement theme screenshot]]
This isn't all of the CSS for the theme, but just enough to style the front page when the user is not logged in.
Remember this theme extends the base theme so there is already CSS for layout as well.

Note:
* The CSS is laid out in a single line format. This is done within the core themes for Moodle. It makes it quicker to read the selectors and see what is being styled.
* I have written my selectors to take into account the structure of the HTML (more than just the one tag I want to style). This helps further to reduce the conflicts that I may encounter.
* I use generic classes like ''.sideblock'' only where I want to be generic, as soon as I want to be specific I use the unique classes such as ''.block_calendar_month''

<br style="clear:right;" />

===Using images within CSS===

I will add two image files to the pix directory of my theme:
; /theme/excitement/pix/background.png : This will be the background image for my theme.
; /theme/excitement/pix/gradient.jpg : This will be a gradient I use for the header and headings.
I quickly created both of these images using gimp and simply saved them to the pix directory.
<code css>
html {
background-image: url([[pix:theme|background]]);
}

h2.headingblock,
#page-header,
.sideblock,
.block_calendar_month .content .minicalendar .day {
background-image: url([[pix:theme|gradient]]);
background-repeat: repeat-x;
background-color: #0273C8;
}
</code>
[[image:Learn_to_theme_03.jpg‎|400px|thumb|Excitement theme screenshot]]
The CSS above is the two new rules that I had to write to use my images within CSS.

The first rule sets the background image for the page to background.png

The second rule sets the background for headings, and the sideblocks to use gradient.jpg

You will notice that I did not need to write a path to the image. This is because Moodle has this special syntax that can be used and will be replaced when the CSS is parsed before delivery.
The advantage of using this syntax over writing the path in is that the path may change depending on where you are or what theme is being used.

Other themers may choose to extend your theme with their own; if you use this syntax then all they need to do to override the image is to create one with the same name in their themes directory.

You will also notice that I don't need to add the image files extension. This is because Moodle is smart enough to work out what extension the file uses. It also allows themers to override images with different formats.

<br style="clear:right" />
The following is the complete CSS for my theme:
<div style="overflow:auto;height:860px;">
<code css>
a {text-decoration: none;}
.addcoursebutton .singlebutton {text-align: center;}

h1.headermain {color: #fff;}
h2.main {border-bottom: 3px solid #013D6A;color: #013D6A;text-align: center;}
h2.headingblock {font-size: 18pt;margin-top: 0;background-color: #013D6A;color: #FFF;text-align: center;}
#page-header {background-color: #013D6A;border-bottom:5px solid #013D6A;}
#page-header .headermenu {color: #FFF;}
#page-header .headermenu a {color: #FDFF2A;}

.sideblock {background-color: #013D6A;}
.sideblock .header .title {color: #FFF;}
.sideblock .header .title .block_action input {background-color: #FFF;}
.sideblock .content {border: 1px solid #000;padding: 5px;background-color: #FFF;}
.sideblock .content .block_tree p {font-size: 80%;}

.block_settings_navigation_tree .content .footer {text-align: center;}
.block_settings_navigation_tree .content .footer .adminsearchform {margin-left: 5%;width: 90%;font-size: 9pt;}
.block_settings_navigation_tree .content .footer .adminsearchform #adminsearchquery {width: 95%;}

.block_calendar_month .content .calendar-controls a {color: #013D6A;font-weight: bold;}
.block_calendar_month .content .minicalendar td {border-color: #FFF;}
.block_calendar_month .content .minicalendar .day {color: #FFF;background-color: #013D6A;}
.block_calendar_month .content .minicalendar .day a {color: #FFF000;}
.block_calendar_month .content .minicalendar .weekdays th {border-width: 0;font-weight: bold;color: #013D6A;}
.block_calendar_month .content .minicalendar .weekdays abbr {border-width: 0;text-decoration: none;}

html {background-image:url([[pix:theme|background]]);}

h2.headingblock,
#page-header,
.sideblock,
.block_calendar_month .content .minicalendar .day {background-image:url([[pix:theme|gradient]]);
background-repeat:repeat-x;background-color: #0273C8;}
</code>
</div>

==Adding a screenshot and favicon==
The final thing to do at this point is add both a screenshot for this theme as well as a favicon for it.
The screenshot will be shown in the theme selector screen and should be named ''screenshot.jpg''.
The favicon will be used when someone bookmarks this page.
Both images should be located in your themes pix directory as follows:
* /theme/excitement/pix/screenshot.jpg
* /theme/excitement/pix/favicon.ico

In the case of my theme I have taken a screenshot and added it to that directory, and because I don't really want to do anything special with the favicon I have copied it from /theme/base/pix/favicon.ico so that at least it will be recognisable as Moodle.

[[es:Desarollo:Temas 2.0 creando tu primer tema]]

Creating a theme

2014-12-03T09:17:11Z

Jethac: /* The page header */

{{Template:Themes}}This document describes how to create a theme for Moodle 2.x.x. It assumes you have some understanding of how themes within Moodle work as well as a good understanding of HTML and CSS.

===Theme designer mode===

Under normal operation Moodle does several things in the name of performance, one of these is to combine all of the CSS into one file, minimize it, cache it on the server, and then serve it. After the first request the cached version is served to greatly improve page performance.

What this means for you as a themer? When you make changes they will not be seen immediately. In fact you will need to tell Moodle to rebuild the cache that it is serving.
This isn't practical for designing themes of course so the '''theme designer mode''' was added. When enabled it tells Moodle not to combine or cache the CSS that gets delivered. This has the downside that page load times will take significantly longer, however you will see your changes immediately every time.

Theme designer mode may be enabled via ''Administration > Appearance > Themes > [[Theme settings]]''.

'''Warning''': Internet Explorer versions 6 and 7 have BIG problems when a site attempts to link to more than 31 stylesheets, in which case either a limited number or no styles get applied. Because Moodle sends up all of the CSS all of the time with theme designer mode turned on there is a very high chance you will get more than 31 stylesheets being included. This will, of course, cause major problems for Internet Explorer until theme designer mode is turned off.

==Getting started==

The first thing you need to do is create the directories and files you will be using, the first thing to create is the actual directory for your theme. This should be the name of your theme, in my case it's 'excitement'. The directory should be located within the theme directory of Moodle, ./moodle/theme/excitement/ will be the directory I create.

Now within that directory we can immediately create several files that we know we are going to need.

So the files that we want to create are:
; config.php : All of our settings will go here.
; /style/ : This directory will contain all of our stylesheets.
; /style/excitement.css : All of our css will go in here.
; /pix/ : Into this directory we'll put a screen shot of our theme as well as our favicon and any images we use in CSS.
; /layout/ : Our layout files will end up in this directory.
; /layout/standard.php : This will be our one basic layout file.
; /lang/en/ : The file we put here will make our theme name show properly on the Theme Selector page. You need a few standard entries. Copy the one from the Standard theme and modify is easiest.

So after this setup step you should have a directory structure similar to what is shown below.

[[image:Learn_to_theme_01.jpg]]

==Configuring our theme==

Open config.php in your favourite editor and start by adding the opening PHP tags '''<nowiki><?php</nowiki>'''.

Now we need to add the settings:

<code php>
$THEME->name = 'excitement';
</code>
Very simply this tells Moodle the name of your theme, and if you ever have several config.php files open this will help you identify which one you are looking at.

Next, the parents for this theme.
<code php>
$THEME->parents = array('base');
</code>
This tells Moodle that my new theme ''`excitement`' wants to extend the base theme.

A theme can extend any number of themes. Rather than creating an entirely new theme and copying all of the CSS, you can simply create a new theme, extend the theme you like and just add the changes you want to your theme.

Also worth noting is the purpose of the base theme: it provides us with a basic layout and just enough CSS to make everything fall into place.

Now we will tell Moodle about our stylesheets:
<code php>
$THEME->sheets = array('excitement');
</code>

The final thing we need to add into our theme's config.php file is the definition of the layouts for our theme:
(in the code below, replace 'general.php' with 'standard.php' because that is the file that is previously created)
<code php>
$THEME->layouts = array(
// Most backwards compatible layout without the blocks - this is the layout used by default
'base' => array(
'file' => 'general.php',
'regions' => array(),
),
// Standard layout with blocks, this is recommended for most pages with general information
'standard' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
),
// part of course, typical for modules - default page layout if $cm specified in require_login()
'incourse' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
),
// Server administration scripts.
'admin' => array(
'file' => 'general.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
// My dashboard page
'mydashboard' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
),
'login' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('langmenu'=>true),
),

// Pages that appear in pop-up windows - no navigation, no blocks, no header.
'popup' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true, 'nologininfo'=>true, 'nocourseheaderfooter'=>true),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.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(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true, 'nocourseheaderfooter'=>true),
),
// Used during upgrade and install, and for the 'This site is undergoing maintenance' message.
// This must not have any blocks, and it is good idea if it does not have links to
// other places - for example there should not be a home link in the footer...
'maintenance' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('noblocks'=>true, 'nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true, 'nocourseheaderfooter'=>true),
),
// Should display the content and basic headers only.
'print' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('noblocks'=>true, 'nofooter'=>true, 'nonavbar'=>false, 'nocustommenu'=>true, 'nocourseheaderfooter'=>true),
),
// The pagelayout used when a redirection is occuring.
'redirect' => array(
'file' => 'embedded.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true, 'nocourseheaderfooter'=>true),
),
// The pagelayout used for reports.
'report' => array(
'file' => 'report.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
// The pagelayout used for safebrowser and securewindow.
'secure' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-pre',
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true, 'nologinlinks'=>true, 'nocourseheaderfooter'=>true),
),
);

/** List of javascript files that need to be included on each page */
$THEME->javascripts = array();
$THEME->javascripts_footer = array();

</code>

What you are looking at is the different layouts for our theme. Why are there so many? Because, that is how many there are in Moodle. There is one for every general type of page. With my ''`excitement`'' theme I have chosen to use my own layout. Unless there was a specific reason to do so, normally you would not need to create your own layouts, you could extend the base theme, and use its layouts, meaning you would only have to write CSS to achieve your desired look.

For each layout above, you will notice the following four things are being set:
; file : This is the name of the layout file we want to use, it should always be located in the above themes layout directory. For us this is of course standard.php as we only have one layout file.
; regions : This is an array of block regions that our theme has. Each entry in here can be used to put blocks in when that layout is being used.
; defaultregion : If a layout has regions it should have a default region, this is where blocks get put when first added. It is also where the "add block" block is shown when editing is on.
; options : These are special settings, anything that gets put into the options array is available later on when we are writing our layout file.

There are additional settings that can be defined in the config.php file - see [[Themes 2.0|Themes 2.0]] for the full list.

==Configuring the language file==
Open theme_base.php file from '''base/lang/en/theme_base.php'''

Save it as '''excitement/lang/en/theme_excitement.php'''.

Change
<code php>
$string['pluginname'] = 'Base';
</code>
to
<code php>
$string['pluginname'] = 'Excitement';
</code>

After making these changes and perhaps clearing theme caches and/or purging all caches, the new theme name should now show properly in the Theme Selector: ''Site Administration > Appearance > Themes > Theme Selector''

You can also edit the theme description:

<code php>
$string['choosereadme'] = 'Write your theme description here.';
</code>

You need to leave the following two lines in place (you can change the wording if you need to) to avoid notices when editing blocks etc.:

<code php>
$string['region-side-post'] = 'Right';
$string['region-side-pre'] = 'Left';
</code>

==Writing the layout file==

The excitement theme has just one layout file.

The downside of this is that I have to make the layout file do everything I want which means I need to make use of some options (as defined in the layouts in config.php).

The upside is that I only need to maintain one file.

Other than maintenance, using multiple layout files provides many advantages to real world themes in that you can easily tweak and customise specific layouts to achieve the goals of the organisation using the theme.

Before learning more it is good to understand the two primary objects that will be used in your layout files: $OUTPUT and $PAGE.

'''$OUTPUT''' is an instance of the <code>core_renderer</code> class which is defined in lib/outputrenderers.php. Each method is clearly documented there, along with which is appropriate for use within the layout files.

'''$PAGE''' is an instance of the <code>moodle_page</code> class defined in lib/pagelib.php. Most of the things you will want to use are the properties that are all documented at the top of the file. If you are not familiar with PHP properties, you access them like $PAGE->activityname, just like fields of an ordinary PHP object. (However, behind the scenes the value you get is produced by calling a function. Also, you cannot change these values, they are '''read-only'''. However, you don't need to understand all that if you are just using these properties in your theme.)

So lets start writing standard.php, the layout file for my ''`excitement`'' theme.

===The top of the layout file===

<code php>
<?php
$hassidepre = $PAGE->blocks->region_has_content('side-pre', $OUTPUT);
$hassidepost = $PAGE->blocks->region_has_content('side-post', $OUTPUT);
echo $OUTPUT->doctype(); ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title ?></title>
<?php echo $OUTPUT->standard_head_html() ?>
</head>
</code>

Lets look at the code that goes into this section:
<code php>
<?php
echo $OUTPUT->doctype(); ?>
</code>
This is very important and is required to go at the very top of the page. This tells Moodle to print out the document type tag that is determined by the settings within Moodle.

<code php>
<html <?php echo $OUTPUT->htmlattributes() ?>>
</code>
Here we open the HTML tag and then ask Moodle to print the attributes that should go inside it.

<code php>
<title><?php echo $PAGE->title ?></title>
</code>
Simply creates the title tag and asks Moodle to fill it in.

<code php>
<?php echo $OUTPUT->standard_head_html() ?>
</code>
Here we are asking Moodle to print all of the other tags and content that need to go into the head. This includes stylesheets, script tags, and inline JavaScript code.

===The page header===

<code php>
<body id="<?php p($PAGE->bodyid); ?>" class="<?php p($PAGE->bodyclasses); ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<div id="page">
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
<div id="page-header">
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
if (method_exists($OUTPUT, 'user_menu)) {
echo $OUTPUT->user_menu(); // user menu, for Moodle 2.8
} else {
echo $OUTPUT->login_info(); // login_info, Moodle 2.7 and before
}
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div>
<?php } ?>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</div>
<?php } ?>
</code>

So there is a bit more going on here obviously.

<code php>
<body id="<?php p($PAGE->bodyid); ?>" class="<?php p($PAGE->bodyclasses); ?>">
</code>
Again much like what we did for the opening HTML tag in the head we have started writing the opening body tag and are then asking Moodle to give us the ID we should use for the body tag as well as the classes we should use.

<code php>
<?php echo $OUTPUT->standard_top_of_body_html() ?>
</code>
This very important call writes some critical bits of JavaScript into the page. It should always be located after the body tag as soon as possible.

<code php>
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
......
<?php } ?>
</code>
Here we are checking whether or not we need to print the header for the page. There are three checks we need to make here:
# '''$PAGE->heading''' : This checks to make sure that there is a heading for the page. This will have been set by the script and normally describes the page in a couple of words.
# '''empty($PAGE->layout_options['nonavbar'])''' : Now this check is looking at the layout options that we set in our config.php file. It is looking to see if the layout set 'nonavbar' => true.
# '''$PAGE->has_navbar()''' The third check is to check with the page whether it has a navigation bar to display.
If either there is a heading for this page or there is a navigation bar to display then we will display a heading.

Leading on from this lets assume that there is a header to print.
<code php>
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
.....
<?php } ?>
</code>
This line is simply saying if the page has a heading print it. In this case we run the first check above again just to make sure there is a heading, we then open a heading tag that we choose and ask the page to print the heading.

<code php>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div>
</code>
Here we are looking to print the menu and content that you see at the top of the page (usually to the right). We start by getting Moodle to print the login information for the current user. If the user is logged in this will be their name and a link to their profile, if not then it will be a link to login.

Next we check our page options to see whether a language menu should be printed. If in the layout definition within config.php it sets '''langmenu => true''' then we will print the language menu, a drop down box that lets the user change the language that Moodle displays in.

Finally the page also has a heading menu that can be printed. This heading menu is special HTML that the page you are viewing wants to add. It can be anything from drop down boxes to buttons and any number of each.

<code php>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</code>
The final part of the header.

Here we want to print the navigation bar for the page if there is one. To find out if there is one we run checks number 2 and 3 again and proceed if they pass.

Assuming there is a header then there are two things that we need to print. The first is the navigation bar. This is a component that the OUTPUT library knows about. The second is a button to show on the page.

In both cases we choose to wrap them in a div tag with a class attribute to enable theming on those elements.

Well that is it for the header. There is a lot of PHP compared to the other sections of the layout file but it does not change and can be copied and pasted between themes.

===The page content===

I am going with the default two block regions plus the main content.

Because I have based this theme and layout file on the base theme the HTML looks a little intense. This is because it is a floating div layout where the content comes first and then we get the columns (even though one column will be to the left of the content.) Don't worry too much about it. When it comes to writing your own theme you can go about it as you choose.

<code php>
<div id="page-content">
<div id="region-main-box">
<div id="region-post-box">
<div id="region-main-wrap">
<div id="region-main">
<div class="region-content">
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</div>
</div>
</div>
<?php if ($hassidepre) { ?>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<?php } ?>

<?php if ($hassidepost) { ?>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
<?php } ?>
</div>
</div>
</div>
</code>

In regards to PHP this section is very easy. There are only three lines for the whole section one to get the main content and one for each block region.
<code php>
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</code>
This line prints the main content for the page.
PLEASE NOTE: In Moodle 2.2 onwards "core_renderer::MAIN_CONTENT_TOKEN" changed to "$OUTPUT->main_content()".

<code php>
<?php if ($hassidepre) { ?>
....
<?php } ?>
</code>
These lines of code check the variables we created earlier on to decide whether we should show the pre block region. If you try to display a block region that isn't there or has no content then Moodle will give you an error message so these lines are very important.

For those who get an error message if it is "unknown block region side-pre" or "unknown block region side-post" then this is the issue you are experiencing. Simply add the following lines and all will be fine.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</code>
This line gets all of the blocks and more particularly the content for the block region '''side-pre'''. This block region will be displayed to the left of the content.

<code php>
<?php if ($hassidepost) { ?>
....
<?php } ?>
</code>
Again we should make this check for every block region as there are some pages that have no blocks what-so-ever.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</code>
Here we are getting the other block region '''side-post''' which will be displayed to the right of the content.

===The page footer===
Here we want to print the footer for the page, any content required by Moodle, and then close the last tags.
<code php>
<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</div>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>

The section of code is responsible for printing the footer for the page.
<code php>
<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</code>
The first thing we do before printing the footer is check that we actually want to print it. This is done by checking the options for the layout as defined in the config.php file. If '''nofooter => true''' is set the we don't want to print the footer and should skip over this body of code.

Assuming we want to print a footer we proceed to create a div to house its content and then print the bits of the content that will make it up.
There are four things that the typical page footer will want to print:
; echo page_doc_link(get_string('moodledocslink')) : This will print a link to the Moodle.org help page for this particular page.
; echo $OUTPUT->login_info(); : This is the same as at the top of the page and will print the login information for the current user.
; echo $OUTPUT->home_link(); : This prints a link back to the Moodle home page for this site.
; echo $OUTPUT->standard_footer_html(); : This prints special HTML that is determined by the settings for the site. Things such as performance information or debugging will be printed by this line if they are turned on.

And the final line of code for our layout file is:
<code php>
<?php echo $OUTPUT->standard_end_of_body_html(); ?>
</code>
This is one of the most important lines of code in the layout file. It asks Moodle to print any required content into the page, and there will likely be a lot although most of it will not be visual.

It will instead be things such as inline scripts and JavaScript files required to go at the bottom of the page. If you forget this line its likely no JavaScript will work!

We've now written our layout file and it is all set to go. The complete source is below for reference. Remember if you want more practical examples simply look at the layout files located within the layout directory of other themes.

<code php>
<?php
$hassidepre = $PAGE->blocks->region_has_content('side-pre', $OUTPUT);
$hassidepost = $PAGE->blocks->region_has_content('side-post', $OUTPUT);
echo $OUTPUT->doctype() ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title; ?></title>
<link rel="shortcut icon" href="<?php echo $OUTPUT->pix_url('favicon', 'theme')?>" />
<?php echo $OUTPUT->standard_head_html() ?>
</head>

<body id="<?php p($PAGE->bodyid); ?>" class="<?php p($PAGE->bodyclasses); ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<div id="page">
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
<div id="page-header">
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div><?php } ?>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</div>
<?php } ?>

<div id="page-content">
<div id="region-main-box">
<div id="region-post-box">
<div id="region-main-wrap">
<div id="region-main">
<div class="region-content">
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</div>
</div>
</div>
<?php if ($hassidepre) { ?>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<?php } ?>

<?php if ($hassidepost) { ?>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
<?php } ?>
</div>
</div>
</div>

<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</div>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>

==Adding some CSS==
With config.php and standard.php both complete the theme is now usable and starting to look like a real theme, however if you change to it using the theme selector you will notice that it still lacks any style.

This of course is where CSS comes in. When writing code Moodle developers are strongly encouraged to not use inline styles anywhere. This is fantastic for us as themers because there is nothing (or at least very little) in Moodle that cannot be styled using CSS.

===Moodle CSS basics===

In Moodle 2.0 all of the CSS for the whole of Moodle is delivered all of the time! This was done for performance reasons. Moodle now reads in all of the CSS, combines it into one file, shrinks it removing any white space, caches it, and then delivers it.

'''What this means for you as a themer?'''

You will need to write good CSS that won't clash with any other CSS within Moodle.

Moodle is so big and complex,there is no way to ensure that classes don't get reused. What we can control however is the classes and id that get added to the body tag for every page. When writing CSS it is highly encouraged to make full use of these body classes, using them will help ensure the CSS you write has the least chance of causing conflicts.

You should also take the time to look at how the Moodle themes use CSS. Look at their use of the body classes and how they separate the CSS for the theme into separate files based on the region of Moodle it applies to.

Check out [[Themes 2.0|Themes 2.0]] and [[CSS coding style]] for more information about writing good CSS.

===Starting to write excitement.css===

<code css>
a {
text-decoration: none;
}

.addcoursebutton .singlebutton {
text-align: center;
}

h1.headermain {
color: #fff;
}

h2.main {
border-bottom: 3px solid #013D6A;
color: #013D6A;
text-align: center;
}

h2.headingblock {
font-size: 18pt;
margin-top: 0;
background-color: #013D6A;
color: #FFF;
text-align: center;
}

#page-header {
background-color: #013D6A;
}

#page-header .headermenu {
color: #FFF;
}

#page-header .headermenu a {
color: #FDFF2A;
}

.navbar {
padding-left: 1em;
}

.breadcrumb li {
color: #FFF;
}

.breadcrumb li a {
color: #FFF;
}

.block {
background-color: #013D6A;
}

.block .header .title {
color: #FFF;
}

.block .header .title .block_action input {
background-color: #FFF;
}

.block .content {
border: 1px solid #000;
padding: 5px;
background-color: #FFF;
}

.block .content .block_tree p {
font-size: 80%;
}

.block_settings_navigation_tree .content .footer {
text-align: center;
}

.block_settings_navigation_tree .content .footer .adminsearchform {
margin-left: 5%;
width: 90%;
font-size: 9pt;
}

.block_settings_navigation_tree .content .footer .adminsearchform #adminsearchquery {
width: 95%;
}

.block_calendar_month .content .calendar-controls a {
color: #013D6A;
font-weight: bold;
}

.block_calendar_month .content .minicalendar td {
border-color: #FFF;
}

.block_calendar_month .content .minicalendar .day {
color: #FFF;
background-color: #013D6A;
}

.block_calendar_month .content .minicalendar .day a {
color: #FFF000;
}

.block_calendar_month .content .minicalendar .weekdays th {
border-width: 0;
font-weight: bold;
color: #013D6A;
}

.block_calendar_month .content .minicalendar .weekdays abbr {
border-width: 0;
text-decoration: none;
}
</code>
[[image:Learn_to_theme_02.jpg|400px|thumb|Excitement theme screenshot]]
This isn't all of the CSS for the theme, but just enough to style the front page when the user is not logged in.
Remember this theme extends the base theme so there is already CSS for layout as well.

Note:
* The CSS is laid out in a single line format. This is done within the core themes for Moodle. It makes it quicker to read the selectors and see what is being styled.
* I have written my selectors to take into account the structure of the HTML (more than just the one tag I want to style). This helps further to reduce the conflicts that I may encounter.
* I use generic classes like ''.sideblock'' only where I want to be generic, as soon as I want to be specific I use the unique classes such as ''.block_calendar_month''

<br style="clear:right;" />

===Using images within CSS===

I will add two image files to the pix directory of my theme:
; /theme/excitement/pix/background.png : This will be the background image for my theme.
; /theme/excitement/pix/gradient.jpg : This will be a gradient I use for the header and headings.
I quickly created both of these images using gimp and simply saved them to the pix directory.
<code css>
html {
background-image: url([[pix:theme|background]]);
}

h2.headingblock,
#page-header,
.sideblock,
.block_calendar_month .content .minicalendar .day {
background-image: url([[pix:theme|gradient]]);
background-repeat: repeat-x;
background-color: #0273C8;
}
</code>
[[image:Learn_to_theme_03.jpg‎|400px|thumb|Excitement theme screenshot]]
The CSS above is the two new rules that I had to write to use my images within CSS.

The first rule sets the background image for the page to background.png

The second rule sets the background for headings, and the sideblocks to use gradient.jpg

You will notice that I did not need to write a path to the image. This is because Moodle has this special syntax that can be used and will be replaced when the CSS is parsed before delivery.
The advantage of using this syntax over writing the path in is that the path may change depending on where you are or what theme is being used.

Other themers may choose to extend your theme with their own; if you use this syntax then all they need to do to override the image is to create one with the same name in their themes directory.

You will also notice that I don't need to add the image files extension. This is because Moodle is smart enough to work out what extension the file uses. It also allows themers to override images with different formats.

<br style="clear:right" />
The following is the complete CSS for my theme:
<div style="overflow:auto;height:860px;">
<code css>
a {text-decoration: none;}
.addcoursebutton .singlebutton {text-align: center;}

h1.headermain {color: #fff;}
h2.main {border-bottom: 3px solid #013D6A;color: #013D6A;text-align: center;}
h2.headingblock {font-size: 18pt;margin-top: 0;background-color: #013D6A;color: #FFF;text-align: center;}
#page-header {background-color: #013D6A;border-bottom:5px solid #013D6A;}
#page-header .headermenu {color: #FFF;}
#page-header .headermenu a {color: #FDFF2A;}

.sideblock {background-color: #013D6A;}
.sideblock .header .title {color: #FFF;}
.sideblock .header .title .block_action input {background-color: #FFF;}
.sideblock .content {border: 1px solid #000;padding: 5px;background-color: #FFF;}
.sideblock .content .block_tree p {font-size: 80%;}

.block_settings_navigation_tree .content .footer {text-align: center;}
.block_settings_navigation_tree .content .footer .adminsearchform {margin-left: 5%;width: 90%;font-size: 9pt;}
.block_settings_navigation_tree .content .footer .adminsearchform #adminsearchquery {width: 95%;}

.block_calendar_month .content .calendar-controls a {color: #013D6A;font-weight: bold;}
.block_calendar_month .content .minicalendar td {border-color: #FFF;}
.block_calendar_month .content .minicalendar .day {color: #FFF;background-color: #013D6A;}
.block_calendar_month .content .minicalendar .day a {color: #FFF000;}
.block_calendar_month .content .minicalendar .weekdays th {border-width: 0;font-weight: bold;color: #013D6A;}
.block_calendar_month .content .minicalendar .weekdays abbr {border-width: 0;text-decoration: none;}

html {background-image:url([[pix:theme|background]]);}

h2.headingblock,
#page-header,
.sideblock,
.block_calendar_month .content .minicalendar .day {background-image:url([[pix:theme|gradient]]);
background-repeat:repeat-x;background-color: #0273C8;}
</code>
</div>

==Adding a screenshot and favicon==
The final thing to do at this point is add both a screenshot for this theme as well as a favicon for it.
The screenshot will be shown in the theme selector screen and should be named ''screenshot.jpg''.
The favicon will be used when someone bookmarks this page.
Both images should be located in your themes pix directory as follows:
* /theme/excitement/pix/screenshot.jpg
* /theme/excitement/pix/favicon.ico

In the case of my theme I have taken a screenshot and added it to that directory, and because I don't really want to do anything special with the favicon I have copied it from /theme/base/pix/favicon.ico so that at least it will be recognisable as Moodle.

[[es:Desarollo:Temas 2.0 creando tu primer tema]]

Output components

2014-10-27T01:31:57Z

Jethac:

{{Work in progress}}

A list of renderable components to be used with [[Output renderers|output renderers]].

== User-related components ==
=== user_picture ===
An avatar for a given '''user''' object, which can be rendered after being constructed directly:
<code php>
$userpic1 = new user_picture($USER);
$OUTPUT->render($userpic1);
</code>
Or by using a helper method in the core renderer (preferred):
<code php>
$options = array( "visibletoscreenreaders" => false );
$userpic2 = $OUTPUT->user_picture($USER, $options);
</code>
The user object should have the following fields:
<code php>
id
picture
imagealt
firstname
lastname
</code>
If the object does not have these fields, the db will be queried with significant performance implications. A list of these fields can be obtained from user_picture::fields() for the purposes of getting values ahead of time if necessary.

The following options can be set on the user_picture, either by changing each field after construction or by passing in an associative array as the second argument.
<code php>
$userpic->courseid = $this->page->course->id; // course id of user profile in link
$userpic->size = 35; // size of image
$userpic->link = true; // make image clickable - the link leads to user profile
$userpic->popup = false; // open in popup
$userpic->alttext = true; // add image alt attribute
$userpic->class = "userpicture"; // image class attribute
$userpic->visibletoscreenreaders = true; // whether to be visible to screen readers
</code>

Output components

2014-10-27T01:31:31Z

Jethac: /* user_picture */

{{Work in progress}}

A list of renderable components to be used with [[Output renderers||output renderers]].

== User-related components ==
=== user_picture ===
An avatar for a given '''user''' object, which can be rendered after being constructed directly:
<code php>
$userpic1 = new user_picture($USER);
$OUTPUT->render($userpic1);
</code>
Or by using a helper method in the core renderer (preferred):
<code php>
$options = array( "visibletoscreenreaders" => false );
$userpic2 = $OUTPUT->user_picture($USER, $options);
</code>
The user object should have the following fields:
<code php>
id
picture
imagealt
firstname
lastname
</code>
If the object does not have these fields, the db will be queried with significant performance implications. A list of these fields can be obtained from user_picture::fields() for the purposes of getting values ahead of time if necessary.

The following options can be set on the user_picture, either by changing each field after construction or by passing in an associative array as the second argument.
<code php>
$userpic->courseid = $this->page->course->id; // course id of user profile in link
$userpic->size = 35; // size of image
$userpic->link = true; // make image clickable - the link leads to user profile
$userpic->popup = false; // open in popup
$userpic->alttext = true; // add image alt attribute
$userpic->class = "userpicture"; // image class attribute
$userpic->visibletoscreenreaders = true; // whether to be visible to screen readers
</code>

Output components

2014-10-27T01:30:52Z

Jethac: Created page with "{{Work in progress}} A list of renderable components to be used with output renderers. == User-related components == === user_picture === An avatar for..."

{{Work in progress}}

A list of renderable components to be used with [[Output renderers||output renderers]].

== User-related components ==
=== user_picture ===
An avatar for a given *user* object, which can be rendered after being constructed directly:
<code php>
$userpic1 = new user_picture($USER);
$OUTPUT->render($userpic1);
</code>
Or by using a helper method in the core renderer (preferred):
<code php>
$options = array( "visibletoscreenreaders" => false );
$userpic2 = $OUTPUT->user_picture($USER, $options);
</code>
The user object should have the following fields:
<code php>
id
picture
imagealt
firstname
lastname
</code>
If the object does not have these fields, the db will be queried with significant performance implications. A list of these fields can be obtained from user_picture::fields() for the purposes of getting values ahead of time if necessary.

The following options can be set on the user_picture, either by changing each field after construction or by passing in an associative array as the second argument.
<code php>
$userpic->courseid = $this->page->course->id; // course id of user profile in link
$userpic->size = 35; // size of image
$userpic->link = true; // make image clickable - the link leads to user profile
$userpic->popup = false; // open in popup
$userpic->alttext = true; // add image alt attribute
$userpic->class = "userpicture"; // image class attribute
$userpic->visibletoscreenreaders = true; // whether to be visible to screen readers
</code>

Deprecated functions in 2.0

2014-10-27T01:12:21Z

Jethac: /* print_user_picture (0) */

{{Work in progress}}
{{Moodle 2.0}}

THIS PAGE IS OUTDATED, DO NOT USE!

This page lists all functions that have been deprecated between 1.9 and 2.0, with instructions on how to upgrade your code. A count of remaining function calls in core is kept next to each function name.

== General notes ==

The following functions have been arranged in alphabetical order, although some of them are very closely related to each other. The number of occurrences of these function calls at the time of writing are indicated in parentheses.

== Functions to migrate ==
=== button_to_popup_window (0) ===
Old code:
<code php>
button_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return, $id, $class);
</code>
New code:
<code php>
$form = new html_form();
$form->button->text = $linkname;
$form->button->title = $title;
$form->button->id = $id;
$form->url = $url;
$form->add_class($class);
$form->button->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->button($form);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to button_to_popup_window() will not work. The $height and $width params are also part of the popup params. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== choose_from_menu (1) ===
Old code:
<code php>
choose_from_menu($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex, $id, $listbox, $multiple, $class);
</code>
New code:
<code php>
$attributes['disabled'] = $disabled;
$attributes['tabindex'] = $tabindex;
$attributes['multiple'] = $multiple;
$attributes['class'] = $class;
$attributes['id'] = $id;

echo html_writer::select($options, $name, $selected, array($nothingvalue=>$nothing), $attributes);
</code>

=== choose_from_menu_nested (0) ===
Old code:
<code php>
choose_from_menu_nested($options, $name, $selected, $nothing, $script, $nothingvalue, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make($options, $name, $selected);
$select->tabindex = $tabindex;
$select->disabled = $disabled;
$select->nothingvalue = $nothingvalue;
$select->nested = true;

echo $OUTPUT->select($select);
</code>
Notes:
#The lang string "choose" is no longer used, in favour of "choosedots".
#The $script param is no longer supported. Please use component::add_action() instead.

=== choose_from_menu_yesno (0) ===
Old code:
<code php>
choose_from_menu_yesno($name, $selected, $script, $return, $disabled, $tabindex);
</code>
New code:
<code php>
$select = moodle_select::make_yes_no($name, $selected);
$select->disabled = $disabled;
$select->tabindex = $tabindex;
echo $OUTPUT->select($select);
</code>
Note: The $script param has been dropped, you need to use component::add_action() instead.

=== choose_from_radio (0) ===

=== close_window_button (0) ===
Old code:
<code php>
close_window_button($name, $return, $reloadopener);
</code>
New code:
<code php>
echo $OUTPUT->close_window_button(get_string($name));
</code>
Note: You must pass a language string already processed by get_string().

=== print_continue (0) ===
Old code:
<code php>
print_continue($link, $return);
</code>
New code:
<code php>
echo $OUTPUT->continue_button($link);
</code>

=== doc_link (0) ===
Old code:
<code php>
doc_link($path, $text, $iconpath);
</code>
New code:
<code php>
echo $OUTPUT->doc_link($path, $text, $iconpath);
</code>
Note: This is not for general use, do not confuse with help_icon()

=== formerr (0) ===
Old code:
<code php>
formerr($string);
</code>
New code:
<code php>
echo $OUTPUT->error_text($error);
</code>

=== helpbutton (0) ===
Old code:
<code php>
helpbutton($page, $title, $module, $image, $linktext, $text, $return, $imagetext);
</code>
New code:
<code php>
$helpicon = new help_icon();
$helpicon->page = $page; // required
$helpicon->text = $title; // required
$helpicon->module = $module; // defaults to 'moodle'
$helpicon->linktext = $linktext;

echo $OUTPUT->help_icon($helpicon);
</code>

=== link_to_popup_window (0) ===
Old code:
<code php>
link_to_popup_window($url, $name, $linkname, $height, $width, $title, $options, $return);
</code>
New code:
<code php>
$link = html_link::make($url, $linkname);
$link->title = $title; // optional
$options['height'] = $height; // optional
$options['width'] = $width; // optional
$link->add_action(new popup_action('click', $url, $name, $options));
echo $OUTPUT->link($link);
</code>
Note: popup parameters ($options) '''must''' be prepared as an associative array, not a string as previously. Simply reusing the $options param previously passed to link_to_popup_window() will not work. See lib/deprecatedlib.php for an example of how the legacy function call is handled.

=== notice_yesno (0) ===
Old code:
<code php>
notice_yesno($message, $linkyes, $linkno, $optionsyes, $optionsno, $methodyes, $methodno);
</code>
New code (simplest form):
<code php>
echo $OUTPUT->confirm($message, $linkyes, $linkno);
</code>

New code (with options in arrays):
<code php>
echo $OUTPUT->confirm($message, new moodle_url($linkyes, $optionsyes), new moodle_url($linkno, $optionsno));
</code>

New code (if the "get" method is required):
<code php>
$formcontinue = new single_button($linkyes, $optionsyes, get_string('yes'), $methodyes);
$formcancel = new single_button($linkno, $optionsno, get_string('no'), $methodno);
echo $OUTPUT->confirm($message, $formcontinue, $formcancel);
</code>

=== notify (0) ===
Old code:
<code php>
notify($message, $classes, $align, $return);
</code>
New code:
<code php>
echo $OUTPUT->notification($message, $classes='');
</code>
Note: Use a CSS rule for alignment.

=== popup_form (0) ===
Old code:
<code php>
popup_form($baseurl, $options, $formid, $selected, $nothing, $help, $helptext, $return, $targetwindow, $selectlabel, $optionsextra, $submitvalue, $disabled, $showbutton);
</code>
New code:
<code php>
// if $baseurl == 'http://domain.com/index.php?var1=1&var2='
$select = html_select::make_popup_form('http://domain.com/index.php?var1=1', 'var2', $options, $formid, $selected);
$select->disabled = $disabled; // optional
$select->set_label($selectlabel, $select->id); // optional, set to false if no "nothing" option is desired (when $selectlabel == '' in original call)
$select->set_help_icon($help, $helptext); // optional
$select->form->button->text = $submitvalue; // optional

echo $OUTPUT->select($select);
</code>
Notes:
*The $optionsextra param is not supported. If your code uses it, you should find another way to add extra params to your <option> tags without using this horrible hack which usually includes inline JS or CSS.

=== print_arrow (15) ===
=== print_box* (0) ===
Old code:
<code php>
print_box($message, $classes, $ids, $return);
print_box_start($classes, $ids, $return);
print_box_end();
</code>
New code:
<code php>
echo $OUTPUT->box($message, $classes, $ids);
echo $OUTPUT->box_start($classes, $ids);
echo $OUTPUT->box_end();
</code>

=== print_checkbox (10) ===
Old code:
<code php>
print_checkbox($name, $value, $checked, $label, $alt, $script, $return);
</code>
New code:
<code php>
$checkbox = new html_select_option();
$checkbox->value = $value; // Required
$checkbox->selected = $checked;
$checkbox->text = $label;
$checkbox->label->text = $label;
$checkbox->alt = $alt;

echo $OUTPUT->checkbox($checkbox, $name);
</code>
Note: html_select_option is a component that can be rendered as a select <option>, a radio button or a checkbox. It holds sufficient information to render all these elements, except the $name variable which is attached to a moodle_select component. This is why we pass the $name string to $OUTPUT->checkbox().

=== print_container (0) ===
Old code:
<code php>
print_container($message, $clearfix, $classes, $idbase, $return);
</code>
New code:
<code php>
if ($clearfix) {
$classes .= ' clearfix';
}
echo $OUTPUT->container($message, $classes, $idbase);
</code>

=== print_date_selector (0) ===

=== print_footer (0) ===
Old code:
<code php>
print_footer($course, $usercourse, $return);
</code>
New code:
<code php>
echo $OUTPUT->footer();
</code>
Notes: No parameters are required.

=== print_header (501) ===
Old code:
<code php>
print_header($title, $heading, $navigation, $focus, $meta, $cache, $button, $menu, $usexml, $bodytags, $return);
</code>
New code:
<code php>
$PAGE->set_heading($heading); // Required
$PAGE->set_title($title);
$PAGE->set_cacheable($cache);
$PAGE->set_focuscontrol($focus);
$PAGE->set_button($button);
$PAGE->navbar->add($nav_entry[0]);
$PAGE->navbar->add($nav_entry[1]);

echo $OUTPUT->header();
</code>
Note: Navigation code is being rewritten, this doc will then be updated with the new usage.

=== print_heading_with_help (0) ===

=== print_heading (0) ===
Old code:
<code php>
print_heading($text, $align, $size, $class, $return, $id);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size, $class, $id);
</code>
Note: Use a CSS class rule to control alignment.

=== print_heading_block (0) ===

=== print_headline (0) ===
Old code:
<code php>
print_headline($text, $size);
</code>
New code:
<code php>
echo $OUTPUT->heading($text, $size);
</code>

=== print_paging_bar (2) ===

Old code:
<code php>
print_paging_bar($totalcount, $page, $perpage, $baseurl, $pagevar, $nocurr, $return);
</code>
New code:
<code php>
$pagingbar = new moodle_paging_bar();
$pagingbar->totalcount = $totalcount; // Required
$pagingbar->page = $page; // Required
$pagingbar->perpage = $perpage; // Required
$pagingbar->baseurl = $baseurl; // Required
$pagingbar->pagevar = $pagevar;
echo $OUTPUT->paging_bar($pagingbar);
</code>
Note: The last two instances of print_paging_bar are found in the old tablelib, which will soon be deprecated.

Note: $nocurr has been dropped. Current page number is never displayed as a link

=== print_scale_menu_helpbutton (0) ===
Old code:
<code php>
print_scale_menu_helpbutton($courseid, $scale);
</code>
New code:
<code php>
echo $OUTPUT->help_button(help_button::make_scale_menu($courseid, $scale));
</code>

=== print_side_block (4) ===
=== print_single_button (0) ===
Old code:
<code php>
print_single_button($link, $options, $label, $method, $notusedanymore, $return, $tooltip, $disabled, $jsconfirmmessage, $formid)
</code>
New code:
<code php>
$form = new html_form();
$form->url = new moodle_url($link, $options); // Required
$form->button = new html_button();
$form->button->text = $label; // Required
$form->button->disabled = $disabled;
$form->button->title = $tooltip;
$form->method = $method;
$form->id = $formid;

if ($jsconfirmmessage) {
$confirmaction = new component_action('click', 'confirm_dialog', array('message' => $jsconfirmmessage));
$form->button->add_action($confirmaction);
}

$output = $OUTPUT->button($form);
</code>

=== print_spacer (0) ===
Old code:
<code php>
print_spacer($height, $width, $br, $return);
</code>
New code:
<code php>
$spacer = new html_image();
$spacer->height = $height;
$spacer->width = $width;
echo $OUTPUT->spacer($spacer);
</code>
Note: The $br attribute has been dropped. You can simply add a line break manually if you need one.

=== print_table (0) ===
Old code:
<code php>
$table = new stdClass();
$table->class = 'mytable';
$table->head = array('Firstname', 'Lastname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
print_table($table, $return);
</code>
New code:
<code php>
$table = new html_table();
$table->set_classes('mytable'); // note the new style of setting CSS class
$table->head = array('First name', 'Last name');
$table->colclasses = array('name fname','name lname');
$table->rowclasses = array();
// (other table properties here)
$table->data = array(array(...),array(...),array(...));
echo $OUTPUT->table($newtable);
</code>
Notes: The new html_table object has the same member variables as the one originally used by print_table(), but has additional, required methods. You must map the old $table object to the new html_table object, as demonstrated above and in lib/deprecatedlib.php (see old print_table function).

=== print_textarea (55) ===
=== print_textfield (0) ===

=== print_time_selector (0) ===

=== print_user_picture (0) ===

Old code:
<code php>
print_user_picture($user, $courseid, $picture, $size, $return, $link, $target, $alttext);
</code>
New code (simple):
<code php>
$userpic = new moodle_user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
echo $OUTPUT->user_picture($userpic);
</code>
New code (complex: alternate text, size, different image and popup action):
<code php>
$userpic = new user_picture();
$userpic->user = $user;
$userpic->courseid = $courseid;
$userpic->size = $size;
$userpic->link = $link;
$userpic->visibletoscreenreaders = false;
$userpic->alttext = $alttext;
$userpic->image->src = $picture;
$userpic->add_action(new popup_action('click', new moodle_url($target)));

echo $OUTPUT->user_picture($userpic);
</code>

=== update_course_button (0) ===

=== update_module_button (94) ===
Old code:
<code php>
$button = update_module_button($cm->id, $course->id, get_string('modulename', 'workshop')); // passed to print_header_simple()
</code>
New code:
<code php>
$PAGE->set_button($OUTPUT->update_module_button($cm->id, 'workshop'));
</code>
Note: $courseid param has been dropped.

=== update_tag_button (0) ===

== Non-supported functions ==
These functions have been completely dropped in 2.0, most likely because they were used very little or not at all. All calls to these functions in core should have been replaced.
=== blocks_print_group ===
=== print_file_picture ===
=== print_png ===
=== print_scale_menu ===
=== print_side_block_end ===
=== print_side_block_start ===
=== print_timer_selector ===
=== print_user ===
=== update_categories_search_button ===
=== update_mymoodle_icon ===

==See also==

* [[How Moodle outputs HTML]]
* [[Migrating your code to the 2.0 rendering API]]

Navigation overhaul specification

2014-10-02T07:35:13Z

Jethac: /* Design */

{{Infobox Project
|name = Navigation overhaul
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45774
|discussion = https://moodle.org/mod/forum/discuss.php?d=261224
|assignee = Frédéric Massart, Jetha Chan
}}
{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=261224}}
Navigation throughout Moodle is often confusing and needs some improvement. With this in mind, a specification has been prepared, defining what problems were identified and how they will be solved. Particular focus will be placed upon improving the experience of students, teachers, and users unfamiliar to Moodle.

== What can be improved ==

Common complaints leveled at Moodle include:

* '''Unnecessary steep learning curve'''
* '''Features or options not being discovered'''
* '''General frustration''' - clunkiness, a certain ''je ne sais quoi''

=== The navigation is not static ===

Sometimes when navigating from one place to another, the state of the tree in the navigation block completely changes. A good example of this is when going from a course to a module - upon arrival in a module, the Administration block will display a collapsed 'Course administration' node and a new expanded 'Module administration' node, as illustrated below.

[[File:pbnotstatic.png|frame|none|alt=Going from course to a module.|Going from course to a module.]]

Consistency should be improved here, as it is unlikely that a user unfamiliar with the system will understand sudden collapsing of or additional nodes.

=== Feature placement ===

It is our opinion that some navigation nodes contain things that you wouldn't expect, and don't contain things that you '''would'' expect. For example:

* 'My profile settings' contains 'Blogs', 'Badges' or 'Messaging'. These are not strictly related to your profile, they are related to your user account.
* What can be found under 'Site pages'?
* Notes
** In order to view Notes taken on a course level, I first need to click on 'Participants', and once the page is loaded I can see new entries in the navigation node 'Participants'. Why is this the case? Most users will not be aware of those links and will miss out on that feature, we feel.

=== Bad naming ===

Proper naming of the navigation helps the user remembering where to find what they are looking for. It also helps them to discover features that they would not otherwise be aware of, e.g. 'Calendar', hidden under 'Site pages'. If a user has no understanding of what 'Site pages' is, it is unlikely that they will expand it.

Another popular(?) example of bad naming is the link 'My grades' under 'Course administration' in the 'Administration' block. 'A student is not administrating anything, his grades are not a setting.'

=== Context jumps ===

The breadcrumb and navigation sometimes jump from one context to another. For instance, as a student when you click on 'Administration > Course administration > My grades', the navigation node on which you appear to be after clicking is 'Administration > Grade administration > User report'.

[[File:pbcontextjumps.png|frame|none|alt=Breadcrumb context jumping.|Breadcrumb context jumping.]]

It is also possible for the user to jump from a course context to a site context, leaving the course (different breadcrumb, different navigation) without realising it and instantly feeling lost. A common reaction would be to use the 'Back' button of their browser to recover from it rather than trying to understand what happened. This behaviour can be observed when visiting someone's profile, viewing some reports, etc...

[[File:pbcontextjumps2.png|frame|none|alt=Navigation context jumping.|Navigation context jumping.]]

In order for users to feel comfortable and confident, and to not feel lost in Moodle's complex page hierarchy, we need to prevent situations where they feel lost and frustrated.

=== Overwhelming the user ===

Both the navigation block and the administration block can potentially have lots of nodes in them, resulting in what is popularly derided as the "scroll of death". We posit that a good navigation system should be simple and concise, and not necessarily contain the entire site map.

== The goal ==

We seek to provide navigation that is:

* Simpler
* Intuitive
* Easy to learn

Leading to myriad benefits, including but not limited to:

; Efficiency
: Less trial and error when looking for something
; Common expectations being met
: Pages being found where you expect them to be
; A reduction in confusion and general frustration
; Less resistance
: New users feeling more confident using the product

Some risk does present itself; by changing large sections of the product, we risk alienating existing experienced Moodle users, frustrated at not finding pages where they used to be. On the other hand, re-learning the navigation should be straightforward, painless and at the very least easier than learning it the first time. User documentation will also suffer in the interim, as screenshots, navigation patterns and other training materials will have to be updated.

== Rough ideas ==

The following is a list of ideas gathered from discussions and resources both internal and external to HQ:

* A student should be able to quickly access his courses, grades, settings, profile from a static place in the UI. This would remove the need for them to expand nodes in both the 'Navigation' block and the 'Administration' block.
* The different nodes of the 'Administration' block could be displayed on a 'Preferences' page.
** e.g. the 'Course administration' items could be listed on a page, each node being a title and each of its elements listed underneath. By moving administration settings to a single page, we obviate the need for the 'Administration' block entirely.
* A teacher should be able to quickly access the 'Options' of a course through a static node, the same way a user can access anything associated to his account.
* Similarly for modules, an easy dropdown to access module preferences and more frequently used options could be created.
* Breadcrumb-based navigation to reduce and perhaps entirely remove the the need for the nested and cumbersome Navigation block.
** This could be problematic in regards to creating problems with accessing site pages, or pages which do not clearly have a hierarchical position. This could be addressed by providing 'in context' links. For instance, adding a new block entry should be available from the Blog page.
* Providing a sitemap page to counter the lack of 'Navigation' block when something is not easily accessible.
* Ability to 'Star' some pages to quickly access favourites.
* Develop a 'Smart search' to easily access the content in the current course, other courses, etc… and the admin settings for admins.
* Populating my/ page with more useful content for the user itself.
* A new profile page on which is displayed the 'public' information of the user. Their forum interactions, their blog, their reports, ...
* Providing an API to modules to implement their own navigation, thus not required to inject links in the navigation block like 'Chat' is doing or 'Quiz' used to do (Results report). This navigation would be displayed in a standard fashion across modules. (Tabs like in wiki?)
* When hovering a user's name, a menu could appear with a few details and links to their profile, etc... (like Jira does).

== Analysis of popular themes ==

Although most of those themes do not change anything about the navigation itself, a few have implemented a ''user menu''. Usually displayed at the top most right of the screen, it contains links to quickly access user specific pages. The most common links are:

* View profile
* Edit profile
* Logout

Less popular links are:

* Calendar
* My private files
* My home

== The solutions ==

To achieve our goal we have to remove the need for the administration and navigation blocks. This is a long process that needs to be broken down into sub-solutions. Some will need to be developed simultaneously to avoid half-baked temporary solutions. Those solutions can be split into two categories: 'User', and 'Course'.

User solutions:

* A user menu
* A user preferences page
* A new profile page
* Revisiting 'My home' page

Course solutions:

* Handling of course profiles
* A course 'Quick access' menu
* An administration page per module
* An administration page for the course
* Dedicated solution to access reports
* Alternative site and course navigation

=== User menu ===

The user menu is a dropdown containing links to pages specific to user. They are context independent and will always point to the same pages. The user menu can always be found at the same place in the user interface and will contain the following links:

* My home
* My profile
* My grades
* Messages
* Logout

[[File:usermenu.png|frame|none|alt=A user menu.|A user menu.]]

'''Benefits'''

* Gives quick and intuitive access to the user specific pages
* Trimming down 'Navigation > My profile'
* Emphasises the page 'My home'

=== User preferences page ===

A link to that page would be placed in the user menu. That page will contain most of what the user has control over on a site level. Their mailing preferences, changing their password, etc... but reorganised.

[[File:userpreferences.png|frame|none|alt=User preferences page.|User preferences page.]]

'''Benefits'''

* We can remove 'My profile settings' from the 'Administration' block.
* The settings are all reachable from one place.
* New pages will help the user understanding what settings they have control over.

=== A new profile page ===

By adding new content to the profile page, we can trim a bit more the navigation block. The profile page is supposed to contain anything you could find about a user, and there will be links to their blog, forum interactions, notes, to send them a message, etc...

We will keep the distinction between the full profile and the course profiles, at this stage we only improve the site profile because the course profiles need more thoughts and are tied to the course solutions.

'''Benefits'''

* Trimming down 'Navigation > My profile'
* Answering concerns of the 'User preferences page'
* Bonus: the profile page has a reason to be visited

=== Revisiting 'My home' page ===

The My/ page is underused and does not contain enough valuable information for the users to visit it. We will update it to include more user-specific content. It will contain:

* My courses
* My private files
* The calendar and upcoming events
* My latest badges

[[File:myhome.png|frame|none|alt=The new dashboard.|The new dashboard.]]

'''Benefits'''

* Trimming down 'Navigation > My profile', at this point it should be empty
* Making the my/ page more interesting and valuable

=== Handling of course profiles ===

We need to remove the confusion between site and course profiles, only a few more informations should be available when viewing a 'Course profile', but we do not need an entirely different profile for that purpose. The course specific information will be accessible from the user profile, but be in the context of the site profile.

'''Benefits'''

* No more course profile pages

=== A course 'Quick access' menu ===

In order to remove the need for the nodes 'Participants' and 'Badges' from the 'Course' entry in the 'Navigation block', and the 'Grades' entry in the 'Course administration' node (for students), we will implement a new 'Quick access' menu for the course. This menu will be accessible on any page within a course, or module.

This menu will only contain links to the 3 entries mentioned above. If later on we add more links to that list, the additional (and less important) entries will be displayed in a dropdown, or a in a 'More' page.

A new grades page will be created for students to access their course grades.

It is important to keep the visible elements of this menu to a minimum. Not more than 3 elements should be displayed at a time. An exception can be made for users with more privileges who will see a 'Settings' (or 'Administration') link, and perhaps a 'Reports' one when we will work on them (see the following the other solutions below).

To unenrol yourself from a course, you would not look into the 'Course administration' node, you would rather find a link on 'My home' page next to the list of courses to unenrol yourself from them.

[[File:coursemenu.png|frame|none|alt=An example of a course quick-access menu.|An example of a course quick-access menu.]]

'''Benefits'''

* Trimming the navigation block
* Removing the 'Course administration' node for students
* Dedicated grades page for the students
* Quick access to the most important pages of a course

=== An administration page per module ===

The same way we would have a 'Preferences' page for the user, the administration page for the module would list everything that was originally in the 'Module administration' node, but reorganised to be more intuitive. A link to that page would be placed somewhere in the general UI.

Modules currently using the 'Adminstration' block to inject new pages into their module should be updated to provide a module navigation instead. It could be a list of links in the module page, or a module navigation such as tabs, this is probably tied to the solution 'Alternative site and course navigation'.

'''Benefits'''

* Intuitive access to all the module administration pages
* Self-contained and self-explanatory
* Removes the need for the 'Module administration' node

'''Concerns'''

* Potentially more clicks-to-destination

=== An administration page for the course ===

The same way we would have a 'Preferences' page for the user, the administration page for the course would list everything that was originally in the 'Course administration' node, but reorganised to be more intuitive. A link to that page will be added to the course 'Quick access' menu.

'''Benefits'''

* Intuitive access to all the course administration pages
* Self-contained and self-explanatory
* No more 'Course administration' node

'''Concerns'''

* Potentially more clicks-to-destination
* Reports would be accessible from that page until 'Dedicated solution to access reports' is implemented

=== Dedicated solution to access reports ===

Reports are the black sheep of the navigation, nobody agrees on where they should be and they are moved around every so often. Perhaps nobody agrees because they do not belong either in the navigation or the administration block.

Currently they are accessed from the 'Administration' block, and as we are moving the content of the block to administration pages, that is where they will end up. This is surely not better (perhaps even worse) than where they were before, so why not thinking once and for all where they should be.

<pre>/!\ Solution needed!

Idea: We could add a 'Report' menu to the course 'Quick access' menu</pre>

'''Goals'''

* Standardised way to access reports
* A navigation that does not jump somewhere else when viewing a report

=== Alternative site and course navigation ===

Now that everything has been sorted out, we should now be able to remove the navigation block - but first we'll need to sort out how to navigate at both the site and course levels.

'''Site level'''
It is envisaged that the frontpage would just be an entry point, with the navigation node 'Site pages' displayed in a block specific to those site pages. Upon leaving the context of the 'Site', you will be in a course; most users will not go back to the front page, except to find some information specific to their institution. To navigate between their courses, teachers and students could refer to their my/ page.

Alternatively, pages like 'Participants', 'Badges' or 'Tags' could be accessed from their context, for instance in a 'Online users' block which would link to 'All participants'. The same applies for 'Calendar', but is already the case because of its block.

'''Course level'''
The site-level concept should disappear as soon as you get in a course; the student or teacher would then focus 100% on the course they are browsing rather than being distracted by site elements. This behavior is currently exhibited by the base and standard themes in 2.6 and before.

The course format will become responsible for most of the navigation in the course, allowing course formats to:

* Inject block(s) to navigate between sections
* Inject block(s) to navigate between modules
* Inject block(s) that does/do both of the above (very similar to the course node in the navigation block)
* Inject links 'Go to next activity', 'Go back to course', ... into module views.

The course format will also have control over the course 'Quick access' menu, in which it could inject/remove items if they wanted to.

The node 'Switch role' will be removed from the administration block, necessitating a 'Switch role' block to be added to the course to unlock that functionality. This block would only be displayed to users having the capabilities to switch role.

'''Future of the Administration block'''

At this point, the administration block will not be displayed to any user, except those users possessing elevated privileges. Administrators, managers or course creators will still have access to the administration block but it will only contain the 'Site administration' node.

== Implementation details ==

=== User context ===

All the pages in a user context will have their own layout wherein the header includes the name of the user in a standardised way, along with some information and a link to message them, and their preferences if the logged in user has the capabilities to edit them. A renderer will be responsible for creating the header, and will use the user ID found from the context defined on that page.

The navigation within the context pages will be:

; For your own context
: Home > Your Name > Page you are on. Clicking on 'Your Name' will lead you to 'My home'.

[[File:userheader.png|frame|none|alt=The header when viewing your context.|The header when your context.]]

; For other users' context
: Home > Users > User Name > Page you are on. Clicking on 'User Name' will lead you to their profile.

[[File:userheader2.png|frame|none|alt=The header when viewing someone else's context.|The header when viewing someone else's context.]]

==== Rules ====

The user header contains very simplistic information about the user, and a few links to very common actions in regard to other users. For instance it can implement a link to send a message to the user, because you might want to be able to do that regardless of what user context page you are visiting. But, 'Edit profile' should not be in it, because it is only relevant to the profile. It is very important to keep the number of available actions to a minimum, because having too many options would defeat the purpose of the simplicity and efficiency it is trying to achieve.

=== A user menu ===

The new user menu would be a new renderer, called from the layout files as it was the case for the login info renderer. The content of the user menu is fixed and not configurable, however it is possible to override the renderer from a theme to change its layout and content.

==== Design ====

Placed on the top right of the site, the name of the user is displayed next to a user icon. The dropdown is displayed when the user clicks the icon or the name. On smaller screens only a user icon is displayed, and expands to reveal its content. When expanded the name of the user logged in is displayed.

When the user is not logged in or when the user is logged in as a guest, a login link is displayed, regardless of the screen size.

==== My grades ====

The 'My grades' page will display the overall grades of the student in all their visible courses. The ordering can be changed, but the default would be alphabetical.

==== Login as ====

When logged in as someone else, the 'Logout' entry becomes 'Return to Admin User'.

==== Switch role ====

When the user role is switched, the 'Logout' entry becomes 'Return to my normal role'. And the name of the user is appended with the role they switch to, e.g. 'Admin User (teacher)'.

==== Trimming navigation ====

At this stage we could trim the navigation block, but we decide not to remove anything just yet as it would create more confusion: some nodes would accessible from the user menu, and others from the navigation block.

==== Rules ====

For it to be used, the user menu needs to be as short as possible and not being cluttered with additional links. It should contain what has been decided upon above, and not be changed - as users will acclimatise to it, adding and removing nodes should not be looked upon lightly. In any case, it should not contain more than 6 links, and should always contain:

* My home
* My profile
* Preferences
* Logout

These are very important to the user as they target user context-specific pages and nothing related to the site structure or the course. A link to 'My courses' would be redundant as this information should be covered in the 'My home' page.

=== A user preferences page ===

The preferences page is a list of links to sub-preferences page. The page will be generated from the navigation node 'My profile settings', though we will have to re-organise them so that each link belongs to a parent node. A link to the preferences page is added to the user menu.

==== Re-organisation ====

* User account
** Edit profile
** Account settings
** Change password
** Security keys
** Messaging

* Blogs
** Preferences
** External blogs
** Register an external blog

* Badges
** Manage my badges
** Preferences
** Backpack settings

The preferences page displays headings (the setting nodes) under which the links to the sub-pages will be displayed.

[[File:userpreferences.png|frame|none|alt=User preferences page.|User preferences page.]]

The nodes 'Roles' and 'Activity reports' will not be part of this page, because they are context based: they point to the course or site context depending on the page we are on. They will remain in the navigation block, but only when the user has the capability to view them. When the only node in the 'My profile settings' node is 'Preferences', then 'My profile settings' is not displayed. Here is an example when you have the capability to view the reports and roles.

[[File:navblockpref.png|frame|none|alt=My profile settings node with extended capability.|My profile settings node with extended capability.]]

==== Naming ====

The 'My profile settings' node becomes the name of the user: 'Frédéric Massart'. The 'Profile settings for Jetha Chan' becomes 'Jetha Chan'.

==== Breadcrumb ====

Each of the sub-pages should be checked to ensure that they are in the right hierarchy, the breadcrumb always looks like '(User context nav) > Preferences > Preference heading > Page I am on'.

==== Another user's preferences ====

The node 'Profile settings for User B' can be used to edit someone's settings. The content is similar to 'My profile settings', except that the node will always be displayed regardless of the presence of 'Roles' or 'Activity reports'. Currently there is no other way for a user with elevated privileges to access someone's preferences, but sooner or later the preferences will be accessible from their profiles.

[[File:navblocksomeonelse.png|frame|none|alt=Profile settings for X with extended capability.|Profile settings for X node with extended capability.]]

==== Repositories ====

At present, repositories are configurable from the Navigation block - this is a good opportunity to move them to the 'Preferences' page.

==== Rules ====

Every link in this page should belong to a section, the sections are only headers that help the users finding what they are looking for. A plugin that adds user preferences related to its features should define a new heading and add its links to that heading. The heading is never clickable.

=== A new profile page ===

For now we will only be focussing on the site profile of the user. Later on, we will be solving the problems linked to the course context, for instances the links to 'Blog' or 'Forum interactions' automatically filtered to only display the blog posts in the course.

==== Content ====

The contact details will be displayed in such a way that they do not look like a list any more. For instance, everyone knows what an email address is, there is no need to prefix it with 'Email address:'.

The badges will be displayed on the profile too.

==== Links ====

* Edit profile (If this is your profile)
* Blog
* Forum interactions
* Notes (If you have the capability to)
* Preferences (If you have the capability to and are viewing someone's profile)
* Send a message
* Login as (If you have the capability to)

==== Navigation block ====

We can start trimming the node 'My profile' a bit, but some nodes will remain until we sort out the 'My' page. When doing so, it is important to make sure that the nodes 'Home > Some course > Participants > User B' still contain everything it does right now, because those links point to course-based pages, and would not be accessible otherwise.

==== Rules ====

The profile page contains everything about the user that is public. In other words, a content specific to the user should not be displayed on the profile at all, because it would never be accessible to another user, e.g. 'Private files'.

There are exceptions to this rule, badges for example. As a setting allows you to define whether or not your badges are on your profile, you might not be able to see them there, so they should be available on your dashboard.

For content controlled by permissions (and not preferences), they should remain on the profile. Take 'Blog' as an example, an administrator can prevent blog entries from another user to be accessed depending on your role. As the user does not have any information about the roles of the other users, the blog link is displayed on the profile, but other users will not see it. Having a blog block on the 'My home' page would not be useful because it simply duplicates the access points, for no apparent reason to the user.

=== Revisiting 'My home' page ===

We need to add more default blocks to the existing page, the different available blocks will be:

* My courses (already there)
* My private files (already there)
* The calendar
* Upcoming events
* My latest badges

We need to add a link to 'My latest badges' to the page listing all the badges.

==== Navigation block ====

We can now remove 'My profile' (or now called 'Jetha Chan') from the navigation block entirely. But it has to still be accessible under the node of a user in a course tree.

The node 'My courses' is also removed, users should be used to using their dashboard to access their courses.

==== Rules ====

The 'My home' page contains everything about a user that is private and not accessible to other users. For instance, your calendar events or your private files. The list of courses you are enrolled in are an exception, they could be displayed on the user profile, but because they are so important and need to be layed out in useful fashion, they will be part of the 'My home' page.

This page does not need to link to pages which are already accessible from the 'User menu', for instance the profile.

=== Course context ===

<pre>Pending</pre>

* Handling of course profiles
* An administration page per module
* An administration page for the course
* Accessing course grades for students
* Dedicated solution to access reports
* Alternative site and course navigation
** Checking for inconsistencies in the breadcrumb jumping from one place to another.

== Roadmap ==

=== User context ===

# The user menu
# Implementing the user 'header' for user context pages
# The preferences page
# The new profile page
# Revisiting 'My home'

=== Course context ===

<pre>To be defined.</pre>

== Related links ==

* [https://docs.google.com/document/d/16BJsINun13StUFOQaejj3Gawz9jk22ir_r49f3MbInM/edit#heading=h.fuvsbkikzj88 Navigation experiment]
* [https://docs.google.com/document/d/1AXJw8uX6MczA5VC3phkVVv1ee5eZ2nluIiPC2ecgHLE/edit#heading=h.k3lh9alzq3iy Navigation prototyping 2.7]
* MDL-34838: Navigation inconsistencies
* [http://demo2k12.moodlerooms.com Minimal by Moodlerooms]
* [https://moodle.org/mod/forum/discuss.php?d=226791 Users’ personalised profiles]

Peer reviewing

2014-09-30T09:22:04Z

Jethac:

These are points to consider while peer-reviewing issues. Further explanation below.

[] Syntax
[] Whitespace
[] Output
[] Language
[] Databases
[] Testing (instructions and automated tests)
[] Security
[] Documentation
[] Git
[] Third party code
[] Sanity check
[] Icons

Acceptable check-marks are Y (for yes), N (for no) or - (for not applicable). All N check-marks should be accompanied by an explanation of the problem that still needs to be addressed.

==Syntax==
To allow the community of Moodle developers to work together, conventions should be followed.

* The code is easy to understand and, where it isn't, comments have been provided.
* Variables are named correctly (all lower case, no camel-case, no underscores).
* Functions are named correctly (all lower case, no camel-case, underscores allowed).
* PHP DocBlocks have been updated and adhere to [[Coding_style#Documentation_and_comments|coding style guide]].
* Where functions are being removed, the [[Deprecation]] process is followed.
* The code doesn't use [[Deprecated_functions_in_2.0|deprecated functions]].
* $_GET, $_POST, $_REQUEST, $_COOKIE, and $_SESSION are never used.

See the [[Coding style]] guide for details.

==Whitespace==
Unnecessary whitespace changes can cause conflicts when committing code.

Ensure that:
* there are no unnecessary blank lines in the new code;
* blank lines do not contain spaces;
* there are no unnecessary changes to whitespace in other areas on the file;

==Output==
Output needs to be controlled by renderers to achieve consistency and correct application of themes.

Ensure that:
* output renders are used to generate output strings, including HTML tags;
* HTML output is valid XHTML;
* no inline styles have been used in HTML output (everything has to be in CSS);
* CSS has been added to the appropriate CSS files (base, specific area, sometimes canvas); and
* the code doesn't use buffered output unless absolutely necessary.
* all visual output has a RTL alternative included

feedback any notices (E_STRICT, etc) seen into the MDL.

==Language==
To achieve appropriate internationalisation of Moodle, language strings must be managed correctly.

Ensure that:
* new language strings are named correctly (all lower case, no camel-case, underscores are permissible in some cases);
* help strings are named and formatted as described in [[Help strings]];
* language strings are used instead of hard-coded strings for text output;
* language strings have not been removed or renamed, had their meaning changed or had their parameters changed in stable branches (permitted only in master); and
* AMOS commands have been specified when moving or copying language strings.

==Databases==
DB calls are the greatest performance bottleneck in Moodle.

If there is SQL code you can test quickly then do so.

Ensure that:
* there are minimal DB calls (no excessive use of the DB); and
* the code uses SQL compatible with all the supported DB engines (check all selected fields appear in an 'order by' clause).

==Testing instructions and automated tests==
It is the developer's responsibility to test code before integration. Issues should not be sent for peer review without tests so that the peer reviewer can assess their quality and use them to consider the scope of the issue.

Ensure that:
* there are specific testing instructions that state how, as well as what, to test. Please ensure that the testing instructions are in the correct format: [https://docs.moodle.org/dev/Behat Behat gherkin];
* new unit tests have been added when there is a change in functionality; and
* '''unit tests pass''' for related areas where changes have been made.
* '''Behat tests pass''' for related areas where changes have been made, especially when it involved UI changes.

==Security==
The user community relies on Moodle being responsibly secure.

Ensure that:
* user login is checked where an identity is needed;
* sesskey values are checked before all write actions where appropriate (some read actions as well);
* capabilities are checked where roles differ; and
* if the issue itself is a [[Security|security]] issue, the [[Process#Security_issues|security process]] is being followed.
** Ensure that the fix is '''not''' available in a public repository (ie. a personal Github account); stand-alone patches should be provided instead.
** The issue will not be integrated until just before the next minor version release.

==Documentation==
Work does not stop when code is integrated.

Ensure that:
* Appropriate [[Tracker_issue_labels|labels]] have been added when there has been a function change, particularly
** qa_test_required (significant functional change),
** docs_required (any functional change, usually paired with ui_change),
** dev_docs_required (any change to APIs, usually paired with api_chage),
** ui_change (any functional change, usually paired with docs_required, except ui_change remains permanetly), and
** api_change (any change to APIs that devs will need to know about, usually paired with dev_docs_required, except api_change remains permanetly).

==Git==
Ensure that:
* the commit matches the [[Coding style#Git_commits|Coding style]]
* the Git history is clean and the work has been rebased to logical commits; and
* the original author of the work provided as a patch has been given credit within the commit (as author of in the commit message if changes were made).

==Third party code==
Does the change contain third party code? If so, ensure that:

* The code is licensed under a [http://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses| GPL compatible license].
* The instructions for upgrading/importing the library and contained within a readme_moodle.txt file.
* The library is recorded in a thirdparty.xml file, including licensing information.
* Third party code has been scanned to check for url accessible entry points that could be exploited. These should either be disabled, or if required functionality they should be checked for security weaknesses.
* Does not duplicate the functionality of any existing api or third party library in core.

==Sanity check==
Ensure that:
* the code seems to solve the described problem completely within its reported scope (and further issues have been created to resolve remaining parts or further refactoring);
* the code makes sense in relation to the broader codebase (look at the whole function, not just the altered code); and
* the developer has searched for and fixed other areas that may also have been affected by the same problem.
* if any version numbers have been changed in [[version.php]] files, then the changes follow [[Moodle_versions#How_to_increment_version_numbers_in_core|the rule for updating version numbers in core]].

==Icons==
Are new icons being introduced? If so, ensure that:
* the icons abide by our [https://docs.moodle.org/dev/Moodle_icons icon guidelines] with regards to size, design and format
* the icons are do not unnecessarily add new ways of expressing existing concepts
* the icons are in a pix folder that makes sense

==See Also==
* [http://moodle.org/plugins/view.php?plugin=local_codechecker Code checker plugin]

Talk:Navigation overhaul specification

2014-06-05T09:04:32Z

Jethac:

"Both the navigation block and the administration block can potentially have lots of nodes in them, resulting in what is popularly derided as the "scroll of death". We posit that a good navigation system should be simple and concise, and not necessarily contain the entire site map."

IMHO Scroll of death is more having so much content in a linear layout that it's impossible to navigate, rather than there being too many nodes in either of the blocks. However both influence each other:
Lots of content in a straight list introduces navigation issues, however if the navigation only presents straight lists then likely to get content that simply reinforces it --[[User:Michael Hughes|Michael Hughes]] ([[User talk:Michael Hughes|talk]]) 21:42, 3 June 2014 (WST)

@Michael: Thanks for the comment! You're correct that each influences the other; and if you're seeking to influence us in the direction of a holistic approach to that kind of thing, I agree completely. While we're still in early discussions, it's envisaged that placing more control in course formats would help to ameliorate this, for example:

* instead of a naive week-on-week course format, we could have a format that groups future weeks by the month
* instead of a list of activity subject areas, we could have a format that displays subject areas in a square or hex grid

Anything's possible! --[[User:Jetha Chan|Jetha Chan]] ([[User talk:Jetha Chan|talk]]) 17:04, 5 June 2014 (WST)

Talk:Navigation overhaul specification

2014-06-05T09:00:41Z

Jethac:

Navigation overhaul specification

2014-05-30T09:33:53Z

Jethac: /* User context */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45774
|discussion = -
|assignee = Frédéric Massart, Jetha Chan
}}

{{Work in progress}}

Navigation throughout Moodle is often confusing and needs some improvement. With this in mind, a specification has been prepared, defining what problems were identified and how they will be solved. Particular focus will be placed upon improving the experience of students, teachers, and users unfamiliar to Moodle.

== What can be improved ==

Common complaints leveled at Moodle include:

* '''Unnecessary steep learning curve'''
* '''Features or options not being discovered'''
* '''General frustration''' - clunkiness, a certain ''je ne sais quoi''

=== The navigation is not static ===

Sometimes when navigating from one place to another, the state of the tree in the navigation block completely changes. A good example of this is when going from a course to a module - upon arrival in a module, the Administration block will display a collapsed 'Course administration' node and a new expanded 'Module administration' node, as illustrated below.

[[File:pbnotstatic.png|frame|none|alt=Going from course to a module.|Going from course to a module.]]

Consistency should be improved here, as it is unlikely that a user unfamiliar with the system will understand sudden collapsing of or additional nodes.

=== Feature placement ===

It is our opinion that some navigation nodes contain things that you wouldn't expect, and don't contain things that you '''would'' expect. For example:

* 'My profile settings' contains 'Blogs', 'Badges' or 'Messaging'. These are not strictly related to your profile, they are related to your user account.
* What can be found under 'Site pages'?
* Notes
** In order to view Notes taken on a course level, I first need to click on 'Participants', and once the page is loaded I can see new entries in the navigation node 'Participants'. Why is this the case? Most users will not be aware of those links and will miss out on that feature, we feel.

=== Bad naming ===

Proper naming of the navigation helps the user remembering where to find what they are looking for. It also helps them to discover features that they would not otherwise be aware of, e.g. 'Calendar', hidden under 'Site pages'. If a user has no understanding of what 'Site pages' is, it is unlikely that they will expand it.

Another popular(?) example of bad naming is the link 'My grades' under 'Course administration' in the 'Administration' block. 'A student is not administrating anything, his grades are not a setting.'

=== Context jumps ===

The breadcrumb and navigation sometimes jump from one context to another. For instance, as a student when you click on 'Administration > Course administration > My grades', the navigation node on which you appear to be after clicking is 'Administration > Grade administration > User report'.

[[File:pbcontextjumps.png|frame|none|alt=Breadcrumb context jumping.|Breadcrumb context jumping.]]

It is also possible for the user to jump from a course context to a site context, leaving the course (different breadcrumb, different navigation) without realising it and instantly feeling lost. A common reaction would be to use the 'Back' button of their browser to recover from it rather than trying to understand what happened. This behaviour can be observed when visiting someone's profile, viewing some reports, etc...

[[File:pbcontextjumps2.png|frame|none|alt=Navigation context jumping.|Navigation context jumping.]]

In order for users to feel comfortable and confident, and to not feel lost in Moodle's complex page hierarchy, we need to prevent situations where they feel lost and frustrated.

=== Overwhelming the user ===

Both the navigation block and the administration block can potentially have lots of nodes in them, resulting in what is popularly derided as the "scroll of death". We posit that a good navigation system should be simple and concise, and not necessarily contain the entire site map.

== The goal ==

We seek to provide navigation that is:

* Simpler
* Intuitive
* Easy to learn

Leading to myriad benefits, including but not limited to:

; Efficiency
: Less trial and error when looking for something
; Common expectations being met
: Pages being found where you expect them to be
; A reduction in confusion and general frustration
; Less resistance
: New users feeling more confident using the product

Some risk does present itself; by changing large sections of the product, we risk alienating existing experienced Moodle users, frustrated at not finding pages where they used to be. On the other hand, re-learning the navigation should be straightforward, painless and at the very least easier than learning it the first time. User documentation will also suffer in the interim, as screenshots, navigation patterns and other training materials will have to be updated.

== Rough ideas ==

The following is a list of ideas gathered from discussions and resources both internal and external to HQ:

* A student should be able to quickly access his courses, grades, settings, profile from a static place in the UI. This would remove the need for them to expand nodes in both the 'Navigation' block and the 'Administration' block.
* The different nodes of the 'Administration' block could be displayed on a 'Preferences' page.
** e.g. the 'Course administration' items could be listed on a page, each node being a title and each of its elements listed underneath. By moving administration settings to a single page, we obviate the need for the 'Administration' block entirely.
* A teacher should be able to quickly access the 'Options' of a course through a static node, the same way a user can access anything associated to his account.
* Similarly for modules, an easy dropdown to access module preferences and more frequently used options could be created.
* Breadcrumb-based navigation to reduce and perhaps entirely remove the the need for the nested and cumbersome Navigation block.
** This could be problematic in regards to creating problems with accessing site pages, or pages which do not clearly have a hierarchical position. This could be addressed by providing 'in context' links. For instance, adding a new block entry should be available from the Blog page.
* Providing a sitemap page to counter the lack of 'Navigation' block when something is not easily accessible.
* Ability to 'Star' some pages to quickly access favourites.
* Develop a 'Smart search' to easily access the content in the current course, other courses, etc… and the admin settings for admins.
* Populating my/ page with more useful content for the user itself.
* A new profile page on which is displayed the 'public' information of the user. Their forum interactions, their blog, their reports, ...
* Providing an API to modules to implement their own navigation, thus not required to inject links in the navigation block like 'Chat' is doing or 'Quiz' used to do (Results report). This navigation would be displayed in a standard fashion across modules. (Tabs like in wiki?)
* When hovering a user's name, a menu could appear with a few details and links to their profile, etc... (like Jira does).

== Analysis of popular themes ==

Although most of those themes do not change anything about the navigation itself, a few have implemented a ''user menu''. Usually displayed at the top most right of the screen, it contains links to quickly access user specific pages. The most common links are:

* View profile
* Edit profile
* Logout

Less popular links are:

* Calendar
* My private files
* My home

== The solutions ==

To achieve our goal we have to remove the need for the administration and navigation blocks. This is a long process that needs to be broken down into sub-solutions. Some will need to be developed simultaneously to avoid half-baked temporary solutions. Those solutions can be split into two categories: 'User', and 'Course'.

User solutions:

* A user menu
* A user preferences page
* A new profile page
* Revisiting 'My home' page

Course solutions:

* Handling of course profiles
* A course 'Quick access' menu
* An administration page per module
* An administration page for the course
* Dedicated solution to access reports
* Alternative site and course navigation

=== User menu ===

The user menu is a dropdown containing links to pages specific to user. They are context independent and will always point to the same pages. The user menu can always be found at the same place in the user interface and will contain the following links:

* My home
* My profile
* My grades
* Messages
* Logout

[[File:usermenu.png|frame|none|alt=A user menu.|A user menu.]]

'''Benefits'''

* Gives quick and intuitive access to the user specific pages
* Trimming down 'Navigation > My profile'
* Emphasises the page 'My home'

=== User preferences page ===

A link to that page would be placed in the user menu. That page will contain most of what the user has control over on a site level. Their mailing preferences, changing their password, etc... but reorganised.

[[File:userpreferences.png|frame|none|alt=User preferences page.|User preferences page.]]

'''Benefits'''

* We can remove 'My profile settings' from the 'Administration' block.
* The settings are all reachable from one place.
* New pages will help the user understanding what settings they have control over.

=== A new profile page ===

By adding new content to the profile page, we can trim a bit more the navigation block. The profile page is supposed to contain anything you could find about a user, and there will be links to their blog, forum interactions, notes, to send them a message, etc...

We will keep the distinction between the full profile and the course profiles, at this stage we only improve the site profile because the course profiles need more thoughts and are tied to the course solutions.

'''Benefits'''

* Trimming down 'Navigation > My profile'
* Answering concerns of the 'User preferences page'
* Bonus: the profile page has a reason to be visited

=== Revisiting 'My home' page ===

The My/ page is underused and does not contain enough valuable information for the users to visit it. We will update it to include more user-specific content. It will contain:

* My courses
* My private files
* The calendar and upcoming events
* My latest badges

[[File:myhome.png|frame|none|alt=The new dashboard.|The new dashboard.]]

'''Benefits'''

* Trimming down 'Navigation > My profile', at this point it should be empty
* Making the my/ page more interesting and valuable

=== Handling of course profiles ===

We need to remove the confusion between site and course profiles, only a few more informations should be available when viewing a 'Course profile', but we do not need an entirely different profile for that purpose. The course specific information will be accessible from the user profile, but be in the context of the site profile.

'''Benefits'''

* No more course profile pages

=== A course 'Quick access' menu ===

In order to remove the need for the nodes 'Participants' and 'Badges' from the 'Course' entry in the 'Navigation block', and the 'Grades' entry in the 'Course administration' node (for students), we will implement a new 'Quick access' menu for the course. This menu will be accessible on any page within a course, or module.

This menu will only contain links to the 3 entries mentioned above. If later on we add more links to that list, the additional (and less important) entries will be displayed in a dropdown, or a in a 'More' page.

A new grades page will be created for students to access their course grades.

It is important to keep the visible elements of this menu to a minimum. Not more than 3 elements should be displayed at a time. An exception can be made for users with more privileges who will see a 'Settings' (or 'Administration') link, and perhaps a 'Reports' one when we will work on them (see the following the other solutions below).

To unenrol yourself from a course, you would not look into the 'Course administration' node, you would rather find a link on 'My home' page next to the list of courses to unenrol yourself from them.

[[File:coursemenu.png|frame|none|alt=An example of a course quick-access menu.|An example of a course quick-access menu.]]

'''Benefits'''

* Trimming the navigation block
* Removing the 'Course administration' node for students
* Dedicated grades page for the students
* Quick access to the most important pages of a course

=== An administration page per module ===

The same way we would have a 'Preferences' page for the user, the administration page for the module would list everything that was originally in the 'Module administration' node, but reorganised to be more intuitive. A link to that page would be placed somewhere in the general UI.

Modules currently using the 'Adminstration' block to inject new pages into their module should be updated to provide a module navigation instead. It could be a list of links in the module page, or a module navigation such as tabs, this is probably tied to the solution 'Alternative site and course navigation'.

'''Benefits'''

* Intuitive access to all the module administration pages
* Self-contained and self-explanatory
* Removes the need for the 'Module administration' node

'''Concerns'''

* Potentially more clicks-to-destination

=== An administration page for the course ===

The same way we would have a 'Preferences' page for the user, the administration page for the course would list everything that was originally in the 'Course administration' node, but reorganised to be more intuitive. A link to that page will be added to the course 'Quick access' menu.

'''Benefits'''

* Intuitive access to all the course administration pages
* Self-contained and self-explanatory
* No more 'Course administration' node

'''Concerns'''

* Potentially more clicks-to-destination
* Reports would be accessible from that page until 'Dedicated solution to access reports' is implemented

=== Dedicated solution to access reports ===

Reports are the black sheep of the navigation, nobody agrees on where they should be and they are moved around every so often. Perhaps nobody agrees because they do not belong either in the navigation or the administration block.

Currently they are accessed from the 'Administration' block, and as we are moving the content of the block to administration pages, that is where they will end up. This is surely not better (perhaps even worse) than where they were before, so why not thinking once and for all where they should be.

<pre>/!\ Solution needed!

Idea: We could add a 'Report' menu to the course 'Quick access' menu</pre>

'''Goals'''

* Standardised way to access reports
* A navigation that does not jump somewhere else when viewing a report

=== Alternative site and course navigation ===

Now that everything has been sorted out, we should now be able to remove the navigation block - but first we'll need to sort out how to navigate at both the site and course levels.

'''Site level'''
It is envisaged that the frontpage would just be an entry point, with the navigation node 'Site pages' displayed in a block specific to those site pages. Upon leaving the context of the 'Site', you will be in a course; most users will not go back to the front page, except to find some information specific to their institution. To navigate between their courses, teachers and students could refer to their my/ page.

Alternatively, pages like 'Participants', 'Badges' or 'Tags' could be accessed from their context, for instance in a 'Online users' block which would link to 'All participants'. The same applies for 'Calendar', but is already the case because of its block.

'''Course level'''
The site-level concept should disappear as soon as you get in a course; the student or teacher would then focus 100% on the course they are browsing rather than being distracted by site elements. This behavior is currently exhibited by the base and standard themes in 2.6 and before.

The course format will become responsible for most of the navigation in the course, allowing course formats to:

* Inject block(s) to navigate between sections
* Inject block(s) to navigate between modules
* Inject block(s) that does/do both of the above (very similar to the course node in the navigation block)
* Inject links 'Go to next activity', 'Go back to course', ... into module views.

The course format will also have control over the course 'Quick access' menu, in which it could inject/remove items if they wanted to.

The node 'Switch role' will be removed from the administration block, necessitating a 'Switch role' block to be added to the course to unlock that functionality. This block would only be displayed to users having the capabilities to switch role.

'''Future of the Administration block'''

At this point, the administration block will not be displayed to any user, except those users possessing elevated privileges. Administrators, managers or course creators will still have access to the administration block but it will only contain the 'Site administration' node.

== Implementation details ==

=== User context ===

All the pages in a user context will have their own layout wherein the header includes the name of the user in a standardised way, along with some information and a link to message them, and their preferences if the logged in user has the capabilities to edit them. A renderer will be responsible for creating the header, and will use the user ID found from the context defined on that page.

The navigation within the context pages will be:

; For your own context
: Home > Your Name > Page you are on. Clicking on 'Your Name' will lead you to 'My home'.

[[File:userheader.png|frame|none|alt=The header when viewing your context.|The header when your context.]]

; For other users' context
: Home > Users > User Name > Page you are on. Clicking on 'User Name' will lead you to their profile.

[[File:userheader2.png|frame|none|alt=The header when viewing someone else's context.|The header when viewing someone else's context.]]

==== Rules ====

The user header contains very simplistic information about the user, and a few links to very common actions in regard to other users. For instance it can implement a link to send a message to the user, because you might want to be able to do that regardless of what user context page you are visiting. But, 'Edit profile' should not be in it, because it is only relevant to the profile. It is very important to keep the number of available actions to a minimum, because having too many options would defeat the purpose of the simplicity and efficiency it is trying to achieve.

=== A user menu ===

The new user menu would be a new renderer, called from the layout files as it was the case for the login info renderer. The content of the user menu is fixed and not configurable, however it is possible to override the renderer from a theme to change its layout and content.

==== Design ====

Placed on the top right of the site, the name of the user is displayed next to a user icon. The dropdown is displayed when the user clicks the icon or the name. On smaller screens only a user icon is displayed, and expands to reveal its content. When expanded the name of the user logged in is displayed.

When the user is not logged in, a login link is displayed, regardless of the screen size.

==== My grades ====

The 'My grades' page will display the overall grades of the student in all their visible courses. The ordering can be changed, but the default would be alphabetical.

==== Login as ====

When logged in as someone else, the 'Logout' entry becomes 'Return to Admin User'.

==== Switch role ====

When the user role is switched, the 'Logout' entry becomes 'Return to my normal role'. And the name of the user is appended with the role they switch to, e.g. 'Admin User (teacher)'.

==== Trimming navigation ====

At this stage we could trim the navigation block, but we decide not to remove anything just yet as it would create more confusion: some nodes would accessible from the user menu, and others from the navigation block.

==== Rules ====

For it to be used, the user menu needs to be as short as possible and not being cluttered with additional links. It should contain what has been decided upon above, and not be changed - as users will acclimatise to it, adding and removing nodes should not be looked upon lightly. In any case, it should not contain more than 6 links, and should always contain:

* My home
* My profile
* Preferences
* Logout

These are very important to the user as they target user context-specific pages and nothing related to the site structure or the course. A link to 'My courses' would be redundant as this information should be covered in the 'My home' page.

=== A user preferences page ===

The preferences page is a list of links to sub-preferences page. The page will be generated from the navigation node 'My profile settings', though we will have to re-organise them so that each link belongs to a parent node. A link to the preferences page is added to the user menu.

==== Re-organisation ====

* User account
** Edit profile
** Account settings
** Change password
** Security keys
** Messaging

* Blogs
** Preferences
** External blogs
** Register an external blog

* Badges
** Manage my badges
** Preferences
** Backpack settings

The preferences page displays headings (the setting nodes) under which the links to the sub-pages will be displayed.

[[File:userpreferences.png|frame|none|alt=User preferences page.|User preferences page.]]

The nodes 'Roles' and 'Activity reports' will not be part of this page, because they are context based: they point to the course or site context depending on the page we are on. They will remain in the navigation block, but only when the user has the capability to view them. When the only node in the 'My profile settings' node is 'Preferences', then 'My profile settings' is not displayed. Here is an example when you have the capability to view the reports and roles.

[[File:navblockpref.png|frame|none|alt=My profile settings node with extended capability.|My profile settings node with extended capability.]]

==== Naming ====

The 'My profile settings' node becomes the name of the user: 'Frédéric Massart'. The 'Profile settings for Jetha Chan' becomes 'Jetha Chan'.

==== Breadcrumb ====

Each of the sub-pages should be checked to ensure that they are in the right hierarchy, the breadcrumb always looks like '(User context nav) > Preferences > Preference heading > Page I am on'.

==== Another user's preferences ====

The node 'Profile settings for User B' can be used to edit someone's settings. The content is similar to 'My profile settings', except that the node will always be displayed regardless of the presence of 'Roles' or 'Activity reports'. Currently there is no other way for a user with elevated privileges to access someone's preferences, but sooner or later the preferences will be accessible from their profiles.

[[File:navblocksomeonelse.png|frame|none|alt=Profile settings for X with extended capability.|Profile settings for X node with extended capability.]]

==== Repositories ====

At present, repositories are configurable from the Navigation block - this is a good opportunity to move them to the 'Preferences' page.

==== Rules ====

Every link in this page should belong to a section, the sections are only headers that help the users finding what they are looking for. A plugin that adds user preferences related to its features should define a new heading and add its links to that heading. The heading is never clickable.

=== A new profile page ===

For now we will only be focussing on the site profile of the user. Later on, we will be solving the problems linked to the course context, for instances the links to 'Blog' or 'Forum interactions' automatically filtered to only display the blog posts in the course.

==== Content ====

The contact details will be displayed in such a way that they do not look like a list any more. For instance, everyone knows what an email address is, there is no need to prefix it with 'Email address:'.

The badges will be displayed on the profile too.

==== Links ====

* Edit profile (If this is your profile)
* Blog
* Forum interactions
* Notes (If you have the capability to)
* Preferences (If you have the capability to and are viewing someone's profile)
* Send a message
* Login as (If you have the capability to)

==== Navigation block ====

We can start trimming the node 'My profile' a bit, but some nodes will remain until we sort out the 'My' page. When doing so, it is important to make sure that the nodes 'Home > Some course > Participants > User B' still contain everything it does right now, because those links point to course-based pages, and would not be accessible otherwise.

==== Rules ====

The profile page contains everything about the user that is public. In other words, a content specific to the user should not be displayed on the profile at all, because it would never be accessible to another user, e.g. 'Private files'.

There are exceptions to this rule, badges for example. As a setting allows you to define whether or not your badges are on your profile, you might not be able to see them there, so they should be available on your dashboard.

For content controlled by permissions (and not preferences), they should remain on the profile. Take 'Blog' as an example, an administrator can prevent blog entries from another user to be accessed depending on your role. As the user does not have any information about the roles of the other users, the blog link is displayed on the profile, but other users will not see it. Having a blog block on the 'My home' page would not be useful because it simply duplicates the access points, for no apparent reason to the user.

=== Revisiting 'My home' page ===

We need to add more default blocks to the existing page, the different available blocks will be:

* My courses (already there)
* My private files (already there)
* The calendar
* Upcoming events
* My latest badges

We need to add a link to 'My latest badges' to the page listing all the badges.

==== Navigation block ====

We can now remove 'My profile' (or now called 'Jetha Chan') from the navigation block entirely. But it has to still be accessible under the node of a user in a course tree.

The node 'My courses' is also removed, users should be used to using their dashboard to access their courses.

==== Rules ====

The 'My home' page contains everything about a user that is private and not accessible to other users. For instance, your calendar events or your private files. The list of courses you are enrolled in are an exception, they could be displayed on the user profile, but because they are so important and need to be layed out in useful fashion, they will be part of the 'My home' page.

This page does not need to link to pages which are already accessible from the 'User menu', for instance the profile.

=== Course context ===

<pre>Pending</pre>

* Handling of course profiles
* An administration page per module
* An administration page for the course
* Accessing course grades for students
* Dedicated solution to access reports
* Alternative site and course navigation
** Checking for inconsistencies in the breadcrumb jumping from one place to another.

== Roadmap ==

=== User context ===

# The user menu
# Implementing the user 'header' for user context pages
# The preferences page
# The new profile page
# Revisiting 'My home'

=== Course context ===

<pre>To be defined.</pre>

== Related links ==

* [https://docs.google.com/document/d/16BJsINun13StUFOQaejj3Gawz9jk22ir_r49f3MbInM/edit#heading=h.fuvsbkikzj88 Navigation experiment]
* [https://docs.google.com/document/d/1AXJw8uX6MczA5VC3phkVVv1ee5eZ2nluIiPC2ecgHLE/edit#heading=h.k3lh9alzq3iy Navigation prototyping 2.7]
* MDL-34838: Navigation inconsistencies
* [http://demo2k12.moodlerooms.com Minimal by Moodlerooms]
* [https://moodle.org/mod/forum/discuss.php?d=226791 Users’ personalised profiles]

Navigation overhaul specification

2014-05-30T09:27:01Z

Jethac: /* An administration page per module */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45774
|discussion = -
|assignee = Frédéric Massart, Jetha Chan
}}

{{Work in progress}}

Navigation throughout Moodle is often confusing and needs some improvement. With this in mind, a specification has been prepared, defining what problems were identified and how they will be solved. Particular focus will be placed upon improving the experience of students, teachers, and users unfamiliar to Moodle.

== What can be improved ==

Common complaints leveled at Moodle include:

* '''Unnecessary steep learning curve'''
* '''Features or options not being discovered'''
* '''General frustration''' - clunkiness, a certain ''je ne sais quoi''

=== The navigation is not static ===

Sometimes when navigating from one place to another, the state of the tree in the navigation block completely changes. A good example of this is when going from a course to a module - upon arrival in a module, the Administration block will display a collapsed 'Course administration' node and a new expanded 'Module administration' node, as illustrated below.

[[File:pbnotstatic.png|frame|none|alt=Going from course to a module.|Going from course to a module.]]

Consistency should be improved here, as it is unlikely that a user unfamiliar with the system will understand sudden collapsing of or additional nodes.

=== Feature placement ===

It is our opinion that some navigation nodes contain things that you wouldn't expect, and don't contain things that you '''would'' expect. For example:

* 'My profile settings' contains 'Blogs', 'Badges' or 'Messaging'. These are not strictly related to your profile, they are related to your user account.
* What can be found under 'Site pages'?
* Notes
** In order to view Notes taken on a course level, I first need to click on 'Participants', and once the page is loaded I can see new entries in the navigation node 'Participants'. Why is this the case? Most users will not be aware of those links and will miss out on that feature, we feel.

=== Bad naming ===

Proper naming of the navigation helps the user remembering where to find what they are looking for. It also helps them to discover features that they would not otherwise be aware of, e.g. 'Calendar', hidden under 'Site pages'. If a user has no understanding of what 'Site pages' is, it is unlikely that they will expand it.

Another popular(?) example of bad naming is the link 'My grades' under 'Course administration' in the 'Administration' block. 'A student is not administrating anything, his grades are not a setting.'

=== Context jumps ===

The breadcrumb and navigation sometimes jump from one context to another. For instance, as a student when you click on 'Administration > Course administration > My grades', the navigation node on which you appear to be after clicking is 'Administration > Grade administration > User report'.

[[File:pbcontextjumps.png|frame|none|alt=Breadcrumb context jumping.|Breadcrumb context jumping.]]

It is also possible for the user to jump from a course context to a site context, leaving the course (different breadcrumb, different navigation) without realising it and instantly feeling lost. A common reaction would be to use the 'Back' button of their browser to recover from it rather than trying to understand what happened. This behaviour can be observed when visiting someone's profile, viewing some reports, etc...

[[File:pbcontextjumps2.png|frame|none|alt=Navigation context jumping.|Navigation context jumping.]]

In order for users to feel comfortable and confident, and to not feel lost in Moodle's complex page hierarchy, we need to prevent situations where they feel lost and frustrated.

=== Overwhelming the user ===

Both the navigation block and the administration block can potentially have lots of nodes in them, resulting in what is popularly derided as the "scroll of death". We posit that a good navigation system should be simple and concise, and not necessarily contain the entire site map.

== The goal ==

We seek to provide navigation that is:

* Simpler
* Intuitive
* Easy to learn

Leading to myriad benefits, including but not limited to:

; Efficiency
: Less trial and error when looking for something
; Common expectations being met
: Pages being found where you expect them to be
; A reduction in confusion and general frustration
; Less resistance
: New users feeling more confident using the product

Some risk does present itself; by changing large sections of the product, we risk alienating existing experienced Moodle users, frustrated at not finding pages where they used to be. On the other hand, re-learning the navigation should be straightforward, painless and at the very least easier than learning it the first time. User documentation will also suffer in the interim, as screenshots, navigation patterns and other training materials will have to be updated.

== Rough ideas ==

The following is a list of ideas gathered from discussions and resources both internal and external to HQ:

* A student should be able to quickly access his courses, grades, settings, profile from a static place in the UI. This would remove the need for them to expand nodes in both the 'Navigation' block and the 'Administration' block.
* The different nodes of the 'Administration' block could be displayed on a 'Preferences' page.
** e.g. the 'Course administration' items could be listed on a page, each node being a title and each of its elements listed underneath. By moving administration settings to a single page, we obviate the need for the 'Administration' block entirely.
* A teacher should be able to quickly access the 'Options' of a course through a static node, the same way a user can access anything associated to his account.
* Similarly for modules, an easy dropdown to access module preferences and more frequently used options could be created.
* Breadcrumb-based navigation to reduce and perhaps entirely remove the the need for the nested and cumbersome Navigation block.
** This could be problematic in regards to creating problems with accessing site pages, or pages which do not clearly have a hierarchical position. This could be addressed by providing 'in context' links. For instance, adding a new block entry should be available from the Blog page.
* Providing a sitemap page to counter the lack of 'Navigation' block when something is not easily accessible.
* Ability to 'Star' some pages to quickly access favourites.
* Develop a 'Smart search' to easily access the content in the current course, other courses, etc… and the admin settings for admins.
* Populating my/ page with more useful content for the user itself.
* A new profile page on which is displayed the 'public' information of the user. Their forum interactions, their blog, their reports, ...
* Providing an API to modules to implement their own navigation, thus not required to inject links in the navigation block like 'Chat' is doing or 'Quiz' used to do (Results report). This navigation would be displayed in a standard fashion across modules. (Tabs like in wiki?)
* When hovering a user's name, a menu could appear with a few details and links to their profile, etc... (like Jira does).

== Analysis of popular themes ==

Although most of those themes do not change anything about the navigation itself, a few have implemented a ''user menu''. Usually displayed at the top most right of the screen, it contains links to quickly access user specific pages. The most common links are:

* View profile
* Edit profile
* Logout

Less popular links are:

* Calendar
* My private files
* My home

== The solutions ==

To achieve our goal we have to remove the need for the administration and navigation blocks. This is a long process that needs to be broken down into sub-solutions. Some will need to be developed simultaneously to avoid half-baked temporary solutions. Those solutions can be split into two categories: 'User', and 'Course'.

User solutions:

* A user menu
* A user preferences page
* A new profile page
* Revisiting 'My home' page

Course solutions:

* Handling of course profiles
* A course 'Quick access' menu
* An administration page per module
* An administration page for the course
* Dedicated solution to access reports
* Alternative site and course navigation

=== User menu ===

The user menu is a dropdown containing links to pages specific to user. They are context independent and will always point to the same pages. The user menu can always be found at the same place in the user interface and will contain the following links:

* My home
* My profile
* My grades
* Messages
* Logout

[[File:usermenu.png|frame|none|alt=A user menu.|A user menu.]]

'''Benefits'''

* Gives quick and intuitive access to the user specific pages
* Trimming down 'Navigation > My profile'
* Emphasises the page 'My home'

=== User preferences page ===

A link to that page would be placed in the user menu. That page will contain most of what the user has control over on a site level. Their mailing preferences, changing their password, etc... but reorganised.

[[File:userpreferences.png|frame|none|alt=User preferences page.|User preferences page.]]

'''Benefits'''

* We can remove 'My profile settings' from the 'Administration' block.
* The settings are all reachable from one place.
* New pages will help the user understanding what settings they have control over.

=== A new profile page ===

By adding new content to the profile page, we can trim a bit more the navigation block. The profile page is supposed to contain anything you could find about a user, and there will be links to their blog, forum interactions, notes, to send them a message, etc...

We will keep the distinction between the full profile and the course profiles, at this stage we only improve the site profile because the course profiles need more thoughts and are tied to the course solutions.

'''Benefits'''

* Trimming down 'Navigation > My profile'
* Answering concerns of the 'User preferences page'
* Bonus: the profile page has a reason to be visited

=== Revisiting 'My home' page ===

The My/ page is underused and does not contain enough valuable information for the users to visit it. We will update it to include more user-specific content. It will contain:

* My courses
* My private files
* The calendar and upcoming events
* My latest badges

[[File:myhome.png|frame|none|alt=The new dashboard.|The new dashboard.]]

'''Benefits'''

* Trimming down 'Navigation > My profile', at this point it should be empty
* Making the my/ page more interesting and valuable

=== Handling of course profiles ===

We need to remove the confusion between site and course profiles, only a few more informations should be available when viewing a 'Course profile', but we do not need an entirely different profile for that purpose. The course specific information will be accessible from the user profile, but be in the context of the site profile.

'''Benefits'''

* No more course profile pages

=== A course 'Quick access' menu ===

In order to remove the need for the nodes 'Participants' and 'Badges' from the 'Course' entry in the 'Navigation block', and the 'Grades' entry in the 'Course administration' node (for students), we will implement a new 'Quick access' menu for the course. This menu will be accessible on any page within a course, or module.

This menu will only contain links to the 3 entries mentioned above. If later on we add more links to that list, the additional (and less important) entries will be displayed in a dropdown, or a in a 'More' page.

A new grades page will be created for students to access their course grades.

It is important to keep the visible elements of this menu to a minimum. Not more than 3 elements should be displayed at a time. An exception can be made for users with more privileges who will see a 'Settings' (or 'Administration') link, and perhaps a 'Reports' one when we will work on them (see the following the other solutions below).

To unenrol yourself from a course, you would not look into the 'Course administration' node, you would rather find a link on 'My home' page next to the list of courses to unenrol yourself from them.

[[File:coursemenu.png|frame|none|alt=An example of a course quick-access menu.|An example of a course quick-access menu.]]

'''Benefits'''

* Trimming the navigation block
* Removing the 'Course administration' node for students
* Dedicated grades page for the students
* Quick access to the most important pages of a course

=== An administration page per module ===

The same way we would have a 'Preferences' page for the user, the administration page for the module would list everything that was originally in the 'Module administration' node, but reorganised to be more intuitive. A link to that page would be placed somewhere in the general UI.

Modules currently using the 'Adminstration' block to inject new pages into their module should be updated to provide a module navigation instead. It could be a list of links in the module page, or a module navigation such as tabs, this is probably tied to the solution 'Alternative site and course navigation'.

'''Benefits'''

* Intuitive access to all the module administration pages
* Self-contained and self-explanatory
* Removes the need for the 'Module administration' node

'''Concerns'''

* Potentially more clicks-to-destination

=== An administration page for the course ===

The same way we would have a 'Preferences' page for the user, the administration page for the course would list everything that was originally in the 'Course administration' node, but reorganised to be more intuitive. A link to that page will be added to the course 'Quick access' menu.

'''Benefits'''

* Intuitive access to all the course administration pages
* Self-contained and self-explanatory
* No more 'Course administration' node

'''Concerns'''

* Potentially more clicks-to-destination
* Reports would be accessible from that page until 'Dedicated solution to access reports' is implemented

=== Dedicated solution to access reports ===

Reports are the black sheep of the navigation, nobody agrees on where they should be and they are moved around every so often. Perhaps nobody agrees because they do not belong either in the navigation or the administration block.

Currently they are accessed from the 'Administration' block, and as we are moving the content of the block to administration pages, that is where they will end up. This is surely not better (perhaps even worse) than where they were before, so why not thinking once and for all where they should be.

<pre>/!\ Solution needed!

Idea: We could add a 'Report' menu to the course 'Quick access' menu</pre>

'''Goals'''

* Standardised way to access reports
* A navigation that does not jump somewhere else when viewing a report

=== Alternative site and course navigation ===

Now that everything has been sorted out, we should now be able to remove the navigation block - but first we'll need to sort out how to navigate at both the site and course levels.

'''Site level'''
It is envisaged that the frontpage would just be an entry point, with the navigation node 'Site pages' displayed in a block specific to those site pages. Upon leaving the context of the 'Site', you will be in a course; most users will not go back to the front page, except to find some information specific to their institution. To navigate between their courses, teachers and students could refer to their my/ page.

Alternatively, pages like 'Participants', 'Badges' or 'Tags' could be accessed from their context, for instance in a 'Online users' block which would link to 'All participants'. The same applies for 'Calendar', but is already the case because of its block.

'''Course level'''
The site-level concept should disappear as soon as you get in a course; the student or teacher would then focus 100% on the course they are browsing rather than being distracted by site elements. This behavior is currently exhibited by the base and standard themes in 2.6 and before.

The course format will become responsible for most of the navigation in the course, allowing course formats to:

* Inject block(s) to navigate between sections
* Inject block(s) to navigate between modules
* Inject block(s) that does/do both of the above (very similar to the course node in the navigation block)
* Inject links 'Go to next activity', 'Go back to course', ... into module views.

The course format will also have control over the course 'Quick access' menu, in which it could inject/remove items if they wanted to.

The node 'Switch role' will be removed from the administration block, necessitating a 'Switch role' block to be added to the course to unlock that functionality. This block would only be displayed to users having the capabilities to switch role.

'''Future of the Administration block'''

At this point, the administration block will not be displayed to any user, except those users possessing elevated privileges. Administrators, managers or course creators will still have access to the administration block but it will only contain the 'Site administration' node.

== Implementation details ==

=== User context ===

All the pages on a user context will all have their own layout where the header includes the name of the user in a standardised way, along with some information and a link to message them, and their preferences if the logged in user has the capabilities to edit them. A renderer will be responsible for creating the header, and will use the user ID found from the context defined on that page.

The navigation within the context pages will be:

; For your own context
: Home > Your Name > Page you are on. Clicking on 'Your Name' will lead you to 'My home'.

[[File:userheader.png|frame|none|alt=The header when viewing your context.|The header when your context.]]

; For other users' context
: Home > Users > User Name > Page you are on. Clicking on 'User Name' will lead you to their profile.

[[File:userheader2.png|frame|none|alt=The header when viewing someone else's context.|The header when viewing someone else's context.]]

==== Rules ====

The user header contains very simplistic information about the user, and a few links to very common actions in regard to other users. For instance it can implement a link to send a message to the user, because you might want to be able to do that regardless of what user context page you are visiting. But, 'Edit profile' should not be in it, because it is only relevant to the profile. It is very important to keep the number of available actions to a minimum, because having too many options would defeat the purpose of the simplicity and efficiency it is trying to achieve.

=== A user menu ===

The new user menu would be a new renderer, called from the layout files as it was the case for the login info renderer. The content of the user menu is fixed and not configurable, however it is possible to override the renderer from a theme to change its layout and content.

==== Design ====

Placed on the top right of the site, the name of the user is displayed next to a user icon. The dropdown is displayed when the user clicks the icon or the name. On smaller screens only a user icon is displayed, and expands to reveal its content. When expanded the name of the user logged in is displayed.

When the user is not logged in, a login link is displayed, regardless of the screen size.

==== My grades ====

The 'My grades' page will display the overall grades of the student in all their visible courses. The ordering can be changed, but the default would be alphabetical.

==== Login as ====

When logged in as someone else, the 'Logout' entry becomes 'Return to Admin User'.

==== Switch role ====

When the user role is switched, the 'Logout' entry becomes 'Return to my normal role'. And the name of the user is appended with the role they switch to, e.g. 'Admin User (teacher)'.

==== Trimming navigation ====

At this stage we could trim the navigation block, but we decide not to remove anything just yet as it would create more confusion: some nodes would accessible from the user menu, and others from the navigation block.

==== Rules ====

For it to be used, the user menu needs to be as short as possible and not being cluttered with additional links. It should contain what has been decided upon above, and not be changed - as users will acclimatise to it, adding and removing nodes should not be looked upon lightly. In any case, it should not contain more than 6 links, and should always contain:

* My home
* My profile
* Preferences
* Logout

These are very important to the user as they target user context-specific pages and nothing related to the site structure or the course. A link to 'My courses' would be redundant as this information should be covered in the 'My home' page.

=== A user preferences page ===

The preferences page is a list of links to sub-preferences page. The page will be generated from the navigation node 'My profile settings', though we will have to re-organise them so that each link belongs to a parent node. A link to the preferences page is added to the user menu.

==== Re-organisation ====

* User account
** Edit profile
** Account settings
** Change password
** Security keys
** Messaging

* Blogs
** Preferences
** External blogs
** Register an external blog

* Badges
** Manage my badges
** Preferences
** Backpack settings

The preferences page displays headings (the setting nodes) under which the links to the sub-pages will be displayed.

[[File:userpreferences.png|frame|none|alt=User preferences page.|User preferences page.]]

The nodes 'Roles' and 'Activity reports' will not be part of this page, because they are context based: they point to the course or site context depending on the page we are on. They will remain in the navigation block, but only when the user has the capability to view them. When the only node in the 'My profile settings' node is 'Preferences', then 'My profile settings' is not displayed. Here is an example when you have the capability to view the reports and roles.

[[File:navblockpref.png|frame|none|alt=My profile settings node with extended capability.|My profile settings node with extended capability.]]

==== Naming ====

The 'My profile settings' node becomes the name of the user: 'Frédéric Massart'. The 'Profile settings for Jetha Chan' becomes 'Jetha Chan'.

==== Breadcrumb ====

Each of the sub-pages should be checked to ensure that they are in the right hierarchy, the breadcrumb always looks like '(User context nav) > Preferences > Preference heading > Page I am on'.

==== Another user's preferences ====

The node 'Profile settings for User B' can be used to edit someone's settings. The content is similar to 'My profile settings', except that the node will always be displayed regardless of the presence of 'Roles' or 'Activity reports'. Currently there is no other way for a user with elevated privileges to access someone's preferences, but sooner or later the preferences will be accessible from their profiles.

[[File:navblocksomeonelse.png|frame|none|alt=Profile settings for X with extended capability.|Profile settings for X node with extended capability.]]

==== Repositories ====

At present, repositories are configurable from the Navigation block - this is a good opportunity to move them to the 'Preferences' page.

==== Rules ====

Every link in this page should belong to a section, the sections are only headers that help the users finding what they are looking for. A plugin that adds user preferences related to its features should define a new heading and add its links to that heading. The heading is never clickable.

=== A new profile page ===

For now we will only be focussing on the site profile of the user. Later on, we will be solving the problems linked to the course context, for instances the links to 'Blog' or 'Forum interactions' automatically filtered to only display the blog posts in the course.

==== Content ====

The contact details will be displayed in such a way that they do not look like a list any more. For instance, everyone knows what an email address is, there is no need to prefix it with 'Email address:'.

The badges will be displayed on the profile too.

==== Links ====

* Edit profile (If this is your profile)
* Blog
* Forum interactions
* Notes (If you have the capability to)
* Preferences (If you have the capability to and are viewing someone's profile)
* Send a message
* Login as (If you have the capability to)

==== Navigation block ====

We can start trimming the node 'My profile' a bit, but some nodes will remain until we sort out the 'My' page. When doing so, it is important to make sure that the nodes 'Home > Some course > Participants > User B' still contain everything it does right now, because those links point to course-based pages, and would not be accessible otherwise.

==== Rules ====

The profile page contains everything about the user that is public. In other words, a content specific to the user should not be displayed on the profile at all, because it would never be accessible to another user, e.g. 'Private files'.

There are exceptions to this rule, badges for example. As a setting allows you to define whether or not your badges are on your profile, you might not be able to see them there, so they should be available on your dashboard.

For content controlled by permissions (and not preferences), they should remain on the profile. Take 'Blog' as an example, an administrator can prevent blog entries from another user to be accessed depending on your role. As the user does not have any information about the roles of the other users, the blog link is displayed on the profile, but other users will not see it. Having a blog block on the 'My home' page would not be useful because it simply duplicates the access points, for no apparent reason to the user.

=== Revisiting 'My home' page ===

We need to add more default blocks to the existing page, the different available blocks will be:

* My courses (already there)
* My private files (already there)
* The calendar
* Upcoming events
* My latest badges

We need to add a link to 'My latest badges' to the page listing all the badges.

==== Navigation block ====

We can now remove 'My profile' (or now called 'Jetha Chan') from the navigation block entirely. But it has to still be accessible under the node of a user in a course tree.

The node 'My courses' is also removed, users should be used to using their dashboard to access their courses.

==== Rules ====

The 'My home' page contains everything about a user that is private and not accessible to other users. For instance, your calendar events or your private files. The list of courses you are enrolled in are an exception, they could be displayed on the user profile, but because they are so important and need to be layed out in useful fashion, they will be part of the 'My home' page.

This page does not need to link to pages which are already accessible from the 'User menu', for instance the profile.

=== Course context ===

<pre>Pending</pre>

* Handling of course profiles
* An administration page per module
* An administration page for the course
* Accessing course grades for students
* Dedicated solution to access reports
* Alternative site and course navigation
** Checking for inconsistencies in the breadcrumb jumping from one place to another.

== Roadmap ==

=== User context ===

# The user menu
# Implementing the user 'header' for user context pages
# The preferences page
# The new profile page
# Revisiting 'My home'

=== Course context ===

<pre>To be defined.</pre>

== Related links ==

* [https://docs.google.com/document/d/16BJsINun13StUFOQaejj3Gawz9jk22ir_r49f3MbInM/edit#heading=h.fuvsbkikzj88 Navigation experiment]
* [https://docs.google.com/document/d/1AXJw8uX6MczA5VC3phkVVv1ee5eZ2nluIiPC2ecgHLE/edit#heading=h.k3lh9alzq3iy Navigation prototyping 2.7]
* MDL-34838: Navigation inconsistencies
* [http://demo2k12.moodlerooms.com Minimal by Moodlerooms]
* [https://moodle.org/mod/forum/discuss.php?d=226791 Users’ personalised profiles]

Navigation overhaul specification

2014-05-30T09:26:07Z

Jethac: /* Alternative site and course navigation */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45774
|discussion = -
|assignee = Frédéric Massart, Jetha Chan
}}

{{Work in progress}}

Navigation throughout Moodle is often confusing and needs some improvement. With this in mind, a specification has been prepared, defining what problems were identified and how they will be solved. Particular focus will be placed upon improving the experience of students, teachers, and users unfamiliar to Moodle.

== What can be improved ==

Common complaints leveled at Moodle include:

* '''Unnecessary steep learning curve'''
* '''Features or options not being discovered'''
* '''General frustration''' - clunkiness, a certain ''je ne sais quoi''

=== The navigation is not static ===

Sometimes when navigating from one place to another, the state of the tree in the navigation block completely changes. A good example of this is when going from a course to a module - upon arrival in a module, the Administration block will display a collapsed 'Course administration' node and a new expanded 'Module administration' node, as illustrated below.

[[File:pbnotstatic.png|frame|none|alt=Going from course to a module.|Going from course to a module.]]

Consistency should be improved here, as it is unlikely that a user unfamiliar with the system will understand sudden collapsing of or additional nodes.

=== Feature placement ===

It is our opinion that some navigation nodes contain things that you wouldn't expect, and don't contain things that you '''would'' expect. For example:

* 'My profile settings' contains 'Blogs', 'Badges' or 'Messaging'. These are not strictly related to your profile, they are related to your user account.
* What can be found under 'Site pages'?
* Notes
** In order to view Notes taken on a course level, I first need to click on 'Participants', and once the page is loaded I can see new entries in the navigation node 'Participants'. Why is this the case? Most users will not be aware of those links and will miss out on that feature, we feel.

=== Bad naming ===

Proper naming of the navigation helps the user remembering where to find what they are looking for. It also helps them to discover features that they would not otherwise be aware of, e.g. 'Calendar', hidden under 'Site pages'. If a user has no understanding of what 'Site pages' is, it is unlikely that they will expand it.

Another popular(?) example of bad naming is the link 'My grades' under 'Course administration' in the 'Administration' block. 'A student is not administrating anything, his grades are not a setting.'

=== Context jumps ===

The breadcrumb and navigation sometimes jump from one context to another. For instance, as a student when you click on 'Administration > Course administration > My grades', the navigation node on which you appear to be after clicking is 'Administration > Grade administration > User report'.

[[File:pbcontextjumps.png|frame|none|alt=Breadcrumb context jumping.|Breadcrumb context jumping.]]

It is also possible for the user to jump from a course context to a site context, leaving the course (different breadcrumb, different navigation) without realising it and instantly feeling lost. A common reaction would be to use the 'Back' button of their browser to recover from it rather than trying to understand what happened. This behaviour can be observed when visiting someone's profile, viewing some reports, etc...

[[File:pbcontextjumps2.png|frame|none|alt=Navigation context jumping.|Navigation context jumping.]]

In order for users to feel comfortable and confident, and to not feel lost in Moodle's complex page hierarchy, we need to prevent situations where they feel lost and frustrated.

=== Overwhelming the user ===

Both the navigation block and the administration block can potentially have lots of nodes in them, resulting in what is popularly derided as the "scroll of death". We posit that a good navigation system should be simple and concise, and not necessarily contain the entire site map.

== The goal ==

We seek to provide navigation that is:

* Simpler
* Intuitive
* Easy to learn

Leading to myriad benefits, including but not limited to:

; Efficiency
: Less trial and error when looking for something
; Common expectations being met
: Pages being found where you expect them to be
; A reduction in confusion and general frustration
; Less resistance
: New users feeling more confident using the product

Some risk does present itself; by changing large sections of the product, we risk alienating existing experienced Moodle users, frustrated at not finding pages where they used to be. On the other hand, re-learning the navigation should be straightforward, painless and at the very least easier than learning it the first time. User documentation will also suffer in the interim, as screenshots, navigation patterns and other training materials will have to be updated.

== Rough ideas ==

The following is a list of ideas gathered from discussions and resources both internal and external to HQ:

* A student should be able to quickly access his courses, grades, settings, profile from a static place in the UI. This would remove the need for them to expand nodes in both the 'Navigation' block and the 'Administration' block.
* The different nodes of the 'Administration' block could be displayed on a 'Preferences' page.
** e.g. the 'Course administration' items could be listed on a page, each node being a title and each of its elements listed underneath. By moving administration settings to a single page, we obviate the need for the 'Administration' block entirely.
* A teacher should be able to quickly access the 'Options' of a course through a static node, the same way a user can access anything associated to his account.
* Similarly for modules, an easy dropdown to access module preferences and more frequently used options could be created.
* Breadcrumb-based navigation to reduce and perhaps entirely remove the the need for the nested and cumbersome Navigation block.
** This could be problematic in regards to creating problems with accessing site pages, or pages which do not clearly have a hierarchical position. This could be addressed by providing 'in context' links. For instance, adding a new block entry should be available from the Blog page.
* Providing a sitemap page to counter the lack of 'Navigation' block when something is not easily accessible.
* Ability to 'Star' some pages to quickly access favourites.
* Develop a 'Smart search' to easily access the content in the current course, other courses, etc… and the admin settings for admins.
* Populating my/ page with more useful content for the user itself.
* A new profile page on which is displayed the 'public' information of the user. Their forum interactions, their blog, their reports, ...
* Providing an API to modules to implement their own navigation, thus not required to inject links in the navigation block like 'Chat' is doing or 'Quiz' used to do (Results report). This navigation would be displayed in a standard fashion across modules. (Tabs like in wiki?)
* When hovering a user's name, a menu could appear with a few details and links to their profile, etc... (like Jira does).

== Analysis of popular themes ==

Although most of those themes do not change anything about the navigation itself, a few have implemented a ''user menu''. Usually displayed at the top most right of the screen, it contains links to quickly access user specific pages. The most common links are:

* View profile
* Edit profile
* Logout

Less popular links are:

* Calendar
* My private files
* My home

== The solutions ==

To achieve our goal we have to remove the need for the administration and navigation blocks. This is a long process that needs to be broken down into sub-solutions. Some will need to be developed simultaneously to avoid half-baked temporary solutions. Those solutions can be split into two categories: 'User', and 'Course'.

User solutions:

* A user menu
* A user preferences page
* A new profile page
* Revisiting 'My home' page

Course solutions:

* Handling of course profiles
* A course 'Quick access' menu
* An administration page per module
* An administration page for the course
* Dedicated solution to access reports
* Alternative site and course navigation

=== User menu ===

The user menu is a dropdown containing links to pages specific to user. They are context independent and will always point to the same pages. The user menu can always be found at the same place in the user interface and will contain the following links:

* My home
* My profile
* My grades
* Messages
* Logout

[[File:usermenu.png|frame|none|alt=A user menu.|A user menu.]]

'''Benefits'''

* Gives quick and intuitive access to the user specific pages
* Trimming down 'Navigation > My profile'
* Emphasises the page 'My home'

=== User preferences page ===

A link to that page would be placed in the user menu. That page will contain most of what the user has control over on a site level. Their mailing preferences, changing their password, etc... but reorganised.

[[File:userpreferences.png|frame|none|alt=User preferences page.|User preferences page.]]

'''Benefits'''

* We can remove 'My profile settings' from the 'Administration' block.
* The settings are all reachable from one place.
* New pages will help the user understanding what settings they have control over.

=== A new profile page ===

By adding new content to the profile page, we can trim a bit more the navigation block. The profile page is supposed to contain anything you could find about a user, and there will be links to their blog, forum interactions, notes, to send them a message, etc...

We will keep the distinction between the full profile and the course profiles, at this stage we only improve the site profile because the course profiles need more thoughts and are tied to the course solutions.

'''Benefits'''

* Trimming down 'Navigation > My profile'
* Answering concerns of the 'User preferences page'
* Bonus: the profile page has a reason to be visited

=== Revisiting 'My home' page ===

The My/ page is underused and does not contain enough valuable information for the users to visit it. We will update it to include more user-specific content. It will contain:

* My courses
* My private files
* The calendar and upcoming events
* My latest badges

[[File:myhome.png|frame|none|alt=The new dashboard.|The new dashboard.]]

'''Benefits'''

* Trimming down 'Navigation > My profile', at this point it should be empty
* Making the my/ page more interesting and valuable

=== Handling of course profiles ===

We need to remove the confusion between site and course profiles, only a few more informations should be available when viewing a 'Course profile', but we do not need an entirely different profile for that purpose. The course specific information will be accessible from the user profile, but be in the context of the site profile.

'''Benefits'''

* No more course profile pages

=== A course 'Quick access' menu ===

In order to remove the need for the nodes 'Participants' and 'Badges' from the 'Course' entry in the 'Navigation block', and the 'Grades' entry in the 'Course administration' node (for students), we will implement a new 'Quick access' menu for the course. This menu will be accessible on any page within a course, or module.

This menu will only contain links to the 3 entries mentioned above. If later on we add more links to that list, the additional (and less important) entries will be displayed in a dropdown, or a in a 'More' page.

A new grades page will be created for students to access their course grades.

It is important to keep the visible elements of this menu to a minimum. Not more than 3 elements should be displayed at a time. An exception can be made for users with more privileges who will see a 'Settings' (or 'Administration') link, and perhaps a 'Reports' one when we will work on them (see the following the other solutions below).

To unenrol yourself from a course, you would not look into the 'Course administration' node, you would rather find a link on 'My home' page next to the list of courses to unenrol yourself from them.

[[File:coursemenu.png|frame|none|alt=An example of a course quick-access menu.|An example of a course quick-access menu.]]

'''Benefits'''

* Trimming the navigation block
* Removing the 'Course administration' node for students
* Dedicated grades page for the students
* Quick access to the most important pages of a course

=== An administration page per module ===

The same way we would have a 'Preferences' page for the user, the administration page for the module would list everything that was originally in the 'Module administration' node, but reorganised to be more intuitive. A link to that page would be placed somewhere in the general UI.

The modules abusing the 'Adminstration' block to inject new pages into their module should be updated to provide a module navigation instead. It could be a list of links in the module page, or a module navigation such as tabs, this is probably tied to the solution 'Alternative site and course navigation'.

'''Benefits'''

* Intuitive access to all the module administration pages
* Self-contained and self-explanatory
* Removes the need for the 'Module administration' node

'''Concerns'''

* Potentially more clicks-to-destination

=== An administration page for the course ===

The same way we would have a 'Preferences' page for the user, the administration page for the course would list everything that was originally in the 'Course administration' node, but reorganised to be more intuitive. A link to that page will be added to the course 'Quick access' menu.

'''Benefits'''

* Intuitive access to all the course administration pages
* Self-contained and self-explanatory
* No more 'Course administration' node

'''Concerns'''

* Potentially more clicks-to-destination
* Reports would be accessible from that page until 'Dedicated solution to access reports' is implemented

=== Dedicated solution to access reports ===

Reports are the black sheep of the navigation, nobody agrees on where they should be and they are moved around every so often. Perhaps nobody agrees because they do not belong either in the navigation or the administration block.

Currently they are accessed from the 'Administration' block, and as we are moving the content of the block to administration pages, that is where they will end up. This is surely not better (perhaps even worse) than where they were before, so why not thinking once and for all where they should be.

<pre>/!\ Solution needed!

Idea: We could add a 'Report' menu to the course 'Quick access' menu</pre>

'''Goals'''

* Standardised way to access reports
* A navigation that does not jump somewhere else when viewing a report

=== Alternative site and course navigation ===

Now that everything has been sorted out, we should now be able to remove the navigation block - but first we'll need to sort out how to navigate at both the site and course levels.

'''Site level'''
It is envisaged that the frontpage would just be an entry point, with the navigation node 'Site pages' displayed in a block specific to those site pages. Upon leaving the context of the 'Site', you will be in a course; most users will not go back to the front page, except to find some information specific to their institution. To navigate between their courses, teachers and students could refer to their my/ page.

Alternatively, pages like 'Participants', 'Badges' or 'Tags' could be accessed from their context, for instance in a 'Online users' block which would link to 'All participants'. The same applies for 'Calendar', but is already the case because of its block.

'''Course level'''
The site-level concept should disappear as soon as you get in a course; the student or teacher would then focus 100% on the course they are browsing rather than being distracted by site elements. This behavior is currently exhibited by the base and standard themes in 2.6 and before.

The course format will become responsible for most of the navigation in the course, allowing course formats to:

* Inject block(s) to navigate between sections
* Inject block(s) to navigate between modules
* Inject block(s) that does/do both of the above (very similar to the course node in the navigation block)
* Inject links 'Go to next activity', 'Go back to course', ... into module views.

The course format will also have control over the course 'Quick access' menu, in which it could inject/remove items if they wanted to.

The node 'Switch role' will be removed from the administration block, necessitating a 'Switch role' block to be added to the course to unlock that functionality. This block would only be displayed to users having the capabilities to switch role.

'''Future of the Administration block'''

At this point, the administration block will not be displayed to any user, except those users possessing elevated privileges. Administrators, managers or course creators will still have access to the administration block but it will only contain the 'Site administration' node.

== Implementation details ==

=== User context ===

All the pages on a user context will all have their own layout where the header includes the name of the user in a standardised way, along with some information and a link to message them, and their preferences if the logged in user has the capabilities to edit them. A renderer will be responsible for creating the header, and will use the user ID found from the context defined on that page.

The navigation within the context pages will be:

; For your own context
: Home > Your Name > Page you are on. Clicking on 'Your Name' will lead you to 'My home'.

[[File:userheader.png|frame|none|alt=The header when viewing your context.|The header when your context.]]

; For other users' context
: Home > Users > User Name > Page you are on. Clicking on 'User Name' will lead you to their profile.

[[File:userheader2.png|frame|none|alt=The header when viewing someone else's context.|The header when viewing someone else's context.]]

==== Rules ====

The user header contains very simplistic information about the user, and a few links to very common actions in regard to other users. For instance it can implement a link to send a message to the user, because you might want to be able to do that regardless of what user context page you are visiting. But, 'Edit profile' should not be in it, because it is only relevant to the profile. It is very important to keep the number of available actions to a minimum, because having too many options would defeat the purpose of the simplicity and efficiency it is trying to achieve.

=== A user menu ===

The new user menu would be a new renderer, called from the layout files as it was the case for the login info renderer. The content of the user menu is fixed and not configurable, however it is possible to override the renderer from a theme to change its layout and content.

==== Design ====

Placed on the top right of the site, the name of the user is displayed next to a user icon. The dropdown is displayed when the user clicks the icon or the name. On smaller screens only a user icon is displayed, and expands to reveal its content. When expanded the name of the user logged in is displayed.

When the user is not logged in, a login link is displayed, regardless of the screen size.

==== My grades ====

The 'My grades' page will display the overall grades of the student in all their visible courses. The ordering can be changed, but the default would be alphabetical.

==== Login as ====

When logged in as someone else, the 'Logout' entry becomes 'Return to Admin User'.

==== Switch role ====

When the user role is switched, the 'Logout' entry becomes 'Return to my normal role'. And the name of the user is appended with the role they switch to, e.g. 'Admin User (teacher)'.

==== Trimming navigation ====

At this stage we could trim the navigation block, but we decide not to remove anything just yet as it would create more confusion: some nodes would accessible from the user menu, and others from the navigation block.

==== Rules ====

For it to be used, the user menu needs to be as short as possible and not being cluttered with additional links. It should contain what has been decided upon above, and not be changed - as users will acclimatise to it, adding and removing nodes should not be looked upon lightly. In any case, it should not contain more than 6 links, and should always contain:

* My home
* My profile
* Preferences
* Logout

These are very important to the user as they target user context-specific pages and nothing related to the site structure or the course. A link to 'My courses' would be redundant as this information should be covered in the 'My home' page.

=== A user preferences page ===

The preferences page is a list of links to sub-preferences page. The page will be generated from the navigation node 'My profile settings', though we will have to re-organise them so that each link belongs to a parent node. A link to the preferences page is added to the user menu.

==== Re-organisation ====

* User account
** Edit profile
** Account settings
** Change password
** Security keys
** Messaging

* Blogs
** Preferences
** External blogs
** Register an external blog

* Badges
** Manage my badges
** Preferences
** Backpack settings

The preferences page displays headings (the setting nodes) under which the links to the sub-pages will be displayed.

[[File:userpreferences.png|frame|none|alt=User preferences page.|User preferences page.]]

The nodes 'Roles' and 'Activity reports' will not be part of this page, because they are context based: they point to the course or site context depending on the page we are on. They will remain in the navigation block, but only when the user has the capability to view them. When the only node in the 'My profile settings' node is 'Preferences', then 'My profile settings' is not displayed. Here is an example when you have the capability to view the reports and roles.

[[File:navblockpref.png|frame|none|alt=My profile settings node with extended capability.|My profile settings node with extended capability.]]

==== Naming ====

The 'My profile settings' node becomes the name of the user: 'Frédéric Massart'. The 'Profile settings for Jetha Chan' becomes 'Jetha Chan'.

==== Breadcrumb ====

Each of the sub-pages should be checked to ensure that they are in the right hierarchy, the breadcrumb always looks like '(User context nav) > Preferences > Preference heading > Page I am on'.

==== Another user's preferences ====

The node 'Profile settings for User B' can be used to edit someone's settings. The content is similar to 'My profile settings', except that the node will always be displayed regardless of the presence of 'Roles' or 'Activity reports'. Currently there is no other way for a user with elevated privileges to access someone's preferences, but sooner or later the preferences will be accessible from their profiles.

[[File:navblocksomeonelse.png|frame|none|alt=Profile settings for X with extended capability.|Profile settings for X node with extended capability.]]

==== Repositories ====

At present, repositories are configurable from the Navigation block - this is a good opportunity to move them to the 'Preferences' page.

==== Rules ====

Every link in this page should belong to a section, the sections are only headers that help the users finding what they are looking for. A plugin that adds user preferences related to its features should define a new heading and add its links to that heading. The heading is never clickable.

=== A new profile page ===

For now we will only be focussing on the site profile of the user. Later on, we will be solving the problems linked to the course context, for instances the links to 'Blog' or 'Forum interactions' automatically filtered to only display the blog posts in the course.

==== Content ====

The contact details will be displayed in such a way that they do not look like a list any more. For instance, everyone knows what an email address is, there is no need to prefix it with 'Email address:'.

The badges will be displayed on the profile too.

==== Links ====

* Edit profile (If this is your profile)
* Blog
* Forum interactions
* Notes (If you have the capability to)
* Preferences (If you have the capability to and are viewing someone's profile)
* Send a message
* Login as (If you have the capability to)

==== Navigation block ====

We can start trimming the node 'My profile' a bit, but some nodes will remain until we sort out the 'My' page. When doing so, it is important to make sure that the nodes 'Home > Some course > Participants > User B' still contain everything it does right now, because those links point to course-based pages, and would not be accessible otherwise.

==== Rules ====

The profile page contains everything about the user that is public. In other words, a content specific to the user should not be displayed on the profile at all, because it would never be accessible to another user, e.g. 'Private files'.

There are exceptions to this rule, badges for example. As a setting allows you to define whether or not your badges are on your profile, you might not be able to see them there, so they should be available on your dashboard.

For content controlled by permissions (and not preferences), they should remain on the profile. Take 'Blog' as an example, an administrator can prevent blog entries from another user to be accessed depending on your role. As the user does not have any information about the roles of the other users, the blog link is displayed on the profile, but other users will not see it. Having a blog block on the 'My home' page would not be useful because it simply duplicates the access points, for no apparent reason to the user.

=== Revisiting 'My home' page ===

We need to add more default blocks to the existing page, the different available blocks will be:

* My courses (already there)
* My private files (already there)
* The calendar
* Upcoming events
* My latest badges

We need to add a link to 'My latest badges' to the page listing all the badges.

==== Navigation block ====

We can now remove 'My profile' (or now called 'Jetha Chan') from the navigation block entirely. But it has to still be accessible under the node of a user in a course tree.

The node 'My courses' is also removed, users should be used to using their dashboard to access their courses.

==== Rules ====

The 'My home' page contains everything about a user that is private and not accessible to other users. For instance, your calendar events or your private files. The list of courses you are enrolled in are an exception, they could be displayed on the user profile, but because they are so important and need to be layed out in useful fashion, they will be part of the 'My home' page.

This page does not need to link to pages which are already accessible from the 'User menu', for instance the profile.

=== Course context ===

<pre>Pending</pre>

* Handling of course profiles
* An administration page per module
* An administration page for the course
* Accessing course grades for students
* Dedicated solution to access reports
* Alternative site and course navigation
** Checking for inconsistencies in the breadcrumb jumping from one place to another.

== Roadmap ==

=== User context ===

# The user menu
# Implementing the user 'header' for user context pages
# The preferences page
# The new profile page
# Revisiting 'My home'

=== Course context ===

<pre>To be defined.</pre>

== Related links ==

* [https://docs.google.com/document/d/16BJsINun13StUFOQaejj3Gawz9jk22ir_r49f3MbInM/edit#heading=h.fuvsbkikzj88 Navigation experiment]
* [https://docs.google.com/document/d/1AXJw8uX6MczA5VC3phkVVv1ee5eZ2nluIiPC2ecgHLE/edit#heading=h.k3lh9alzq3iy Navigation prototyping 2.7]
* MDL-34838: Navigation inconsistencies
* [http://demo2k12.moodlerooms.com Minimal by Moodlerooms]
* [https://moodle.org/mod/forum/discuss.php?d=226791 Users’ personalised profiles]

Navigation overhaul specification

2014-05-30T09:17:38Z

Jethac: /* Rules */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45774
|discussion = -
|assignee = Frédéric Massart, Jetha Chan
}}

{{Work in progress}}

Navigation throughout Moodle is often confusing and needs some improvement. With this in mind, a specification has been prepared, defining what problems were identified and how they will be solved. Particular focus will be placed upon improving the experience of students, teachers, and users unfamiliar to Moodle.

== What can be improved ==

Common complaints leveled at Moodle include:

* '''Unnecessary steep learning curve'''
* '''Features or options not being discovered'''
* '''General frustration''' - clunkiness, a certain ''je ne sais quoi''

=== The navigation is not static ===

Sometimes when navigating from one place to another, the state of the tree in the navigation block completely changes. A good example of this is when going from a course to a module - upon arrival in a module, the Administration block will display a collapsed 'Course administration' node and a new expanded 'Module administration' node, as illustrated below.

[[File:pbnotstatic.png|frame|none|alt=Going from course to a module.|Going from course to a module.]]

Consistency should be improved here, as it is unlikely that a user unfamiliar with the system will understand sudden collapsing of or additional nodes.

=== Feature placement ===

It is our opinion that some navigation nodes contain things that you wouldn't expect, and don't contain things that you '''would'' expect. For example:

* 'My profile settings' contains 'Blogs', 'Badges' or 'Messaging'. These are not strictly related to your profile, they are related to your user account.
* What can be found under 'Site pages'?
* Notes
** In order to view Notes taken on a course level, I first need to click on 'Participants', and once the page is loaded I can see new entries in the navigation node 'Participants'. Why is this the case? Most users will not be aware of those links and will miss out on that feature, we feel.

=== Bad naming ===

Proper naming of the navigation helps the user remembering where to find what they are looking for. It also helps them to discover features that they would not otherwise be aware of, e.g. 'Calendar', hidden under 'Site pages'. If a user has no understanding of what 'Site pages' is, it is unlikely that they will expand it.

Another popular(?) example of bad naming is the link 'My grades' under 'Course administration' in the 'Administration' block. 'A student is not administrating anything, his grades are not a setting.'

=== Context jumps ===

The breadcrumb and navigation sometimes jump from one context to another. For instance, as a student when you click on 'Administration > Course administration > My grades', the navigation node on which you appear to be after clicking is 'Administration > Grade administration > User report'.

[[File:pbcontextjumps.png|frame|none|alt=Breadcrumb context jumping.|Breadcrumb context jumping.]]

It is also possible for the user to jump from a course context to a site context, leaving the course (different breadcrumb, different navigation) without realising it and instantly feeling lost. A common reaction would be to use the 'Back' button of their browser to recover from it rather than trying to understand what happened. This behaviour can be observed when visiting someone's profile, viewing some reports, etc...

[[File:pbcontextjumps2.png|frame|none|alt=Navigation context jumping.|Navigation context jumping.]]

In order for users to feel comfortable and confident, and to not feel lost in Moodle's complex page hierarchy, we need to prevent situations where they feel lost and frustrated.

=== Overwhelming the user ===

Both the navigation block and the administration block can potentially have lots of nodes in them, resulting in what is popularly derided as the "scroll of death". We posit that a good navigation system should be simple and concise, and not necessarily contain the entire site map.

== The goal ==

We seek to provide navigation that is:

* Simpler
* Intuitive
* Easy to learn

Leading to myriad benefits, including but not limited to:

; Efficiency
: Less trial and error when looking for something
; Common expectations being met
: Pages being found where you expect them to be
; A reduction in confusion and general frustration
; Less resistance
: New users feeling more confident using the product

Some risk does present itself; by changing large sections of the product, we risk alienating existing experienced Moodle users, frustrated at not finding pages where they used to be. On the other hand, re-learning the navigation should be straightforward, painless and at the very least easier than learning it the first time. User documentation will also suffer in the interim, as screenshots, navigation patterns and other training materials will have to be updated.

== Rough ideas ==

The following is a list of ideas gathered from discussions and resources both internal and external to HQ:

* A student should be able to quickly access his courses, grades, settings, profile from a static place in the UI. This would remove the need for them to expand nodes in both the 'Navigation' block and the 'Administration' block.
* The different nodes of the 'Administration' block could be displayed on a 'Preferences' page.
** e.g. the 'Course administration' items could be listed on a page, each node being a title and each of its elements listed underneath. By moving administration settings to a single page, we obviate the need for the 'Administration' block entirely.
* A teacher should be able to quickly access the 'Options' of a course through a static node, the same way a user can access anything associated to his account.
* Similarly for modules, an easy dropdown to access module preferences and more frequently used options could be created.
* Breadcrumb-based navigation to reduce and perhaps entirely remove the the need for the nested and cumbersome Navigation block.
** This could be problematic in regards to creating problems with accessing site pages, or pages which do not clearly have a hierarchical position. This could be addressed by providing 'in context' links. For instance, adding a new block entry should be available from the Blog page.
* Providing a sitemap page to counter the lack of 'Navigation' block when something is not easily accessible.
* Ability to 'Star' some pages to quickly access favourites.
* Develop a 'Smart search' to easily access the content in the current course, other courses, etc… and the admin settings for admins.
* Populating my/ page with more useful content for the user itself.
* A new profile page on which is displayed the 'public' information of the user. Their forum interactions, their blog, their reports, ...
* Providing an API to modules to implement their own navigation, thus not required to inject links in the navigation block like 'Chat' is doing or 'Quiz' used to do (Results report). This navigation would be displayed in a standard fashion across modules. (Tabs like in wiki?)
* When hovering a user's name, a menu could appear with a few details and links to their profile, etc... (like Jira does).

== Analysis of popular themes ==

Although most of those themes do not change anything about the navigation itself, a few have implemented a ''user menu''. Usually displayed at the top most right of the screen, it contains links to quickly access user specific pages. The most common links are:

* View profile
* Edit profile
* Logout

Less popular links are:

* Calendar
* My private files
* My home

== The solutions ==

To achieve our goal we have to remove the need for the administration and navigation blocks. This is a long process that needs to be broken down into sub-solutions. Some will need to be developed simultaneously to avoid half-baked temporary solutions. Those solutions can be split into two categories: 'User', and 'Course'.

User solutions:

* A user menu
* A user preferences page
* A new profile page
* Revisiting 'My home' page

Course solutions:

* Handling of course profiles
* A course 'Quick access' menu
* An administration page per module
* An administration page for the course
* Dedicated solution to access reports
* Alternative site and course navigation

=== User menu ===

The user menu is a dropdown containing links to pages specific to user. They are context independent and will always point to the same pages. The user menu can always be found at the same place in the user interface and will contain the following links:

* My home
* My profile
* My grades
* Messages
* Logout

[[File:usermenu.png|frame|none|alt=A user menu.|A user menu.]]

'''Benefits'''

* Gives quick and intuitive access to the user specific pages
* Trimming down 'Navigation > My profile'
* Emphasises the page 'My home'

=== User preferences page ===

A link to that page would be placed in the user menu. That page will contain most of what the user has control over on a site level. Their mailing preferences, changing their password, etc... but reorganised.

[[File:userpreferences.png|frame|none|alt=User preferences page.|User preferences page.]]

'''Benefits'''

* We can remove 'My profile settings' from the 'Administration' block.
* The settings are all reachable from one place.
* New pages will help the user understanding what settings they have control over.

=== A new profile page ===

By adding new content to the profile page, we can trim a bit more the navigation block. The profile page is supposed to contain anything you could find about a user, and there will be links to their blog, forum interactions, notes, to send them a message, etc...

We will keep the distinction between the full profile and the course profiles, at this stage we only improve the site profile because the course profiles need more thoughts and are tied to the course solutions.

'''Benefits'''

* Trimming down 'Navigation > My profile'
* Answering concerns of the 'User preferences page'
* Bonus: the profile page has a reason to be visited

=== Revisiting 'My home' page ===

The My/ page is underused and does not contain enough valuable information for the users to visit it. We will update it to include more user-specific content. It will contain:

* My courses
* My private files
* The calendar and upcoming events
* My latest badges

[[File:myhome.png|frame|none|alt=The new dashboard.|The new dashboard.]]

'''Benefits'''

* Trimming down 'Navigation > My profile', at this point it should be empty
* Making the my/ page more interesting and valuable

=== Handling of course profiles ===

We need to remove the confusion between site and course profiles, only a few more informations should be available when viewing a 'Course profile', but we do not need an entirely different profile for that purpose. The course specific information will be accessible from the user profile, but be in the context of the site profile.

'''Benefits'''

* No more course profile pages

=== A course 'Quick access' menu ===

In order to remove the need for the nodes 'Participants' and 'Badges' from the 'Course' entry in the 'Navigation block', and the 'Grades' entry in the 'Course administration' node (for students), we will implement a new 'Quick access' menu for the course. This menu will be accessible on any page within a course, or module.

This menu will only contain links to the 3 entries mentioned above. If later on we add more links to that list, the additional (and less important) entries will be displayed in a dropdown, or a in a 'More' page.

A new grades page will be created for students to access their course grades.

It is important to keep the visible elements of this menu to a minimum. Not more than 3 elements should be displayed at a time. An exception can be made for users with more privileges who will see a 'Settings' (or 'Administration') link, and perhaps a 'Reports' one when we will work on them (see the following the other solutions below).

To unenrol yourself from a course, you would not look into the 'Course administration' node, you would rather find a link on 'My home' page next to the list of courses to unenrol yourself from them.

[[File:coursemenu.png|frame|none|alt=An example of a course quick-access menu.|An example of a course quick-access menu.]]

'''Benefits'''

* Trimming the navigation block
* Removing the 'Course administration' node for students
* Dedicated grades page for the students
* Quick access to the most important pages of a course

=== An administration page per module ===

The same way we would have a 'Preferences' page for the user, the administration page for the module would list everything that was originally in the 'Module administration' node, but reorganised to be more intuitive. A link to that page would be placed somewhere in the general UI.

The modules abusing the 'Adminstration' block to inject new pages into their module should be updated to provide a module navigation instead. It could be a list of links in the module page, or a module navigation such as tabs, this is probably tied to the solution 'Alternative site and course navigation'.

'''Benefits'''

* Intuitive access to all the module administration pages
* Self-contained and self-explanatory
* Removes the need for the 'Module administration' node

'''Concerns'''

* Potentially more clicks-to-destination

=== An administration page for the course ===

The same way we would have a 'Preferences' page for the user, the administration page for the course would list everything that was originally in the 'Course administration' node, but reorganised to be more intuitive. A link to that page will be added to the course 'Quick access' menu.

'''Benefits'''

* Intuitive access to all the course administration pages
* Self-contained and self-explanatory
* No more 'Course administration' node

'''Concerns'''

* Potentially more clicks-to-destination
* Reports would be accessible from that page until 'Dedicated solution to access reports' is implemented

=== Dedicated solution to access reports ===

Reports are the black sheep of the navigation, nobody agrees on where they should be and they are moved around every so often. Perhaps nobody agrees because they do not belong either in the navigation or the administration block.

Currently they are accessed from the 'Administration' block, and as we are moving the content of the block to administration pages, that is where they will end up. This is surely not better (perhaps even worse) than where they were before, so why not thinking once and for all where they should be.

<pre>/!\ Solution needed!

Idea: We could add a 'Report' menu to the course 'Quick access' menu</pre>

'''Goals'''

* Standardised way to access reports
* A navigation that does not jump somewhere else when viewing a report

=== Alternative site and course navigation ===

Now, that everything else has been sorted out, we can will be able to remove the navigation block, but first we need to sort out how to navigate at the site and course levels.

'''Site level'''

The frontpage would just be an entry point. The navigation node 'Site pages' will be displayed in a block specific to the site pages. Once you leave the context of the 'Site', you will be in a course. Most users will not go back to the front page, except to find some information specific to their institution. To navigate between their courses, teachers and students would refer to their my/ page.

Alternatively, pages like 'Participants', 'Badges' or 'Tags' could be accessed from their context, for instance in a 'Online users' block which would link to 'All participants'. The same applies for 'Calendar', but is already the case because of the block.

'''Course level'''

The concept of site would disappear as soon as you get in a course. A student or teacher would then focus 100% on the course they are browsing rather than being distracted by site elements.

The course format will be responsible for most of the navigation in the course:

* Injecting a block to navigate between sections
* Injecting a block to navigate between modules
* Injecting a block that does both of the above (very similar to the course node in the navigation block)
* Injecting links 'Go to next activity', 'Go back to course', ... into module views.

The course format will also have control over the course 'Quick access' menu, in which it could inject/remove items if they wanted to.

The node 'Switch role' disappears from the administration block and we now require a 'Switch role' block to be added to the course to unlock that functionality. This block would only be displayed to users having the capabilities to switch role.

'''Future of the Administration block'''

At this point, the administration block will not be displayed to any user, except the ones with elevated privileges. Administrators, managers or course creators will still have access to the administration block but it will only contain the 'Site administration' node.

== Implementation details ==

=== User context ===

All the pages on a user context will all have their own layout where the header includes the name of the user in a standardised way, along with some information and a link to message them, and their preferences if the logged in user has the capabilities to edit them. A renderer will be responsible for creating the header, and will use the user ID found from the context defined on that page.

The navigation within the context pages will be:

; For your own context
: Home > Your Name > Page you are on. Clicking on 'Your Name' will lead you to 'My home'.

[[File:userheader.png|frame|none|alt=The header when viewing your context.|The header when your context.]]

; For other users' context
: Home > Users > User Name > Page you are on. Clicking on 'User Name' will lead you to their profile.

[[File:userheader2.png|frame|none|alt=The header when viewing someone else's context.|The header when viewing someone else's context.]]

==== Rules ====

The user header contains very simplistic information about the user, and a few links to very common actions in regard to other users. For instance it can implement a link to send a message to the user, because you might want to be able to do that regardless of what user context page you are visiting. But, 'Edit profile' should not be in it, because it is only relevant to the profile. It is very important to keep the number of available actions to a minimum, because having too many options would defeat the purpose of the simplicity and efficiency it is trying to achieve.

=== A user menu ===

The new user menu would be a new renderer, called from the layout files as it was the case for the login info renderer. The content of the user menu is fixed and not configurable, however it is possible to override the renderer from a theme to change its layout and content.

==== Design ====

Placed on the top right of the site, the name of the user is displayed next to a user icon. The dropdown is displayed when the user clicks the icon or the name. On smaller screens only a user icon is displayed, and expands to reveal its content. When expanded the name of the user logged in is displayed.

When the user is not logged in, a login link is displayed, regardless of the screen size.

==== My grades ====

The 'My grades' page will display the overall grades of the student in all their visible courses. The ordering can be changed, but the default would be alphabetical.

==== Login as ====

When logged in as someone else, the 'Logout' entry becomes 'Return to Admin User'.

==== Switch role ====

When the user role is switched, the 'Logout' entry becomes 'Return to my normal role'. And the name of the user is appended with the role they switch to, e.g. 'Admin User (teacher)'.

==== Trimming navigation ====

At this stage we could trim the navigation block, but we decide not to remove anything just yet as it would create more confusion: some nodes would accessible from the user menu, and others from the navigation block.

==== Rules ====

For it to be used, the user menu needs to be as short as possible and not being cluttered with additional links. It should contain what has been decided upon above, and not be changed - as users will acclimatise to it, adding and removing nodes should not be looked upon lightly. In any case, it should not contain more than 6 links, and should always contain:

* My home
* My profile
* Preferences
* Logout

These are very important to the user as they target user context-specific pages and nothing related to the site structure or the course. A link to 'My courses' would be redundant as this information should be covered in the 'My home' page.

=== A user preferences page ===

The preferences page is a list of links to sub-preferences page. The page will be generated from the navigation node 'My profile settings', though we will have to re-organise them so that each link belongs to a parent node. A link to the preferences page is added to the user menu.

==== Re-organisation ====

* User account
** Edit profile
** Account settings
** Change password
** Security keys
** Messaging

* Blogs
** Preferences
** External blogs
** Register an external blog

* Badges
** Manage my badges
** Preferences
** Backpack settings

The preferences page displays headings (the setting nodes) under which the links to the sub-pages will be displayed.

[[File:userpreferences.png|frame|none|alt=User preferences page.|User preferences page.]]

The nodes 'Roles' and 'Activity reports' will not be part of this page, because they are context based: they point to the course or site context depending on the page we are on. They will remain in the navigation block, but only when the user has the capability to view them. When the only node in the 'My profile settings' node is 'Preferences', then 'My profile settings' is not displayed. Here is an example when you have the capability to view the reports and roles.

[[File:navblockpref.png|frame|none|alt=My profile settings node with extended capability.|My profile settings node with extended capability.]]

==== Naming ====

The 'My profile settings' node becomes the name of the user: 'Frédéric Massart'. The 'Profile settings for Jetha Chan' becomes 'Jetha Chan'.

==== Breadcrumb ====

Each of the sub-pages should be checked to ensure that they are in the right hierarchy, the breadcrumb always looks like '(User context nav) > Preferences > Preference heading > Page I am on'.

==== Another user's preferences ====

The node 'Profile settings for User B' can be used to edit someone's settings. The content is similar to 'My profile settings', except that the node will always be displayed regardless of the presence of 'Roles' or 'Activity reports'. Currently there is no other way for a user with elevated privileges to access someone's preferences, but sooner or later the preferences will be accessible from their profiles.

[[File:navblocksomeonelse.png|frame|none|alt=Profile settings for X with extended capability.|Profile settings for X node with extended capability.]]

==== Repositories ====

At present, repositories are configurable from the Navigation block - this is a good opportunity to move them to the 'Preferences' page.

==== Rules ====

Every link in this page should belong to a section, the sections are only headers that help the users finding what they are looking for. A plugin that adds user preferences related to its features should define a new heading and add its links to that heading. The heading is never clickable.

=== A new profile page ===

For now we will only be focussing on the site profile of the user. Later on, we will be solving the problems linked to the course context, for instances the links to 'Blog' or 'Forum interactions' automatically filtered to only display the blog posts in the course.

==== Content ====

The contact details will be displayed in such a way that they do not look like a list any more. For instance, everyone knows what an email address is, there is no need to prefix it with 'Email address:'.

The badges will be displayed on the profile too.

==== Links ====

* Edit profile (If this is your profile)
* Blog
* Forum interactions
* Notes (If you have the capability to)
* Preferences (If you have the capability to and are viewing someone's profile)
* Send a message
* Login as (If you have the capability to)

==== Navigation block ====

We can start trimming the node 'My profile' a bit, but some nodes will remain until we sort out the 'My' page. When doing so, it is important to make sure that the nodes 'Home > Some course > Participants > User B' still contain everything it does right now, because those links point to course-based pages, and would not be accessible otherwise.

==== Rules ====

The profile page contains everything about the user that is public. In other words, a content specific to the user should not be displayed on the profile at all, because it would never be accessible to another user, e.g. 'Private files'.

There are exceptions to this rule, badges for example. As a setting allows you to define whether or not your badges are on your profile, you might not be able to see them there, so they should be available on your dashboard.

For content controlled by permissions (and not preferences), they should remain on the profile. Take 'Blog' as an example, an administrator can prevent blog entries from another user to be accessed depending on your role. As the user does not have any information about the roles of the other users, the blog link is displayed on the profile, but other users will not see it. Having a blog block on the 'My home' page would not be useful because it simply duplicates the access points, for no apparent reason to the user.

=== Revisiting 'My home' page ===

We need to add more default blocks to the existing page, the different available blocks will be:

* My courses (already there)
* My private files (already there)
* The calendar
* Upcoming events
* My latest badges

We need to add a link to 'My latest badges' to the page listing all the badges.

==== Navigation block ====

We can now remove 'My profile' (or now called 'Jetha Chan') from the navigation block entirely. But it has to still be accessible under the node of a user in a course tree.

The node 'My courses' is also removed, users should be used to using their dashboard to access their courses.

==== Rules ====

The 'My home' page contains everything about a user that is private and not accessible to other users. For instance, your calendar events or your private files. The list of courses you are enrolled in are an exception, they could be displayed on the user profile, but because they are so important and need to be layed out in useful fashion, they will be part of the 'My home' page.

This page does not need to link to pages which are already accessible from the 'User menu', for instance the profile.

=== Course context ===

<pre>Pending</pre>

* Handling of course profiles
* An administration page per module
* An administration page for the course
* Accessing course grades for students
* Dedicated solution to access reports
* Alternative site and course navigation
** Checking for inconsistencies in the breadcrumb jumping from one place to another.

== Roadmap ==

=== User context ===

# The user menu
# Implementing the user 'header' for user context pages
# The preferences page
# The new profile page
# Revisiting 'My home'

=== Course context ===

<pre>To be defined.</pre>

== Related links ==

* [https://docs.google.com/document/d/16BJsINun13StUFOQaejj3Gawz9jk22ir_r49f3MbInM/edit#heading=h.fuvsbkikzj88 Navigation experiment]
* [https://docs.google.com/document/d/1AXJw8uX6MczA5VC3phkVVv1ee5eZ2nluIiPC2ecgHLE/edit#heading=h.k3lh9alzq3iy Navigation prototyping 2.7]
* MDL-34838: Navigation inconsistencies
* [http://demo2k12.moodlerooms.com Minimal by Moodlerooms]
* [https://moodle.org/mod/forum/discuss.php?d=226791 Users’ personalised profiles]

Navigation overhaul specification

2014-05-30T09:14:39Z

Jethac: /* Re-organisation */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45774
|discussion = -
|assignee = Frédéric Massart, Jetha Chan
}}

{{Work in progress}}

Navigation throughout Moodle is often confusing and needs some improvement. With this in mind, a specification has been prepared, defining what problems were identified and how they will be solved. Particular focus will be placed upon improving the experience of students, teachers, and users unfamiliar to Moodle.

== What can be improved ==

Common complaints leveled at Moodle include:

* '''Unnecessary steep learning curve'''
* '''Features or options not being discovered'''
* '''General frustration''' - clunkiness, a certain ''je ne sais quoi''

=== The navigation is not static ===

Sometimes when navigating from one place to another, the state of the tree in the navigation block completely changes. A good example of this is when going from a course to a module - upon arrival in a module, the Administration block will display a collapsed 'Course administration' node and a new expanded 'Module administration' node, as illustrated below.

[[File:pbnotstatic.png|frame|none|alt=Going from course to a module.|Going from course to a module.]]

Consistency should be improved here, as it is unlikely that a user unfamiliar with the system will understand sudden collapsing of or additional nodes.

=== Feature placement ===

It is our opinion that some navigation nodes contain things that you wouldn't expect, and don't contain things that you '''would'' expect. For example:

* 'My profile settings' contains 'Blogs', 'Badges' or 'Messaging'. These are not strictly related to your profile, they are related to your user account.
* What can be found under 'Site pages'?
* Notes
** In order to view Notes taken on a course level, I first need to click on 'Participants', and once the page is loaded I can see new entries in the navigation node 'Participants'. Why is this the case? Most users will not be aware of those links and will miss out on that feature, we feel.

=== Bad naming ===

Proper naming of the navigation helps the user remembering where to find what they are looking for. It also helps them to discover features that they would not otherwise be aware of, e.g. 'Calendar', hidden under 'Site pages'. If a user has no understanding of what 'Site pages' is, it is unlikely that they will expand it.

Another popular(?) example of bad naming is the link 'My grades' under 'Course administration' in the 'Administration' block. 'A student is not administrating anything, his grades are not a setting.'

=== Context jumps ===

The breadcrumb and navigation sometimes jump from one context to another. For instance, as a student when you click on 'Administration > Course administration > My grades', the navigation node on which you appear to be after clicking is 'Administration > Grade administration > User report'.

[[File:pbcontextjumps.png|frame|none|alt=Breadcrumb context jumping.|Breadcrumb context jumping.]]

It is also possible for the user to jump from a course context to a site context, leaving the course (different breadcrumb, different navigation) without realising it and instantly feeling lost. A common reaction would be to use the 'Back' button of their browser to recover from it rather than trying to understand what happened. This behaviour can be observed when visiting someone's profile, viewing some reports, etc...

[[File:pbcontextjumps2.png|frame|none|alt=Navigation context jumping.|Navigation context jumping.]]

In order for users to feel comfortable and confident, and to not feel lost in Moodle's complex page hierarchy, we need to prevent situations where they feel lost and frustrated.

=== Overwhelming the user ===

Both the navigation block and the administration block can potentially have lots of nodes in them, resulting in what is popularly derided as the "scroll of death". We posit that a good navigation system should be simple and concise, and not necessarily contain the entire site map.

== The goal ==

We seek to provide navigation that is:

* Simpler
* Intuitive
* Easy to learn

Leading to myriad benefits, including but not limited to:

; Efficiency
: Less trial and error when looking for something
; Common expectations being met
: Pages being found where you expect them to be
; A reduction in confusion and general frustration
; Less resistance
: New users feeling more confident using the product

Some risk does present itself; by changing large sections of the product, we risk alienating existing experienced Moodle users, frustrated at not finding pages where they used to be. On the other hand, re-learning the navigation should be straightforward, painless and at the very least easier than learning it the first time. User documentation will also suffer in the interim, as screenshots, navigation patterns and other training materials will have to be updated.

== Rough ideas ==

The following is a list of ideas gathered from discussions and resources both internal and external to HQ:

* A student should be able to quickly access his courses, grades, settings, profile from a static place in the UI. This would remove the need for them to expand nodes in both the 'Navigation' block and the 'Administration' block.
* The different nodes of the 'Administration' block could be displayed on a 'Preferences' page.
** e.g. the 'Course administration' items could be listed on a page, each node being a title and each of its elements listed underneath. By moving administration settings to a single page, we obviate the need for the 'Administration' block entirely.
* A teacher should be able to quickly access the 'Options' of a course through a static node, the same way a user can access anything associated to his account.
* Similarly for modules, an easy dropdown to access module preferences and more frequently used options could be created.
* Breadcrumb-based navigation to reduce and perhaps entirely remove the the need for the nested and cumbersome Navigation block.
** This could be problematic in regards to creating problems with accessing site pages, or pages which do not clearly have a hierarchical position. This could be addressed by providing 'in context' links. For instance, adding a new block entry should be available from the Blog page.
* Providing a sitemap page to counter the lack of 'Navigation' block when something is not easily accessible.
* Ability to 'Star' some pages to quickly access favourites.
* Develop a 'Smart search' to easily access the content in the current course, other courses, etc… and the admin settings for admins.
* Populating my/ page with more useful content for the user itself.
* A new profile page on which is displayed the 'public' information of the user. Their forum interactions, their blog, their reports, ...
* Providing an API to modules to implement their own navigation, thus not required to inject links in the navigation block like 'Chat' is doing or 'Quiz' used to do (Results report). This navigation would be displayed in a standard fashion across modules. (Tabs like in wiki?)
* When hovering a user's name, a menu could appear with a few details and links to their profile, etc... (like Jira does).

== Analysis of popular themes ==

Although most of those themes do not change anything about the navigation itself, a few have implemented a ''user menu''. Usually displayed at the top most right of the screen, it contains links to quickly access user specific pages. The most common links are:

* View profile
* Edit profile
* Logout

Less popular links are:

* Calendar
* My private files
* My home

== The solutions ==

To achieve our goal we have to remove the need for the administration and navigation blocks. This is a long process that needs to be broken down into sub-solutions. Some will need to be developed simultaneously to avoid half-baked temporary solutions. Those solutions can be split into two categories: 'User', and 'Course'.

User solutions:

* A user menu
* A user preferences page
* A new profile page
* Revisiting 'My home' page

Course solutions:

* Handling of course profiles
* A course 'Quick access' menu
* An administration page per module
* An administration page for the course
* Dedicated solution to access reports
* Alternative site and course navigation

=== User menu ===

The user menu is a dropdown containing links to pages specific to user. They are context independent and will always point to the same pages. The user menu can always be found at the same place in the user interface and will contain the following links:

* My home
* My profile
* My grades
* Messages
* Logout

[[File:usermenu.png|frame|none|alt=A user menu.|A user menu.]]

'''Benefits'''

* Gives quick and intuitive access to the user specific pages
* Trimming down 'Navigation > My profile'
* Emphasises the page 'My home'

=== User preferences page ===

A link to that page would be placed in the user menu. That page will contain most of what the user has control over on a site level. Their mailing preferences, changing their password, etc... but reorganised.

[[File:userpreferences.png|frame|none|alt=User preferences page.|User preferences page.]]

'''Benefits'''

* We can remove 'My profile settings' from the 'Administration' block.
* The settings are all reachable from one place.
* New pages will help the user understanding what settings they have control over.

=== A new profile page ===

By adding new content to the profile page, we can trim a bit more the navigation block. The profile page is supposed to contain anything you could find about a user, and there will be links to their blog, forum interactions, notes, to send them a message, etc...

We will keep the distinction between the full profile and the course profiles, at this stage we only improve the site profile because the course profiles need more thoughts and are tied to the course solutions.

'''Benefits'''

* Trimming down 'Navigation > My profile'
* Answering concerns of the 'User preferences page'
* Bonus: the profile page has a reason to be visited

=== Revisiting 'My home' page ===

The My/ page is underused and does not contain enough valuable information for the users to visit it. We will update it to include more user-specific content. It will contain:

* My courses
* My private files
* The calendar and upcoming events
* My latest badges

[[File:myhome.png|frame|none|alt=The new dashboard.|The new dashboard.]]

'''Benefits'''

* Trimming down 'Navigation > My profile', at this point it should be empty
* Making the my/ page more interesting and valuable

=== Handling of course profiles ===

We need to remove the confusion between site and course profiles, only a few more informations should be available when viewing a 'Course profile', but we do not need an entirely different profile for that purpose. The course specific information will be accessible from the user profile, but be in the context of the site profile.

'''Benefits'''

* No more course profile pages

=== A course 'Quick access' menu ===

In order to remove the need for the nodes 'Participants' and 'Badges' from the 'Course' entry in the 'Navigation block', and the 'Grades' entry in the 'Course administration' node (for students), we will implement a new 'Quick access' menu for the course. This menu will be accessible on any page within a course, or module.

This menu will only contain links to the 3 entries mentioned above. If later on we add more links to that list, the additional (and less important) entries will be displayed in a dropdown, or a in a 'More' page.

A new grades page will be created for students to access their course grades.

It is important to keep the visible elements of this menu to a minimum. Not more than 3 elements should be displayed at a time. An exception can be made for users with more privileges who will see a 'Settings' (or 'Administration') link, and perhaps a 'Reports' one when we will work on them (see the following the other solutions below).

To unenrol yourself from a course, you would not look into the 'Course administration' node, you would rather find a link on 'My home' page next to the list of courses to unenrol yourself from them.

[[File:coursemenu.png|frame|none|alt=An example of a course quick-access menu.|An example of a course quick-access menu.]]

'''Benefits'''

* Trimming the navigation block
* Removing the 'Course administration' node for students
* Dedicated grades page for the students
* Quick access to the most important pages of a course

=== An administration page per module ===

The same way we would have a 'Preferences' page for the user, the administration page for the module would list everything that was originally in the 'Module administration' node, but reorganised to be more intuitive. A link to that page would be placed somewhere in the general UI.

The modules abusing the 'Adminstration' block to inject new pages into their module should be updated to provide a module navigation instead. It could be a list of links in the module page, or a module navigation such as tabs, this is probably tied to the solution 'Alternative site and course navigation'.

'''Benefits'''

* Intuitive access to all the module administration pages
* Self-contained and self-explanatory
* Removes the need for the 'Module administration' node

'''Concerns'''

* Potentially more clicks-to-destination

=== An administration page for the course ===

The same way we would have a 'Preferences' page for the user, the administration page for the course would list everything that was originally in the 'Course administration' node, but reorganised to be more intuitive. A link to that page will be added to the course 'Quick access' menu.

'''Benefits'''

* Intuitive access to all the course administration pages
* Self-contained and self-explanatory
* No more 'Course administration' node

'''Concerns'''

* Potentially more clicks-to-destination
* Reports would be accessible from that page until 'Dedicated solution to access reports' is implemented

=== Dedicated solution to access reports ===

Reports are the black sheep of the navigation, nobody agrees on where they should be and they are moved around every so often. Perhaps nobody agrees because they do not belong either in the navigation or the administration block.

Currently they are accessed from the 'Administration' block, and as we are moving the content of the block to administration pages, that is where they will end up. This is surely not better (perhaps even worse) than where they were before, so why not thinking once and for all where they should be.

<pre>/!\ Solution needed!

Idea: We could add a 'Report' menu to the course 'Quick access' menu</pre>

'''Goals'''

* Standardised way to access reports
* A navigation that does not jump somewhere else when viewing a report

=== Alternative site and course navigation ===

Now, that everything else has been sorted out, we can will be able to remove the navigation block, but first we need to sort out how to navigate at the site and course levels.

'''Site level'''

The frontpage would just be an entry point. The navigation node 'Site pages' will be displayed in a block specific to the site pages. Once you leave the context of the 'Site', you will be in a course. Most users will not go back to the front page, except to find some information specific to their institution. To navigate between their courses, teachers and students would refer to their my/ page.

Alternatively, pages like 'Participants', 'Badges' or 'Tags' could be accessed from their context, for instance in a 'Online users' block which would link to 'All participants'. The same applies for 'Calendar', but is already the case because of the block.

'''Course level'''

The concept of site would disappear as soon as you get in a course. A student or teacher would then focus 100% on the course they are browsing rather than being distracted by site elements.

The course format will be responsible for most of the navigation in the course:

* Injecting a block to navigate between sections
* Injecting a block to navigate between modules
* Injecting a block that does both of the above (very similar to the course node in the navigation block)
* Injecting links 'Go to next activity', 'Go back to course', ... into module views.

The course format will also have control over the course 'Quick access' menu, in which it could inject/remove items if they wanted to.

The node 'Switch role' disappears from the administration block and we now require a 'Switch role' block to be added to the course to unlock that functionality. This block would only be displayed to users having the capabilities to switch role.

'''Future of the Administration block'''

At this point, the administration block will not be displayed to any user, except the ones with elevated privileges. Administrators, managers or course creators will still have access to the administration block but it will only contain the 'Site administration' node.

== Implementation details ==

=== User context ===

All the pages on a user context will all have their own layout where the header includes the name of the user in a standardised way, along with some information and a link to message them, and their preferences if the logged in user has the capabilities to edit them. A renderer will be responsible for creating the header, and will use the user ID found from the context defined on that page.

The navigation within the context pages will be:

; For your own context
: Home > Your Name > Page you are on. Clicking on 'Your Name' will lead you to 'My home'.

[[File:userheader.png|frame|none|alt=The header when viewing your context.|The header when your context.]]

; For other users' context
: Home > Users > User Name > Page you are on. Clicking on 'User Name' will lead you to their profile.

[[File:userheader2.png|frame|none|alt=The header when viewing someone else's context.|The header when viewing someone else's context.]]

==== Rules ====

The user header contains very simplistic information about the user, and a few links to very common actions in regard to other users. For instance it can implement a link to send a message to the user, because you might want to be able to do that regardless of what user context page you are visiting. But, 'Edit profile' should not be in it, because it is only relevant to the profile. It is very important to keep the number of available actions to a minimum, because having too many options would defeat the purpose of the simplicity and efficiency it is trying to achieve.

=== A user menu ===

The new user menu would be a new renderer, called from the layout files as it was the case for the login info renderer. The content of the user menu is fixed and not configurable, however it is possible to override the renderer from a theme to change its layout and content.

==== Design ====

Placed on the top right of the site, the name of the user is displayed next to a user icon. The dropdown is displayed when the user clicks the icon or the name. On smaller screens only a user icon is displayed, and expands to reveal its content. When expanded the name of the user logged in is displayed.

When the user is not logged in, a login link is displayed, regardless of the screen size.

==== My grades ====

The 'My grades' page will display the overall grades of the student in all their visible courses. The ordering can be changed, but the default would be alphabetical.

==== Login as ====

When logged in as someone else, the 'Logout' entry becomes 'Return to Admin User'.

==== Switch role ====

When the user role is switched, the 'Logout' entry becomes 'Return to my normal role'. And the name of the user is appended with the role they switch to, e.g. 'Admin User (teacher)'.

==== Trimming navigation ====

At this stage we could trim the navigation block, but we decide not to remove anything just yet as it would create more confusion: some nodes would accessible from the user menu, and others from the navigation block.

==== Rules ====

For it to be used, the user menu needs to be as short as possible and not being cluttered with additional links. It will contain what has been decided above, and not being changed. The users will get used to its content and thus removing nodes is a very tough decision to make. In any case, it should not contain more than 6 links, and should always contain:

* My home
* My profile
* Preferences
* Logout

The links in the menu are very important to the user, they target user context-specific pages and nothing related to the site structure or the course. A link to 'My courses' would be redundant as this information should be covered in the 'My home' page.

=== A user preferences page ===

The preferences page is a list of links to sub-preferences page. The page will be generated from the navigation node 'My profile settings', though we will have to re-organise them so that each link belongs to a parent node. A link to the preferences page is added to the user menu.

==== Re-organisation ====

* User account
** Edit profile
** Account settings
** Change password
** Security keys
** Messaging

* Blogs
** Preferences
** External blogs
** Register an external blog

* Badges
** Manage my badges
** Preferences
** Backpack settings

The preferences page displays headings (the setting nodes) under which the links to the sub-pages will be displayed.

[[File:userpreferences.png|frame|none|alt=User preferences page.|User preferences page.]]

The nodes 'Roles' and 'Activity reports' will not be part of this page, because they are context based: they point to the course or site context depending on the page we are on. They will remain in the navigation block, but only when the user has the capability to view them. When the only node in the 'My profile settings' node is 'Preferences', then 'My profile settings' is not displayed. Here is an example when you have the capability to view the reports and roles.

[[File:navblockpref.png|frame|none|alt=My profile settings node with extended capability.|My profile settings node with extended capability.]]

==== Naming ====

The 'My profile settings' node becomes the name of the user: 'Frédéric Massart'. The 'Profile settings for Jetha Chan' becomes 'Jetha Chan'.

==== Breadcrumb ====

Each of the sub-pages should be checked to ensure that they are in the right hierarchy, the breadcrumb always looks like '(User context nav) > Preferences > Preference heading > Page I am on'.

==== Another user's preferences ====

The node 'Profile settings for User B' can be used to edit someone's settings. The content is similar to 'My profile settings', except that the node will always be displayed regardless of the presence of 'Roles' or 'Activity reports'. Currently there is no other way for a user with elevated privileges to access someone's preferences, but sooner or later the preferences will be accessible from their profiles.

[[File:navblocksomeonelse.png|frame|none|alt=Profile settings for X with extended capability.|Profile settings for X node with extended capability.]]

==== Repositories ====

At present, repositories are configurable from the Navigation block - this is a good opportunity to move them to the 'Preferences' page.

==== Rules ====

Every link in this page should belong to a section, the sections are only headers that help the users finding what they are looking for. A plugin that adds user preferences related to its features should define a new heading and add its links to that heading. The heading is never clickable.

=== A new profile page ===

For now we will only be focussing on the site profile of the user. Later on, we will be solving the problems linked to the course context, for instances the links to 'Blog' or 'Forum interactions' automatically filtered to only display the blog posts in the course.

==== Content ====

The contact details will be displayed in such a way that they do not look like a list any more. For instance, everyone knows what an email address is, there is no need to prefix it with 'Email address:'.

The badges will be displayed on the profile too.

==== Links ====

* Edit profile (If this is your profile)
* Blog
* Forum interactions
* Notes (If you have the capability to)
* Preferences (If you have the capability to and are viewing someone's profile)
* Send a message
* Login as (If you have the capability to)

==== Navigation block ====

We can start trimming the node 'My profile' a bit, but some nodes will remain until we sort out the 'My' page. When doing so, it is important to make sure that the nodes 'Home > Some course > Participants > User B' still contain everything it does right now, because those links point to course-based pages, and would not be accessible otherwise.

==== Rules ====

The profile page contains everything about the user that is public. In other words, a content specific to the user should not be displayed on the profile at all, because it would never be accessible to another user, e.g. 'Private files'.

There are exceptions to this rule, badges for example. As a setting allows you to define whether or not your badges are on your profile, you might not be able to see them there, so they should be available on your dashboard.

For content controlled by permissions (and not preferences), they should remain on the profile. Take 'Blog' as an example, an administrator can prevent blog entries from another user to be accessed depending on your role. As the user does not have any information about the roles of the other users, the blog link is displayed on the profile, but other users will not see it. Having a blog block on the 'My home' page would not be useful because it simply duplicates the access points, for no apparent reason to the user.

=== Revisiting 'My home' page ===

We need to add more default blocks to the existing page, the different available blocks will be:

* My courses (already there)
* My private files (already there)
* The calendar
* Upcoming events
* My latest badges

We need to add a link to 'My latest badges' to the page listing all the badges.

==== Navigation block ====

We can now remove 'My profile' (or now called 'Jetha Chan') from the navigation block entirely. But it has to still be accessible under the node of a user in a course tree.

The node 'My courses' is also removed, users should be used to using their dashboard to access their courses.

==== Rules ====

The 'My home' page contains everything about a user that is private and not accessible to other users. For instance, your calendar events or your private files. The list of courses you are enrolled in are an exception, they could be displayed on the user profile, but because they are so important and need to be layed out in useful fashion, they will be part of the 'My home' page.

This page does not need to link to pages which are already accessible from the 'User menu', for instance the profile.

=== Course context ===

<pre>Pending</pre>

* Handling of course profiles
* An administration page per module
* An administration page for the course
* Accessing course grades for students
* Dedicated solution to access reports
* Alternative site and course navigation
** Checking for inconsistencies in the breadcrumb jumping from one place to another.

== Roadmap ==

=== User context ===

# The user menu
# Implementing the user 'header' for user context pages
# The preferences page
# The new profile page
# Revisiting 'My home'

=== Course context ===

<pre>To be defined.</pre>

== Related links ==

* [https://docs.google.com/document/d/16BJsINun13StUFOQaejj3Gawz9jk22ir_r49f3MbInM/edit#heading=h.fuvsbkikzj88 Navigation experiment]
* [https://docs.google.com/document/d/1AXJw8uX6MczA5VC3phkVVv1ee5eZ2nluIiPC2ecgHLE/edit#heading=h.k3lh9alzq3iy Navigation prototyping 2.7]
* MDL-34838: Navigation inconsistencies
* [http://demo2k12.moodlerooms.com Minimal by Moodlerooms]
* [https://moodle.org/mod/forum/discuss.php?d=226791 Users’ personalised profiles]

Navigation overhaul specification

2014-05-30T08:49:12Z

Jethac: /* Repositories */

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45774
|discussion = -
|assignee = Frédéric Massart, Jetha Chan
}}

{{Work in progress}}

Navigation throughout Moodle is often confusing and needs some improvement. With this in mind, a specification has been prepared, defining what problems were identified and how they will be solved. Particular focus will be placed upon improving the experience of students, teachers, and users unfamiliar to Moodle.

== What can be improved ==

Common complaints leveled at Moodle include:

* '''Unnecessary steep learning curve'''
* '''Features or options not being discovered'''
* '''General frustration''' - clunkiness, a certain ''je ne sais quoi''

=== The navigation is not static ===

Sometimes when navigating from one place to another, the state of the tree in the navigation block completely changes. A good example of this is when going from a course to a module - upon arrival in a module, the Administration block will display a collapsed 'Course administration' node and a new expanded 'Module administration' node, as illustrated below.

[[File:pbnotstatic.png|frame|none|alt=Going from course to a module.|Going from course to a module.]]

Consistency should be improved here, as it is unlikely that a user unfamiliar with the system will understand sudden collapsing of or additional nodes.

=== Feature placement ===

It is our opinion that some navigation nodes contain things that you wouldn't expect, and don't contain things that you '''would'' expect. For example:

* 'My profile settings' contains 'Blogs', 'Badges' or 'Messaging'. These are not strictly related to your profile, they are related to your user account.
* What can be found under 'Site pages'?
* Notes
** In order to view Notes taken on a course level, I first need to click on 'Participants', and once the page is loaded I can see new entries in the navigation node 'Participants'. Why is this the case? Most users will not be aware of those links and will miss out on that feature, we feel.

=== Bad naming ===

Proper naming of the navigation helps the user remembering where to find what they are looking for. It also helps them to discover features that they would not otherwise be aware of, e.g. 'Calendar', hidden under 'Site pages'. If a user has no understanding of what 'Site pages' is, it is unlikely that they will expand it.

Another popular(?) example of bad naming is the link 'My grades' under 'Course administration' in the 'Administration' block. 'A student is not administrating anything, his grades are not a setting.'

=== Context jumps ===

The breadcrumb and navigation sometimes jump from one context to another. For instance, as a student when you click on 'Administration > Course administration > My grades', the navigation node on which you appear to be after clicking is 'Administration > Grade administration > User report'.

[[File:pbcontextjumps.png|frame|none|alt=Breadcrumb context jumping.|Breadcrumb context jumping.]]

It is also possible for the user to jump from a course context to a site context, leaving the course (different breadcrumb, different navigation) without realising it and instantly feeling lost. A common reaction would be to use the 'Back' button of their browser to recover from it rather than trying to understand what happened. This behaviour can be observed when visiting someone's profile, viewing some reports, etc...

[[File:pbcontextjumps2.png|frame|none|alt=Navigation context jumping.|Navigation context jumping.]]

In order for users to feel comfortable and confident, and to not feel lost in Moodle's complex page hierarchy, we need to prevent situations where they feel lost and frustrated.

=== Overwhelming the user ===

Both the navigation block and the administration block can potentially have lots of nodes in them, resulting in what is popularly derided as the "scroll of death". We posit that a good navigation system should be simple and concise, and not necessarily contain the entire site map.

== The goal ==

We seek to provide navigation that is:

* Simpler
* Intuitive
* Easy to learn

Leading to myriad benefits, including but not limited to:

; Efficiency
: Less trial and error when looking for something
; Common expectations being met
: Pages being found where you expect them to be
; A reduction in confusion and general frustration
; Less resistance
: New users feeling more confident using the product

Some risk does present itself; by changing large sections of the product, we risk alienating existing experienced Moodle users, frustrated at not finding pages where they used to be. On the other hand, re-learning the navigation should be straightforward, painless and at the very least easier than learning it the first time. User documentation will also suffer in the interim, as screenshots, navigation patterns and other training materials will have to be updated.

== Rough ideas ==

The following is a list of ideas gathered from discussions and resources both internal and external to HQ:

* A student should be able to quickly access his courses, grades, settings, profile from a static place in the UI. This would remove the need for them to expand nodes in both the 'Navigation' block and the 'Administration' block.
* The different nodes of the 'Administration' block could be displayed on a 'Preferences' page.
** e.g. the 'Course administration' items could be listed on a page, each node being a title and each of its elements listed underneath. By moving administration settings to a single page, we obviate the need for the 'Administration' block entirely.
* A teacher should be able to quickly access the 'Options' of a course through a static node, the same way a user can access anything associated to his account.
* Similarly for modules, an easy dropdown to access module preferences and more frequently used options could be created.
* Breadcrumb-based navigation to reduce and perhaps entirely remove the the need for the nested and cumbersome Navigation block.
** This could be problematic in regards to creating problems with accessing site pages, or pages which do not clearly have a hierarchical position. This could be addressed by providing 'in context' links. For instance, adding a new block entry should be available from the Blog page.
* Providing a sitemap page to counter the lack of 'Navigation' block when something is not easily accessible.
* Ability to 'Star' some pages to quickly access favourites.
* Develop a 'Smart search' to easily access the content in the current course, other courses, etc… and the admin settings for admins.
* Populating my/ page with more useful content for the user itself.
* A new profile page on which is displayed the 'public' information of the user. Their forum interactions, their blog, their reports, ...
* Providing an API to modules to implement their own navigation, thus not required to inject links in the navigation block like 'Chat' is doing or 'Quiz' used to do (Results report). This navigation would be displayed in a standard fashion across modules. (Tabs like in wiki?)
* When hovering a user's name, a menu could appear with a few details and links to their profile, etc... (like Jira does).

== Analysis of popular themes ==

Although most of those themes do not change anything about the navigation itself, a few have implemented a ''user menu''. Usually displayed at the top most right of the screen, it contains links to quickly access user specific pages. The most common links are:

* View profile
* Edit profile
* Logout

Less popular links are:

* Calendar
* My private files
* My home

== The solutions ==

To achieve our goal we have to remove the need for the administration and navigation blocks. This is a long process that needs to be broken down into sub-solutions. Some will need to be developed simultaneously to avoid half-baked temporary solutions. Those solutions can be split into two categories: 'User', and 'Course'.

User solutions:

* A user menu
* A user preferences page
* A new profile page
* Revisiting 'My home' page

Course solutions:

* Handling of course profiles
* A course 'Quick access' menu
* An administration page per module
* An administration page for the course
* Dedicated solution to access reports
* Alternative site and course navigation

=== User menu ===

The user menu is a dropdown containing links to pages specific to user. They are context independent and will always point to the same pages. The user menu can always be found at the same place in the user interface and will contain the following links:

* My home
* My profile
* My grades
* Messages
* Logout

[[File:usermenu.png|frame|none|alt=A user menu.|A user menu.]]

'''Benefits'''

* Gives quick and intuitive access to the user specific pages
* Trimming down 'Navigation > My profile'
* Emphasises the page 'My home'

=== User preferences page ===

A link to that page would be placed in the user menu. That page will contain most of what the user has control over on a site level. Their mailing preferences, changing their password, etc... but reorganised.

[[File:userpreferences.png|frame|none|alt=User preferences page.|User preferences page.]]

'''Benefits'''

* We can remove 'My profile settings' from the 'Administration' block.
* The settings are all reachable from one place.
* New pages will help the user understanding what settings they have control over.

=== A new profile page ===

By adding new content to the profile page, we can trim a bit more the navigation block. The profile page is supposed to contain anything you could find about a user, and there will be links to their blog, forum interactions, notes, to send them a message, etc...

We will keep the distinction between the full profile and the course profiles, at this stage we only improve the site profile because the course profiles need more thoughts and are tied to the course solutions.

'''Benefits'''

* Trimming down 'Navigation > My profile'
* Answering concerns of the 'User preferences page'
* Bonus: the profile page has a reason to be visited

=== Revisiting 'My home' page ===

The My/ page is underused and does not contain enough valuable information for the users to visit it. We will update it to include more user-specific content. It will contain:

* My courses
* My private files
* The calendar and upcoming events
* My latest badges

[[File:myhome.png|frame|none|alt=The new dashboard.|The new dashboard.]]

'''Benefits'''

* Trimming down 'Navigation > My profile', at this point it should be empty
* Making the my/ page more interesting and valuable

=== Handling of course profiles ===

We need to remove the confusion between site and course profiles, only a few more informations should be available when viewing a 'Course profile', but we do not need an entirely different profile for that purpose. The course specific information will be accessible from the user profile, but be in the context of the site profile.

'''Benefits'''

* No more course profile pages

=== A course 'Quick access' menu ===

In order to remove the need for the nodes 'Participants' and 'Badges' from the 'Course' entry in the 'Navigation block', and the 'Grades' entry in the 'Course administration' node (for students), we will implement a new 'Quick access' menu for the course. This menu will be accessible on any page within a course, or module.

This menu will only contain links to the 3 entries mentioned above. If later on we add more links to that list, the additional (and less important) entries will be displayed in a dropdown, or a in a 'More' page.

A new grades page will be created for students to access their course grades.

It is important to keep the visible elements of this menu to a minimum. Not more than 3 elements should be displayed at a time. An exception can be made for users with more privileges who will see a 'Settings' (or 'Administration') link, and perhaps a 'Reports' one when we will work on them (see the following the other solutions below).

To unenrol yourself from a course, you would not look into the 'Course administration' node, you would rather find a link on 'My home' page next to the list of courses to unenrol yourself from them.

[[File:coursemenu.png|frame|none|alt=An example of a course quick-access menu.|An example of a course quick-access menu.]]

'''Benefits'''

* Trimming the navigation block
* Removing the 'Course administration' node for students
* Dedicated grades page for the students
* Quick access to the most important pages of a course

=== An administration page per module ===

The same way we would have a 'Preferences' page for the user, the administration page for the module would list everything that was originally in the 'Module administration' node, but reorganised to be more intuitive. A link to that page would be placed somewhere in the general UI.

The modules abusing the 'Adminstration' block to inject new pages into their module should be updated to provide a module navigation instead. It could be a list of links in the module page, or a module navigation such as tabs, this is probably tied to the solution 'Alternative site and course navigation'.

'''Benefits'''

* Intuitive access to all the module administration pages
* Self-contained and self-explanatory
* Removes the need for the 'Module administration' node

'''Concerns'''

* Potentially more clicks-to-destination

=== An administration page for the course ===

The same way we would have a 'Preferences' page for the user, the administration page for the course would list everything that was originally in the 'Course administration' node, but reorganised to be more intuitive. A link to that page will be added to the course 'Quick access' menu.

'''Benefits'''

* Intuitive access to all the course administration pages
* Self-contained and self-explanatory
* No more 'Course administration' node

'''Concerns'''

* Potentially more clicks-to-destination
* Reports would be accessible from that page until 'Dedicated solution to access reports' is implemented

=== Dedicated solution to access reports ===

Reports are the black sheep of the navigation, nobody agrees on where they should be and they are moved around every so often. Perhaps nobody agrees because they do not belong either in the navigation or the administration block.

Currently they are accessed from the 'Administration' block, and as we are moving the content of the block to administration pages, that is where they will end up. This is surely not better (perhaps even worse) than where they were before, so why not thinking once and for all where they should be.

<pre>/!\ Solution needed!

Idea: We could add a 'Report' menu to the course 'Quick access' menu</pre>

'''Goals'''

* Standardised way to access reports
* A navigation that does not jump somewhere else when viewing a report

=== Alternative site and course navigation ===

Now, that everything else has been sorted out, we can will be able to remove the navigation block, but first we need to sort out how to navigate at the site and course levels.

'''Site level'''

The frontpage would just be an entry point. The navigation node 'Site pages' will be displayed in a block specific to the site pages. Once you leave the context of the 'Site', you will be in a course. Most users will not go back to the front page, except to find some information specific to their institution. To navigate between their courses, teachers and students would refer to their my/ page.

Alternatively, pages like 'Participants', 'Badges' or 'Tags' could be accessed from their context, for instance in a 'Online users' block which would link to 'All participants'. The same applies for 'Calendar', but is already the case because of the block.

'''Course level'''

The concept of site would disappear as soon as you get in a course. A student or teacher would then focus 100% on the course they are browsing rather than being distracted by site elements.

The course format will be responsible for most of the navigation in the course:

* Injecting a block to navigate between sections
* Injecting a block to navigate between modules
* Injecting a block that does both of the above (very similar to the course node in the navigation block)
* Injecting links 'Go to next activity', 'Go back to course', ... into module views.

The course format will also have control over the course 'Quick access' menu, in which it could inject/remove items if they wanted to.

The node 'Switch role' disappears from the administration block and we now require a 'Switch role' block to be added to the course to unlock that functionality. This block would only be displayed to users having the capabilities to switch role.

'''Future of the Administration block'''

At this point, the administration block will not be displayed to any user, except the ones with elevated privileges. Administrators, managers or course creators will still have access to the administration block but it will only contain the 'Site administration' node.

== Implementation details ==

=== User context ===

All the pages on a user context will all have their own layout where the header includes the name of the user in a standardised way, along with some information and a link to message them, and their preferences if the logged in user has the capabilities to edit them. A renderer will be responsible for creating the header, and will use the user ID found from the context defined on that page.

The navigation within the context pages will be:

; For your own context
: Home > Your Name > Page you are on. Clicking on 'Your Name' will lead you to 'My home'.

[[File:userheader.png|frame|none|alt=The header when viewing your context.|The header when your context.]]

; For other users' context
: Home > Users > User Name > Page you are on. Clicking on 'User Name' will lead you to their profile.

[[File:userheader2.png|frame|none|alt=The header when viewing someone else's context.|The header when viewing someone else's context.]]

==== Rules ====

The user header contains very simplistic information about the user, and a few links to very common actions in regard to other users. For instance it can implement a link to send a message to the user, because you might want to be able to do that regardless of what user context page you are visiting. But, 'Edit profile' should not be in it, because it is only relevant to the profile. It is very important to keep the number of available actions to a minimum, because having too many options would defeat the purpose of the simplicity and efficiency it is trying to achieve.

=== A user menu ===

The new user menu would be a new renderer, called from the layout files as it was the case for the login info renderer. The content of the user menu is fixed and not configurable, however it is possible to override the renderer from a theme to change its layout and content.

==== Design ====

Placed on the top right of the site, the name of the user is displayed next to a user icon. The dropdown is displayed when the user clicks the icon or the name. On smaller screens only a user icon is displayed, and expands to reveal its content. When expanded the name of the user logged in is displayed.

When the user is not logged in, a login link is displayed, regardless of the screen size.

==== My grades ====

The 'My grades' page will display the overall grades of the student in all their visible courses. The ordering can be changed, but the default would be alphabetical.

==== Login as ====

When logged in as someone else, the 'Logout' entry becomes 'Return to Admin User'.

==== Switch role ====

When the user role is switched, the 'Logout' entry becomes 'Return to my normal role'. And the name of the user is appended with the role they switch to, e.g. 'Admin User (teacher)'.

==== Trimming navigation ====

At this stage we could trim the navigation block, but we decide not to remove anything just yet as it would create more confusion: some nodes would accessible from the user menu, and others from the navigation block.

==== Rules ====

For it to be used, the user menu needs to be as short as possible and not being cluttered with additional links. It will contain what has been decided above, and not being changed. The users will get used to its content and thus removing nodes is a very tough decision to make. In any case, it should not contain more than 6 links, and should always contain:

* My home
* My profile
* Preferences
* Logout

The links in the menu are very important to the user, they target user context-specific pages and nothing related to the site structure or the course. A link to 'My courses' would be redundant as this information should be covered in the 'My home' page.

=== A user preferences page ===

The preferences page is a list of links to sub-preferences page. The page will be generated from the navigation node 'My profile settings', though we will have to re-organise them so that each link belongs to a parent node. A link to the preferences page is added to the user menu.

==== Re-organisation ====

* User account
** Edit profile
** Account settings
** Change password
** Security keys
** Messaging

* Blogs
** Preferences
** External blogs
** Register an external blog

* Badges
** Manage my badges
** Preferences
** Backpack settings

The preferences page displays headings (the setting nodes) under which the links to the sub-pages will be displayed.

[[File:userpreferences.png|frame|none|alt=User preferences page.|User preferences page.]

The nodes 'Roles' and 'Activity reports' will not be part of this page, because they are context based: they point to the course or site context depending on the page we are on. They will remain in the navigation block, but only when the user has the capability to view them. When the only node in the 'My profile settings' node is 'Preferences', then 'My profile settings' is not displayed. Here is an example when you have the capability to view the reports and roles.

[[File:navblockpref.png|frame|none|alt=My profile settings node with extended capability.|My profile settings node with extended capability.]

==== Naming ====

The 'My profile settings' node becomes the name of the user: 'Frédéric Massart'. The 'Profile settings for Jetha Chan' becomes 'Jetha Chan'.

==== Breadcrumb ====

Each of the sub-pages should be checked to ensure that they are in the right hierarchy, the breadcrumb always looks like '(User context nav) > Preferences > Preference heading > Page I am on'.

==== Another user's preferences ====

The node 'Profile settings for User B' can be used to edit someone's settings. The content is similar to 'My profile settings', except that the node will always be displayed regardless of the presence of 'Roles' or 'Activity reports'. Currently there is no other way for a user with elevated privileges to access someone's preferences, but sooner or later the preferences will be accessible from their profiles.

[[File:navblocksomeonelse.png|frame|none|alt=Profile settings for X with extended capability.|Profile settings for X node with extended capability.]]

==== Repositories ====

At present, repositories are configurable from the Navigation block - this is a good opportunity to move them to the 'Preferences' page.

==== Rules ====

Every link in this page should belong to a section, the sections are only headers that help the users finding what they are looking for. A plugin that adds user preferences related to its features should define a new heading and add its links to that heading. The heading is never clickable.

=== A new profile page ===

For now we will only be focussing on the site profile of the user. Later on, we will be solving the problems linked to the course context, for instances the links to 'Blog' or 'Forum interactions' automatically filtered to only display the blog posts in the course.

==== Content ====

The contact details will be displayed in such a way that they do not look like a list any more. For instance, everyone knows what an email address is, there is no need to prefix it with 'Email address:'.

The badges will be displayed on the profile too.

==== Links ====

* Edit profile (If this is your profile)
* Blog
* Forum interactions
* Notes (If you have the capability to)
* Preferences (If you have the capability to and are viewing someone's profile)
* Send a message
* Login as (If you have the capability to)

==== Navigation block ====

We can start trimming the node 'My profile' a bit, but some nodes will remain until we sort out the 'My' page. When doing so, it is important to make sure that the nodes 'Home > Some course > Participants > User B' still contain everything it does right now, because those links point to course-based pages, and would not be accessible otherwise.

==== Rules ====

The profile page contains everything about the user that is public. In other words, a content specific to the user should not be displayed on the profile at all, because it would never be accessible to another user, e.g. 'Private files'.

There are exceptions to this rule, badges for example. As a setting allows you to define whether or not your badges are on your profile, you might not be able to see them there, so they should be available on your dashboard.

For content controlled by permissions (and not preferences), they should remain on the profile. Take 'Blog' as an example, an administrator can prevent blog entries from another user to be accessed depending on your role. As the user does not have any information about the roles of the other users, the blog link is displayed on the profile, but other users will not see it. Having a blog block on the 'My home' page would not be useful because it simply duplicates the access points, for no apparent reason to the user.

=== Revisiting 'My home' page ===

We need to add more default blocks to the existing page, the different available blocks will be:

* My courses (already there)
* My private files (already there)
* The calendar
* Upcoming events
* My latest badges

We need to add a link to 'My latest badges' to the page listing all the badges.

==== Navigation block ====

We can now remove 'My profile' (or now called 'Jetha Chan') from the navigation block entirely. But it has to still be accessible under the node of a user in a course tree.

The node 'My courses' is also removed, users should be used to using their dashboard to access their courses.

==== Rules ====

The 'My home' page contains everything about a user that is private and not accessible to other users. For instance, your calendar events or your private files. The list of courses you are enrolled in are an exception, they could be displayed on the user profile, but because they are so important and need to be layed out in useful fashion, they will be part of the 'My home' page.

This page does not need to link to pages which are already accessible from the 'User menu', for instance the profile.

=== Course context ===

<pre>Pending</pre>

* Handling of course profiles
* An administration page per module
* An administration page for the course
* Accessing course grades for students
* Dedicated solution to access reports
* Alternative site and course navigation
** Checking for inconsistencies in the breadcrumb jumping from one place to another.

== Roadmap ==

=== User context ===

# The user menu
# Implementing the user 'header' for user context pages
# The preferences page
# The new profile page
# Revisiting 'My home'

=== Course context ===

<pre>To be defined.</pre>

== Related links ==

* [https://docs.google.com/document/d/16BJsINun13StUFOQaejj3Gawz9jk22ir_r49f3MbInM/edit#heading=h.fuvsbkikzj88 Navigation experiment]
* [https://docs.google.com/document/d/1AXJw8uX6MczA5VC3phkVVv1ee5eZ2nluIiPC2ecgHLE/edit#heading=h.k3lh9alzq3iy Navigation prototyping 2.7]
* MDL-34838: Navigation inconsistencies
* [http://demo2k12.moodlerooms.com Minimal by Moodlerooms]
* [https://moodle.org/mod/forum/discuss.php?d=226791 Users’ personalised profiles]

Navigation overhaul specification

2014-05-30T08:44:38Z

Jethac:

{{Infobox Project
|name = Renderer consistency
|state = Specification
|tracker = https://tracker.moodle.org/browse/MDL-45774
|discussion = -
|assignee = Frédéric Massart, Jetha Chan
}}

{{Work in progress}}

Navigation throughout Moodle is often confusing and needs some improvement. With this in mind, a specification has been prepared, defining what problems were identified and how they will be solved. Particular focus will be placed upon improving the experience of students, teachers, and users unfamiliar to Moodle.

== What can be improved ==

Common complaints leveled at Moodle include:

* '''Unnecessary steep learning curve'''
* '''Features or options not being discovered'''
* '''General frustration''' - clunkiness, a certain ''je ne sais quoi''

=== The navigation is not static ===

Sometimes when navigating from one place to another, the state of the tree in the navigation block completely changes. A good example of this is when going from a course to a module - upon arrival in a module, the Administration block will display a collapsed 'Course administration' node and a new expanded 'Module administration' node, as illustrated below.

[[File:pbnotstatic.png|frame|none|alt=Going from course to a module.|Going from course to a module.]]

Consistency should be improved here, as it is unlikely that a user unfamiliar with the system will understand sudden collapsing of or additional nodes.

=== Feature placement ===

It is our opinion that some navigation nodes contain things that you wouldn't expect, and don't contain things that you '''would'' expect. For example:

* 'My profile settings' contains 'Blogs', 'Badges' or 'Messaging'. These are not strictly related to your profile, they are related to your user account.
* What can be found under 'Site pages'?
* Notes
** In order to view Notes taken on a course level, I first need to click on 'Participants', and once the page is loaded I can see new entries in the navigation node 'Participants'. Why is this the case? Most users will not be aware of those links and will miss out on that feature, we feel.

=== Bad naming ===

Proper naming of the navigation helps the user remembering where to find what they are looking for. It also helps them to discover features that they would not otherwise be aware of, e.g. 'Calendar', hidden under 'Site pages'. If a user has no understanding of what 'Site pages' is, it is unlikely that they will expand it.

Another popular(?) example of bad naming is the link 'My grades' under 'Course administration' in the 'Administration' block. 'A student is not administrating anything, his grades are not a setting.'

=== Context jumps ===

The breadcrumb and navigation sometimes jump from one context to another. For instance, as a student when you click on 'Administration > Course administration > My grades', the navigation node on which you appear to be after clicking is 'Administration > Grade administration > User report'.

[[File:pbcontextjumps.png|frame|none|alt=Breadcrumb context jumping.|Breadcrumb context jumping.]]

It is also possible for the user to jump from a course context to a site context, leaving the course (different breadcrumb, different navigation) without realising it and instantly feeling lost. A common reaction would be to use the 'Back' button of their browser to recover from it rather than trying to understand what happened. This behaviour can be observed when visiting someone's profile, viewing some reports, etc...

[[File:pbcontextjumps2.png|frame|none|alt=Navigation context jumping.|Navigation context jumping.]]

In order for users to feel comfortable and confident, and to not feel lost in Moodle's complex page hierarchy, we need to prevent situations where they feel lost and frustrated.

=== Overwhelming the user ===

Both the navigation block and the administration block can potentially have lots of nodes in them, resulting in what is popularly derided as the "scroll of death". We posit that a good navigation system should be simple and concise, and not necessarily contain the entire site map.

== The goal ==

We seek to provide navigation that is:

* Simpler
* Intuitive
* Easy to learn

Leading to myriad benefits, including but not limited to:

; Efficiency
: Less trial and error when looking for something
; Common expectations being met
: Pages being found where you expect them to be
; A reduction in confusion and general frustration
; Less resistance
: New users feeling more confident using the product

Some risk does present itself; by changing large sections of the product, we risk alienating existing experienced Moodle users, frustrated at not finding pages where they used to be. On the other hand, re-learning the navigation should be straightforward, painless and at the very least easier than learning it the first time. User documentation will also suffer in the interim, as screenshots, navigation patterns and other training materials will have to be updated.

== Rough ideas ==

The following is a list of ideas gathered from discussions and resources both internal and external to HQ:

* A student should be able to quickly access his courses, grades, settings, profile from a static place in the UI. This would remove the need for them to expand nodes in both the 'Navigation' block and the 'Administration' block.
* The different nodes of the 'Administration' block could be displayed on a 'Preferences' page.
** e.g. the 'Course administration' items could be listed on a page, each node being a title and each of its elements listed underneath. By moving administration settings to a single page, we obviate the need for the 'Administration' block entirely.
* A teacher should be able to quickly access the 'Options' of a course through a static node, the same way a user can access anything associated to his account.
* Similarly for modules, an easy dropdown to access module preferences and more frequently used options could be created.
* Breadcrumb-based navigation to reduce and perhaps entirely remove the the need for the nested and cumbersome Navigation block.
** This could be problematic in regards to creating problems with accessing site pages, or pages which do not clearly have a hierarchical position. This could be addressed by providing 'in context' links. For instance, adding a new block entry should be available from the Blog page.
* Providing a sitemap page to counter the lack of 'Navigation' block when something is not easily accessible.
* Ability to 'Star' some pages to quickly access favourites.
* Develop a 'Smart search' to easily access the content in the current course, other courses, etc… and the admin settings for admins.
* Populating my/ page with more useful content for the user itself.
* A new profile page on which is displayed the 'public' information of the user. Their forum interactions, their blog, their reports, ...
* Providing an API to modules to implement their own navigation, thus not required to inject links in the navigation block like 'Chat' is doing or 'Quiz' used to do (Results report). This navigation would be displayed in a standard fashion across modules. (Tabs like in wiki?)
* When hovering a user's name, a menu could appear with a few details and links to their profile, etc... (like Jira does).

== Analysis of popular themes ==

Although most of those themes do not change anything about the navigation itself, a few have implemented a ''user menu''. Usually displayed at the top most right of the screen, it contains links to quickly access user specific pages. The most common links are:

* View profile
* Edit profile
* Logout

Less popular links are:

* Calendar
* My private files
* My home

== The solutions ==

To achieve our goal we have to remove the need for the administration and navigation blocks. This is a long process that needs to be broken down into sub-solutions. Some will need to be developed simultaneously to avoid half-baked temporary solutions. Those solutions can be split into two categories: 'User', and 'Course'.

User solutions:

* A user menu
* A user preferences page
* A new profile page
* Revisiting 'My home' page

Course solutions:

* Handling of course profiles
* A course 'Quick access' menu
* An administration page per module
* An administration page for the course
* Dedicated solution to access reports
* Alternative site and course navigation

=== User menu ===

The user menu is a dropdown containing links to pages specific to user. They are context independent and will always point to the same pages. The user menu can always be found at the same place in the user interface and will contain the following links:

* My home
* My profile
* My grades
* Messages
* Logout

[[File:usermenu.png|frame|none|alt=A user menu.|A user menu.]]

'''Benefits'''

* Gives quick and intuitive access to the user specific pages
* Trimming down 'Navigation > My profile'
* Emphasises the page 'My home'

=== User preferences page ===

A link to that page would be placed in the user menu. That page will contain most of what the user has control over on a site level. Their mailing preferences, changing their password, etc... but reorganised.

[[File:userpreferences.png|frame|none|alt=User preferences page.|User preferences page.]]

'''Benefits'''

* We can remove 'My profile settings' from the 'Administration' block.
* The settings are all reachable from one place.
* New pages will help the user understanding what settings they have control over.

=== A new profile page ===

By adding new content to the profile page, we can trim a bit more the navigation block. The profile page is supposed to contain anything you could find about a user, and there will be links to their blog, forum interactions, notes, to send them a message, etc...

We will keep the distinction between the full profile and the course profiles, at this stage we only improve the site profile because the course profiles need more thoughts and are tied to the course solutions.

'''Benefits'''

* Trimming down 'Navigation > My profile'
* Answering concerns of the 'User preferences page'
* Bonus: the profile page has a reason to be visited

=== Revisiting 'My home' page ===

The My/ page is underused and does not contain enough valuable information for the users to visit it. We will update it to include more user-specific content. It will contain:

* My courses
* My private files
* The calendar and upcoming events
* My latest badges

[[File:myhome.png|frame|none|alt=The new dashboard.|The new dashboard.]]

'''Benefits'''

* Trimming down 'Navigation > My profile', at this point it should be empty
* Making the my/ page more interesting and valuable

=== Handling of course profiles ===

We need to remove the confusion between site and course profiles, only a few more informations should be available when viewing a 'Course profile', but we do not need an entirely different profile for that purpose. The course specific information will be accessible from the user profile, but be in the context of the site profile.

'''Benefits'''

* No more course profile pages

=== A course 'Quick access' menu ===

In order to remove the need for the nodes 'Participants' and 'Badges' from the 'Course' entry in the 'Navigation block', and the 'Grades' entry in the 'Course administration' node (for students), we will implement a new 'Quick access' menu for the course. This menu will be accessible on any page within a course, or module.

This menu will only contain links to the 3 entries mentioned above. If later on we add more links to that list, the additional (and less important) entries will be displayed in a dropdown, or a in a 'More' page.

A new grades page will be created for students to access their course grades.

It is important to keep the visible elements of this menu to a minimum. Not more than 3 elements should be displayed at a time. An exception can be made for users with more privileges who will see a 'Settings' (or 'Administration') link, and perhaps a 'Reports' one when we will work on them (see the following the other solutions below).

To unenrol yourself from a course, you would not look into the 'Course administration' node, you would rather find a link on 'My home' page next to the list of courses to unenrol yourself from them.

[[File:coursemenu.png|frame|none|alt=An example of a course quick-access menu.|An example of a course quick-access menu.]]

'''Benefits'''

* Trimming the navigation block
* Removing the 'Course administration' node for students
* Dedicated grades page for the students
* Quick access to the most important pages of a course

=== An administration page per module ===

The same way we would have a 'Preferences' page for the user, the administration page for the module would list everything that was originally in the 'Module administration' node, but reorganised to be more intuitive. A link to that page would be placed somewhere in the general UI.

The modules abusing the 'Adminstration' block to inject new pages into their module should be updated to provide a module navigation instead. It could be a list of links in the module page, or a module navigation such as tabs, this is probably tied to the solution 'Alternative site and course navigation'.

'''Benefits'''

* Intuitive access to all the module administration pages
* Self-contained and self-explanatory
* Removes the need for the 'Module administration' node

'''Concerns'''

* Potentially more clicks-to-destination

=== An administration page for the course ===

The same way we would have a 'Preferences' page for the user, the administration page for the course would list everything that was originally in the 'Course administration' node, but reorganised to be more intuitive. A link to that page will be added to the course 'Quick access' menu.

'''Benefits'''

* Intuitive access to all the course administration pages
* Self-contained and self-explanatory
* No more 'Course administration' node

'''Concerns'''

* Potentially more clicks-to-destination
* Reports would be accessible from that page until 'Dedicated solution to access reports' is implemented

=== Dedicated solution to access reports ===

Reports are the black sheep of the navigation, nobody agrees on where they should be and they are moved around every so often. Perhaps nobody agrees because they do not belong either in the navigation or the administration block.

Currently they are accessed from the 'Administration' block, and as we are moving the content of the block to administration pages, that is where they will end up. This is surely not better (perhaps even worse) than where they were before, so why not thinking once and for all where they should be.

<pre>/!\ Solution needed!

Idea: We could add a 'Report' menu to the course 'Quick access' menu</pre>

'''Goals'''

* Standardised way to access reports
* A navigation that does not jump somewhere else when viewing a report

=== Alternative site and course navigation ===

Now, that everything else has been sorted out, we can will be able to remove the navigation block, but first we need to sort out how to navigate at the site and course levels.

'''Site level'''

The frontpage would just be an entry point. The navigation node 'Site pages' will be displayed in a block specific to the site pages. Once you leave the context of the 'Site', you will be in a course. Most users will not go back to the front page, except to find some information specific to their institution. To navigate between their courses, teachers and students would refer to their my/ page.

Alternatively, pages like 'Participants', 'Badges' or 'Tags' could be accessed from their context, for instance in a 'Online users' block which would link to 'All participants'. The same applies for 'Calendar', but is already the case because of the block.

'''Course level'''

The concept of site would disappear as soon as you get in a course. A student or teacher would then focus 100% on the course they are browsing rather than being distracted by site elements.

The course format will be responsible for most of the navigation in the course:

* Injecting a block to navigate between sections
* Injecting a block to navigate between modules
* Injecting a block that does both of the above (very similar to the course node in the navigation block)
* Injecting links 'Go to next activity', 'Go back to course', ... into module views.

The course format will also have control over the course 'Quick access' menu, in which it could inject/remove items if they wanted to.

The node 'Switch role' disappears from the administration block and we now require a 'Switch role' block to be added to the course to unlock that functionality. This block would only be displayed to users having the capabilities to switch role.

'''Future of the Administration block'''

At this point, the administration block will not be displayed to any user, except the ones with elevated privileges. Administrators, managers or course creators will still have access to the administration block but it will only contain the 'Site administration' node.

== Implementation details ==

=== User context ===

All the pages on a user context will all have their own layout where the header includes the name of the user in a standardised way, along with some information and a link to message them, and their preferences if the logged in user has the capabilities to edit them. A renderer will be responsible for creating the header, and will use the user ID found from the context defined on that page.

The navigation within the context pages will be:

; For your own context
: Home > Your Name > Page you are on. Clicking on 'Your Name' will lead you to 'My home'.

[[File:userheader.png|frame|none|alt=The header when viewing your context.|The header when your context.]]

; For other users' context
: Home > Users > User Name > Page you are on. Clicking on 'User Name' will lead you to their profile.

[[File:userheader2.png|frame|none|alt=The header when viewing someone else's context.|The header when viewing someone else's context.]]

==== Rules ====

The user header contains very simplistic information about the user, and a few links to very common actions in regard to other users. For instance it can implement a link to send a message to the user, because you might want to be able to do that regardless of what user context page you are visiting. But, 'Edit profile' should not be in it, because it is only relevant to the profile. It is very important to keep the number of available actions to a minimum, because having too many options would defeat the purpose of the simplicity and efficiency it is trying to achieve.

=== A user menu ===

The new user menu would be a new renderer, called from the layout files as it was the case for the login info renderer. The content of the user menu is fixed and not configurable, however it is possible to override the renderer from a theme to change its layout and content.

==== Design ====

Placed on the top right of the site, the name of the user is displayed next to a user icon. The dropdown is displayed when the user clicks the icon or the name. On smaller screens only a user icon is displayed, and expands to reveal its content. When expanded the name of the user logged in is displayed.

When the user is not logged in, a login link is displayed, regardless of the screen size.

==== My grades ====

The 'My grades' page will display the overall grades of the student in all their visible courses. The ordering can be changed, but the default would be alphabetical.

==== Login as ====

When logged in as someone else, the 'Logout' entry becomes 'Return to Admin User'.

==== Switch role ====

When the user role is switched, the 'Logout' entry becomes 'Return to my normal role'. And the name of the user is appended with the role they switch to, e.g. 'Admin User (teacher)'.

==== Trimming navigation ====

At this stage we could trim the navigation block, but we decide not to remove anything just yet as it would create more confusion: some nodes would accessible from the user menu, and others from the navigation block.

==== Rules ====

For it to be used, the user menu needs to be as short as possible and not being cluttered with additional links. It will contain what has been decided above, and not being changed. The users will get used to its content and thus removing nodes is a very tough decision to make. In any case, it should not contain more than 6 links, and should always contain:

* My home
* My profile
* Preferences
* Logout

The links in the menu are very important to the user, they target user context-specific pages and nothing related to the site structure or the course. A link to 'My courses' would be redundant as this information should be covered in the 'My home' page.

=== A user preferences page ===

The preferences page is a list of links to sub-preferences page. The page will be generated from the navigation node 'My profile settings', though we will have to re-organise them so that each link belongs to a parent node. A link to the preferences page is added to the user menu.

==== Re-organisation ====

* User account
** Edit profile
** Account settings
** Change password
** Security keys
** Messaging

* Blogs
** Preferences
** External blogs
** Register an external blog

* Badges
** Manage my badges
** Preferences
** Backpack settings

The preferences page displays headings (the setting nodes) under which the links to the sub-pages will be displayed.

[[File:userpreferences.png|frame|none|alt=User preferences page.|User preferences page.]

The nodes 'Roles' and 'Activity reports' will not be part of this page, because they are context based: they point to the course or site context depending on the page we are on. They will remain in the navigation block, but only when the user has the capability to view them. When the only node in the 'My profile settings' node is 'Preferences', then 'My profile settings' is not displayed. Here is an example when you have the capability to view the reports and roles.

[[File:navblockpref.png|frame|none|alt=My profile settings node with extended capability.|My profile settings node with extended capability.]

==== Naming ====

The 'My profile settings' node becomes the name of the user: 'Frédéric Massart'. The 'Profile settings for Jetha Chan' becomes 'Jetha Chan'.

==== Breadcrumb ====

Each of the sub-pages should be checked to ensure that they are in the right hierarchy, the breadcrumb always looks like '(User context nav) > Preferences > Preference heading > Page I am on'.

==== Another user's preferences ====

The node 'Profile settings for User B' can be used to edit someone's settings. The content is similar to 'My profile settings', except that the node will always be displayed regardless of the presence of 'Roles' or 'Activity reports'. Currently there is no other way for a user with elevated privileges to access someone's preferences, but sooner or later the preferences will be accessible from their profiles.

[[File:navblocksomeonelse.png|frame|none|alt=Profile settings for X with extended capability.|Profile settings for X node with extended capability.]]

==== Repositories ====

Presently the repositories are configurable from the Navigation block, this is the right moment to move them to the 'Preferences' page.

==== Rules ====

Every link in this page should belong to a section, the sections are only headers that help the users finding what they are looking for. A plugin that adds user preferences related to its features should define a new heading and add its links to that heading. The heading is never clickable.

=== A new profile page ===

For now we will only be focussing on the site profile of the user. Later on, we will be solving the problems linked to the course context, for instances the links to 'Blog' or 'Forum interactions' automatically filtered to only display the blog posts in the course.

==== Content ====

The contact details will be displayed in such a way that they do not look like a list any more. For instance, everyone knows what an email address is, there is no need to prefix it with 'Email address:'.

The badges will be displayed on the profile too.

==== Links ====

* Edit profile (If this is your profile)
* Blog
* Forum interactions
* Notes (If you have the capability to)
* Preferences (If you have the capability to and are viewing someone's profile)
* Send a message
* Login as (If you have the capability to)

==== Navigation block ====

We can start trimming the node 'My profile' a bit, but some nodes will remain until we sort out the 'My' page. When doing so, it is important to make sure that the nodes 'Home > Some course > Participants > User B' still contain everything it does right now, because those links point to course-based pages, and would not be accessible otherwise.

==== Rules ====

The profile page contains everything about the user that is public. In other words, a content specific to the user should not be displayed on the profile at all, because it would never be accessible to another user, e.g. 'Private files'.

There are exceptions to this rule, badges for example. As a setting allows you to define whether or not your badges are on your profile, you might not be able to see them there, so they should be available on your dashboard.

For content controlled by permissions (and not preferences), they should remain on the profile. Take 'Blog' as an example, an administrator can prevent blog entries from another user to be accessed depending on your role. As the user does not have any information about the roles of the other users, the blog link is displayed on the profile, but other users will not see it. Having a blog block on the 'My home' page would not be useful because it simply duplicates the access points, for no apparent reason to the user.

=== Revisiting 'My home' page ===

We need to add more default blocks to the existing page, the different available blocks will be:

* My courses (already there)
* My private files (already there)
* The calendar
* Upcoming events
* My latest badges

We need to add a link to 'My latest badges' to the page listing all the badges.

==== Navigation block ====

We can now remove 'My profile' (or now called 'Jetha Chan') from the navigation block entirely. But it has to still be accessible under the node of a user in a course tree.

The node 'My courses' is also removed, users should be used to using their dashboard to access their courses.

==== Rules ====

The 'My home' page contains everything about a user that is private and not accessible to other users. For instance, your calendar events or your private files. The list of courses you are enrolled in are an exception, they could be displayed on the user profile, but because they are so important and need to be layed out in useful fashion, they will be part of the 'My home' page.

This page does not need to link to pages which are already accessible from the 'User menu', for instance the profile.

=== Course context ===

<pre>Pending</pre>

* Handling of course profiles
* An administration page per module
* An administration page for the course
* Accessing course grades for students
* Dedicated solution to access reports
* Alternative site and course navigation
** Checking for inconsistencies in the breadcrumb jumping from one place to another.

== Roadmap ==

=== User context ===

# The user menu
# Implementing the user 'header' for user context pages
# The preferences page
# The new profile page
# Revisiting 'My home'

=== Course context ===

<pre>To be defined.</pre>

== Related links ==

* [https://docs.google.com/document/d/16BJsINun13StUFOQaejj3Gawz9jk22ir_r49f3MbInM/edit#heading=h.fuvsbkikzj88 Navigation experiment]
* [https://docs.google.com/document/d/1AXJw8uX6MczA5VC3phkVVv1ee5eZ2nluIiPC2ecgHLE/edit#heading=h.k3lh9alzq3iy Navigation prototyping 2.7]
* MDL-34838: Navigation inconsistencies
* [http://demo2k12.moodlerooms.com Minimal by Moodlerooms]
* [https://moodle.org/mod/forum/discuss.php?d=226791 Users’ personalised profiles]