MoodleDocs - User contributions [en]

Templates

2018-05-23T21:01:08Z

Tqr: /* An example: tabs */

{{Moodle 2.9}}

= Templates =

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

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

So - putting this all together:

recipe.mustache
<code xml>
<h3>{{recipename}}</h3>
<p>{{description}}</p>
<h4>Ingredients</h4>
<ol>
{{#ingredients}}
<li>{{.}}</li>
{{/ingredients}}
</ol>
<h4>Steps</h4>
<ol>
{{#steps}}
<li>{{{.}}}</li>
{{/steps}}
</ol>
{{ > ratethisrecipe }}
</code>

When given this data:
<code javascript>
{
recipename: "Cheese sandwich",
description: "Who doesn't like a good cheese sandwich?",
ingredients: ["bread", "cheese", "butter"],
steps: ["<p>Step 1 is to spread the butter on the bread</p>", "<p>Step 2 is to put the cheese "in" the bread (not on top, or underneath)</p>"]
}
</code>

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

More info - there are much clearer explanations of templates on the [http://mustache.github.io/mustache.5.html Mustache] website. Try reading those pages "before" posting on stack overflow :) .

=== Blocks (Moodle 3.0 onwards) ===
Blocks are a feature of Mustache that deserves a special mention. They are used as a form of inheritance - and are crucial to building a library of re-usable templates. To make use of "blocks" you define a parent template with replaceable sections. Each of those sections is marked with a "blocks" tag like this (A blocks tag looks like a regular tag, but the variable name is preceded with $):

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

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

<code xml>
{{< section}}
{{$sectionheading}}Latest News{{/sectionheading}}
{{$content}}Nothing happened today - sorry!{{/content}}
{{/section}}
</code>

Notice that when I include a template and I want to make use of blocks - the include tag points the other way:
<code xml>
{{< section}}
</code>
Not
<code xml>
{{> section}}
</code>

Blocks support looping and many other cool things - for more info see https://github.com/bobthecow/mustache.php/wiki/BLOCKS-pragma

== Where do I put my templates? ==

Templates go in the <componentdir>/templates folder and must have a .mustache file extension. When loading templates the template name is <componentname>/<filename> (no file extension).

So "mod_lesson/timer" would load the template at mod/lesson/templates/timer.mustache.

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

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

Rendering a template from javascript is fairly easy. There is a new AMD module that can load/cache and render a template for you.

<code javascript>
// This is AMD code for loading the "core/templates" module. see [Javascript Modules].
require(['core/templates'], function(templates) {

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

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

// It returns a promise that needs to be resoved.
.then(function(html, js) {
// Here eventually I have my compiled template, and any javascript that it generated.
// The templates object has append, prepend and replace functions.
templates.appendNodeContents('.block_looneytunes .content', source, javascript);
}).fail(function(ex) {
// Deal with this exception (I recommend core/notify exception function for this).
});
});
</code>

Under the hood, this did many clever things for us. It loaded the template via an ajax call if it was not cached. It found any missing lang strings in the template and loaded them in a single ajax request, it split the JS from the HTML and returned us both in easy to use way. Read on for how to nicely deal with the javascript parameter.

Note: with some nice chaining and sugar, we can shorten the above example quite a bit:
<code javascript>
require(['core/templates', 'core/notification'], function(templates, notification) {
var context = { name: 'Tweety bird', intelligence: 2 };
templates.render('block_looneytunes/profile', context)
.then(doneCallback)
.fail(notification.exception);
});
</code>

== What if a template contains javascript? ==

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

Example
profile.mustache
<code xml>
<div id="profile">
<p>Name: {{name}}</p>
<p>Intelligence: {{intelligence}}</p>
</div>
{{#js}}
require(['jquery'], function($) {
// Effects! Can we have "blink"?
$('#profile').slideDown();
});
{{/js}}
</code>

If this template is rendered by PHP, the javascript is separated from the HTML, and is appended to a special section in the footer of the page "after" requirejs has loaded. This provides the optimal page loading speed. If the template is rendered by javascript, the javascript source will be passed to the "done" handler from the promise. Then, when the "done" handler has added the template to the DOM, it can call
<code javascript>templates.runTemplateJS(javascript);</code>
which will run the javascript (by creating a new script tag and appending it to the page head).

== What other helpers can I use? ==

The implementation of these helpers is in classes like [https://github.com/moodle/moodle/blob/master/lib/classes/output/mustache_string_helper.php#L31 \core\output\mustache_string_helper]. This is set up in the [https://github.com/moodle/moodle/blob/master/lib/outputrenderers.php#L100 get_mustache method in renderer_base] (There should be no need to look at the implementation, unless you are interested.) If you are considering adding a new helper, it should be limited to display logic - and you need to be able to create identical helpers for the javascript and php implementations (javascript ones go in lib/amd/src/templates.js).

=== {{# str }} ===

There is a string helper for loading language strings.

<code xml>
{{# str }} helloworld, mod_greeting {{/ str }}
</code>

The first 2 parameters are the string id and the component name. So this is effectively Mustache variant of <code>get_string('helloworld', 'mod_greeting')</code>.

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

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

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

Variable tags are allowed to define the value of the <code>$a</code> placeholder:

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

For strings that accept complex placeholder, see the following section.

=== {{# quote }} ===

As shown in the previous section, the <code>{{# str }}</code> helper may need complex data structures passed as the value of the <code>$a</code> placeholder. You can use a JSON object syntax in that case:

<code xml>
{{# str }} iscool, mod_cool, { "firstname": "David", "lastname": "Beckham" } {{/ str }}
</code>

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

<code xml>
{{! DO NOT DO THIS !}}
{{# str }} iscool, mod_cool, { "firstname": "{{ firstname }}", "lastname": "{{ lastname }}" } {{/ str }}
</code>

There is a potential problem though. If the variable tag <code>{{ firstname }}</code> or <code>{{ lastname }}</code> evaluates to a string containing the double quote character, that will break the JSON syntax. We need to escape the double quotes potentially appearing in the variable tags. For this, use the <code>{{# quote }}</code> helper:

<code xml>
{{! This is OK !}}
{{# str }} iscool, mod_cool, { "firstname": {{# quote }}{{ firstname }}{{/ quote }}, "lastname": {{# quote }}{{ lastname }}{{/ quote }} } {{/ str }}
</code>

See MDL-52136 for details.
=== {{# pix }} ===

There is a pix icon helper for generating pix icon tags.

<code xml>
{{# pix }} t/edit, core, Edit David Beckham {{/ pix }}
</code>

The first 2 parameters are the string id and the component name, the rest is the alt text for the image.

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

The recommended way to use this helper is to use the string helper to get one of the core Moodle formats because they have been translated into other languages so you'll get multi-lang support for free (that's a pretty good deal!).

==== Using the string helper (recommended) ====
<code>
// Assuming we had a context variable named "time" set to 1293876000.
{{#userdate}} {{time}}, {{#str}} strftimedate {{/str}} {{/userdate}}
</code>
This will ask the Moodle server for the string "strftimedate" and will use the value (which in this case is "%d %B %Y") to format the user date. So the resulting formatted timestamp from the userdate helper will be "01 January 2011".

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

==== Using hardcoded values ====
<code xml>
{{#userdate}} 1293876000, %A, %d %B %Y, %I:%M %p {{/userdate}}
</code>
Will produce "Saturday, 01 January 2011, 10:00 AM"

=== {{# shortentext }} (Moodle 3.3 onwards) ===
{{Moodle 3.3}}
This helper can be used to shorten a large amount of text to a specified length and will append a trailing ellipsis to signify that the text has been shortened.

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

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

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

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

==== HTML text ====
<code>
{{#shortentext}} 30, <div class='frog'><p><blockquote>Long text with tags that will be chopped off but <b>should be added back again</b></blockquote></p></div></p> {{/shortentext}}
</code>
Will produce:
<code>
<div class='frog'><p><blockquote>Long text with tags that ...</blockquote></p></div>
</code>

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

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

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

Note $context is nothing to do with normal Moodle 'contexts'. It is the data passed to the template (the 'context' mentioned in mustache documentation).

== How do templates work with renderers? ==

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

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

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

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

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

return $data;
}
</code>

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

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

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

== Should I document my templates? ==

Yes!!!! Theme designers need to know the limits of what they can expect to change without breaking anything. As a further benefit - your beautiful new template can be displayed in the "Template Library" tool shipped with Moodle. In order to provide nice documentation and examples for the Template Library, you should follow these conventions when documenting your template.

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

The template library will look for a mustache comment that contains this special marker as the documentation to display, and the source of an example context.

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

==== Useful things to include in the documentation for a template ====
===== Classes required for JS =====
This is a list of classes that are used by the javascript for this template. If removing a class from an element in the template will break the javascript, list it here.

===== Data attributes required for JS =====
This is a list of data attributes (e.g. data-enhance="true") that are used by the javascript for this template. If removing a data attribute from an element in the template will break the javascript, list it here.

===== Context variables required for this template =====
This is a description of the data that may be contained in the context that is passed to the template. Be explicit and document every attribute.

===== Example context (JSON) =====
The Template Library will look for this data in your documentation comment as it allows it to render a "preview" of the template right in the Template Library. This is useful for theme designers to test all the available templates in their new theme to make sure they look nice in a new theme. It is also useful to make sure the template responds to different screen sizes, languages and devices. The format is a JSON-encoded object that is passed directly into the render method for this template.

==== A full example ====
lib/templates/pix_icon.mustache
<pre>
{{!
This file is part of Moodle - http://moodle.org/

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

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

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

Moodle pix_icon template.

The purpose of this template is to render a pix_icon.

Classes required for JS:
* none

Data attributes required for JS:
* none

Context variables required for this template:
* attributes Array of name / value pairs.

Example context (json):
{
"attributes": [
{ "name": "src", "value": "http://moodle.com/wp-content/themes/moodle/images/logo-hat2.png" },
{ "name": "class", "value": "iconsmall" }
]
}

}}
<img {{#attributes}}{{name}}="{{value}}" {{/attributes}}/>
</pre>

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

=== Include GPL at the top of each template ===

Templates are a form of code and it is appropriate to license them like any other code.

===Include a documentation comment for each template===

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

===Use data-attributes for JS hooks===

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

===Avoid custom CSS for templates===

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

===Re-use core templates as much as possible===

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

===Do use the CSS framework classes directly in the templates===

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

===Avoid IDs for styling or javascript===

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

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

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

===Follow CSS coding style===

https://docs.moodle.org/dev/CSS_coding_style

Use hyphens as word-separators for class names.
Use lower case class names.

===Wrap each template in one node with a classname that matches the template name===

Generate a class name by combining the component and template names and separating words with underscore.

e.g.

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

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

===Iterating over php arrays in a mustache template===

Mustache treats hashes and arrays differently because of cross language compatibility
In php arrays and hashes are the same, but mustache treats them differently
It decides a php array is a hash and will not iterate over it if it is non 0 indexed and/or has a gap in the key numbers
so in short
you need to
<code php>
$datafortemplate->mylist = array_values($myarraywithnonnumerickeys)
</code>
you could also use
<code php>
$datafortemplate->mylist = new ArrayIterator($myarraywithnonnumerickeys);
</code>
BUT this fails when $myarraywithnonnumerickeys is empty and you try to use
<code html5>
{{#mylist}}
with an array iterator if mylist is empty this block will not run
{{/mylist}}
{{^mylist}}
with an array iterator mylist will not run this block either because it is not quite empty
{{/mylist}}
</code>

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

Short answer you can't. Include a specific property in the context like "hasusers".

In php
<pre>
{{#users.0}} blah {{/users.0}}
</pre>

will work but please don't use this syntax, it will break if the template is used in javascript AND it mucks up the context.

In javascript

<pre>
{{#users.length}} blah {{/users.length}}
</pre>

will work but please don't use this syntax, it will break if the template is used in php.

===Squash whitespace in a template===
Sometimes whitespace is significant, for example inside a link it will show with an underline. If you want 2 mustache tags from separate lines to be rendered with no whitespace between them you can use mustache comments to squash the whitespace.

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

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

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

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

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

First we can create a basic template to get the general structure down, let's call it tabs. Here's what it might look like:
<pre>
<div id="{{ uniqid }}-tab-container">
<ul role="tablist" class="nav nav-tabs">
{{# tabs }}
<li role="tab"
data-target="{{ uniqid }}-{{ id }}"
data-selected-class="active"
aria-controls="{{ uniqid }}-{{ id }}"
aria-selected="false" tabindex="-1">

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

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

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

The template requires a context that looks something like:
<pre>
{
"tabs": [
{"id":"tab1","name":"Tab 1","content":"This is tab 1 content <a href=\"#\">test</a>"},
{"id":"tab2","name":"Tab 2","content":"This is tab 2 content <a href=\"#\">test</a>"},
{"id":"tab3","name":"Tab 3","content":"This is tab 3 content <a href=\"#\">test</a>"}
]
}
</pre>

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

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

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

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

Here's what the page might look like:
<pre>
<html>
<header><title>User Profile</title></header>
<body>
{{< core/tabs }}
</body>
</html>
</pre>

That looks pretty simple! The only problem is, how do I get my content there? I would have to supply a context like this in order to display the tabs I want:
<pre>
{
"tabs": [
{"id":"tab1","name":"Name","content":"Your name is Mr. Test User."},
{"id":"tab2","name":"Email","content":"Your email is testuser@example.com"},
]
}
</pre>

Let's assume that the context for this page doesn't match what the tabs template is expecting though (as will be the case most of the time). Let's assume the tabs template is being rendered with this context:
<pre>
{
"name":"Mr. Test User",
"email":"testuser@example.com"
}
</pre>

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

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

Let's have another go at that template, this time leveraging blocks:
<pre>
<div id="{{ uniqid }}-tab-container">
{{$ tabheader }}
<ul role="tablist" class="nav nav-tabs">
{{$ tablist }}
{{# tabs }}
<li role="tab"
data-target="{{ uniqid }}-{{ id }}"
data-selected-class="active"
aria-controls="{{ uniqid }}-{{ id }}"
aria-selected="false" tabindex="-1">

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

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

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

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

Now let's see what using this template looks like for your User Profile page:
<pre>
<html>
<header><title>User Profile</title></header>
<body>
{{> core/tabs }}
{{$ tablist }}
<li role="tab"
data-target="{{ uniqid }}-tab1"
data-selected-class="active"
aria-controls="{{ uniqid }}-tab1"
aria-selected="false" tabindex="-1">

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Cool, so let's see what that looks like in our example now:
<pre>
<html>
<header><title>User Profile</title></header>
<body>
{{> core/tabs }}
{{$ tablist }}
{{< core/tab_header_item }}
{{$ tabname }}Name{{/ tabname }}
{{/ core/tab_header_item }}
{{< core/tab_header_item }}
{{$ tabname }}Email{{/ tabname }}
{{/ core/tab_header_item }}
{{/ tablist }}
{{$ tabcontent }}
{{< core/tab_content_item }}
{{$ tabpanelcontent }}Your name is {{ name }}.{{/ tabpanelcontent }}
{{/ core/tab_content_item }}
{{< core/tab_content_item }}
{{$ tabpanelcontent }}Your email address is {{ email }}.{{/ tabpanelcontent }}
{{/ core/tab_content_item }}
{{/ tabcontent }}
{{/ core/tabs }}
</body>
</html>
</pre>

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

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

Templates

2018-03-18T22:07:53Z

Tqr: /* Blocks (Moodle 3.0 onwards) */

{{Moodle 2.9}}

= Templates =

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

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

So - putting this all together:

recipe.mustache
<code xml>
<h3>{{recipename}}</h3>
<p>{{description}}</p>
<h4>Ingredients</h4>
<ol>
{{#ingredients}}
<li>{{.}}</li>
{{/ingredients}}
</ol>
<h4>Steps</h4>
<ol>
{{#steps}}
<li>{{{.}}}</li>
{{/steps}}
</ol>
{{ > ratethisrecipe }}
</code>

When given this data:
<code javascript>
{
recipename: "Cheese sandwich",
description: "Who doesn't like a good cheese sandwich?",
ingredients: ["bread", "cheese", "butter"],
steps: ["<p>Step 1 is to spread the butter on the bread</p>", "<p>Step 2 is to put the cheese "in" the bread (not on top, or underneath)</p>"]
}
</code>

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

More info - there are much clearer explanations of templates on the [http://mustache.github.io/mustache.5.html Mustache] website. Try reading those pages "before" posting on stack overflow :) .

=== Blocks (Moodle 3.0 onwards) ===
Blocks are a feature of Mustache that deserves a special mention. They are used as a form of inheritance - and are crucial to building a library of re-usable templates. To make use of "blocks" you define a parent template with replaceable sections. Each of those sections is marked with a "blocks" tag like this (A blocks tag looks like a regular tag, but the variable name is preceded with $):

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

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

<code xml>
{{< section}}
{{$sectionheading}}Latest News{{/sectionheading}}
{{$content}}Nothing happened today - sorry!{{/content}}
{{/section}}
</code>

Notice that when I include a template and I want to make use of blocks - the include tag points the other way:
<code xml>
{{< section}}
</code>
Not
<code xml>
{{> section}}
</code>

Blocks support looping and many other cool things - for more info see https://github.com/bobthecow/mustache.php/wiki/BLOCKS-pragma

== Where do I put my templates? ==

Templates go in the <componentdir>/templates folder and must have a .mustache file extension. When loading templates the template name is <componentname>/<filename> (no file extension).

So "mod_lesson/timer" would load the template at mod/lesson/templates/timer.mustache.

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

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

Rendering a template from javascript is fairly easy. There is a new AMD module that can load/cache and render a template for you.

<code javascript>
// This is AMD code for loading the "core/templates" module. see [Javascript Modules].
require(['core/templates'], function(templates) {

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

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

// It returns a promise that needs to be resoved.
.then(function(html, js) {
// Here eventually I have my compiled template, and any javascript that it generated.
// The templates object has append, prepend and replace functions.
templates.appendNodeContents('.block_looneytunes .content', source, javascript);
}).fail(function(ex) {
// Deal with this exception (I recommend core/notify exception function for this).
});
});
</code>

Under the hood, this did many clever things for us. It loaded the template via an ajax call if it was not cached. It found any missing lang strings in the template and loaded them in a single ajax request, it split the JS from the HTML and returned us both in easy to use way. Read on for how to nicely deal with the javascript parameter.

Note: with some nice chaining and sugar, we can shorten the above example quite a bit:
<code javascript>
require(['core/templates', 'core/notification'], function(templates, notification) {
var context = { name: 'Tweety bird', intelligence: 2 };
templates.render('block_looneytunes/profile', context)
.then(doneCallback)
.fail(notification.exception);
});
</code>

== What if a template contains javascript? ==

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

Example
profile.mustache
<code xml>
<div id="profile">
<p>Name: {{name}}</p>
<p>Intelligence: {{intelligence}}</p>
</div>
{{#js}}
require(['jquery'], function($) {
// Effects! Can we have "blink"?
$('#profile').slideDown();
});
{{/js}}
</code>

If this template is rendered by PHP, the javascript is separated from the HTML, and is appended to a special section in the footer of the page "after" requirejs has loaded. This provides the optimal page loading speed. If the template is rendered by javascript, the javascript source will be passed to the "done" handler from the promise. Then, when the "done" handler has added the template to the DOM, it can call
<code javascript>templates.runTemplateJS(javascript);</code>
which will run the javascript (by creating a new script tag and appending it to the page head).

== What other helpers can I use? ==

The implementation of these helpers is in classes like [https://github.com/moodle/moodle/blob/master/lib/classes/output/mustache_string_helper.php#L31 \core\output\mustache_string_helper]. This is set up in the [https://github.com/moodle/moodle/blob/master/lib/outputrenderers.php#L100 get_mustache method in renderer_base] (There should be no need to look at the implementation, unless you are interested.) If you are considering adding a new helper, it should be limited to display logic - and you need to be able to create identical helpers for the javascript and php implementations (javascript ones go in lib/amd/src/templates.js).

=== {{# str }} ===

There is a string helper for loading language strings.

<code xml>
{{# str }} helloworld, mod_greeting {{/ str }}
</code>

The first 2 parameters are the string id and the component name. So this is effectively Mustache variant of <code>get_string('helloworld', 'mod_greeting')</code>.

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

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

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

Variable tags are allowed to define the value of the <code>$a</code> placeholder:

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

For strings that accept complex placeholder, see the following section.

=== {{# quote }} ===

As shown in the previous section, the <code>{{# str }}</code> helper may need complex data structures passed as the value of the <code>$a</code> placeholder. You can use a JSON object syntax in that case:

<code xml>
{{# str }} iscool, mod_cool, { "firstname": "David", "lastname": "Beckham" } {{/ str }}
</code>

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

<code xml>
{{! DO NOT DO THIS !}}
{{# str }} iscool, mod_cool, { "firstname": "{{ firstname }}", "lastname": "{{ lastname }}" } {{/ str }}
</code>

There is a potential problem though. If the variable tag <code>{{ firstname }}</code> or <code>{{ lastname }}</code> evaluates to a string containing the double quote character, that will break the JSON syntax. We need to escape the double quotes potentially appearing in the variable tags. For this, use the <code>{{# quote }}</code> helper:

<code xml>
{{! This is OK !}}
{{# str }} iscool, mod_cool, { "firstname": {{# quote }}{{ firstname }}{{/ quote }}, "lastname": {{# quote }}{{ lastname }}{{/ quote }} } {{/ str }}
</code>

See MDL-52136 for details.
=== {{# pix }} ===

There is a pix icon helper for generating pix icon tags.

<code xml>
{{# pix }} t/edit, core, Edit David Beckham {{/ pix }}
</code>

The first 2 parameters are the string id and the component name, the rest is the alt text for the image.

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

The recommended way to use this helper is to use the string helper to get one of the core Moodle formats because they have been translated into other languages so you'll get multi-lang support for free (that's a pretty good deal!).

==== Using the string helper (recommended) ====
<code>
// Assuming we had a context variable named "time" set to 1293876000.
{{#userdate}} {{time}}, {{#str}} strftimedate {{/str}} {{/userdate}}
</code>
This will ask the Moodle server for the string "strftimedate" and will use the value (which in this case is "%d %B %Y") to format the user date. So the resulting formatted timestamp from the userdate helper will be "01 January 2011".

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

==== Using hardcoded values ====
<code xml>
{{#userdate}} 1293876000, %A, %d %B %Y, %I:%M %p {{/userdate}}
</code>
Will produce "Saturday, 01 January 2011, 10:00 AM"

=== {{# shortentext }} (Moodle 3.3 onwards) ===
{{Moodle 3.3}}
This helper can be used to shorten a large amount of text to a specified length and will append a trailing ellipsis to signify that the text has been shortened.

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

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

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

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

==== HTML text ====
<code>
{{#shortentext}} 30, <div class='frog'><p><blockquote>Long text with tags that will be chopped off but <b>should be added back again</b></blockquote></p></div></p> {{/shortentext}}
</code>
Will produce:
<code>
<div class='frog'><p><blockquote>Long text with tags that ...</blockquote></p></div>
</code>

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

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

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

Note $context is nothing to do with normal Moodle 'contexts'. It is the data passed to the template (the 'context' mentioned in mustache documentation).

== How do templates work with renderers? ==

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

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

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

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

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

return $data;
}
</code>

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

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

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

== Should I document my templates? ==

Yes!!!! Theme designers need to know the limits of what they can expect to change without breaking anything. As a further benefit - your beautiful new template can be displayed in the "Template Library" tool shipped with Moodle. In order to provide nice documentation and examples for the Template Library, you should follow these conventions when documenting your template.

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

The template library will look for a mustache comment that contains this special marker as the documentation to display, and the source of an example context.

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

==== Useful things to include in the documentation for a template ====
===== Classes required for JS =====
This is a list of classes that are used by the javascript for this template. If removing a class from an element in the template will break the javascript, list it here.

===== Data attributes required for JS =====
This is a list of data attributes (e.g. data-enhance="true") that are used by the javascript for this template. If removing a data attribute from an element in the template will break the javascript, list it here.

===== Context variables required for this template =====
This is a description of the data that may be contained in the context that is passed to the template. Be explicit and document every attribute.

===== Example context (JSON) =====
The Template Library will look for this data in your documentation comment as it allows it to render a "preview" of the template right in the Template Library. This is useful for theme designers to test all the available templates in their new theme to make sure they look nice in a new theme. It is also useful to make sure the template responds to different screen sizes, languages and devices. The format is a JSON-encoded object that is passed directly into the render method for this template.

==== A full example ====
lib/templates/pix_icon.mustache
<pre>
{{!
This file is part of Moodle - http://moodle.org/

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

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

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

Moodle pix_icon template.

The purpose of this template is to render a pix_icon.

Classes required for JS:
* none

Data attributes required for JS:
* none

Context variables required for this template:
* attributes Array of name / value pairs.

Example context (json):
{
"attributes": [
{ "name": "src", "value": "http://moodle.com/wp-content/themes/moodle/images/logo-hat2.png" },
{ "name": "class", "value": "iconsmall" }
]
}

}}
<img {{#attributes}}{{name}}="{{value}}" {{/attributes}}/>
</pre>

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

=== Include GPL at the top of each template ===

Templates are a form of code and it is appropriate to license them like any other code.

===Include a documentation comment for each template===

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

===Use data-attributes for JS hooks===

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

===Avoid custom CSS for templates===

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

===Re-use core templates as much as possible===

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

===Do use the CSS framework classes directly in the templates===

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

===Avoid IDs for styling or javascript===

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

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

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

===Follow CSS coding style===

https://docs.moodle.org/dev/CSS_coding_style

Use hyphens as word-separators for class names.
Use lower case class names.

===Wrap each template in one node with a classname that matches the template name===

Generate a class name by combining the component and template names and separating words with underscore.

e.g.

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

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

===Iterating over php arrays in a mustache template===

Mustache treats hashes and arrays differently because of cross language compatibility
In php arrays and hashes are the same, but mustache treats them differently
It decides a php array is a hash and will not iterate over it if it is non 0 indexed and/or has a gap in the key numbers
so in short
you need to
<code php>
$datafortemplate->mylist = array_values($myarraywithnonnumerickeys)
</code>
you could also use
<code php>
$datafortemplate->mylist = new ArrayIterator($myarraywithnonnumerickeys);
</code>
BUT this fails when $myarraywithnonnumerickeys is empty and you try to use
<code html5>
{{#mylist}}
with an array iterator if mylist is empty this block will not run
{{/mylist}}
{{^mylist}}
with an array iterator mylist will not run this block either because it is not quite empty
{{/mylist}}
</code>

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

Short answer you can't. Include a specific property in the context like "hasusers".

In php
<pre>
{{#users.0}} blah {{/users.0}}
</pre>

will work but please don't use this syntax, it will break if the template is used in javascript AND it mucks up the context.

In javascript

<pre>
{{#users.length}} blah {{/users.length}}
</pre>

will work but please don't use this syntax, it will break if the template is used in php.

===Squash whitespace in a template===
Sometimes whitespace is significant, for example inside a link it will show with an underline. If you want 2 mustache tags from separate lines to be rendered with no whitespace between them you can use mustache comments to squash the whitespace.

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

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

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

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

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

First we can create a basic template to get the general structure down, let's call it tabs. Here's what it might look like:
<pre>
<div id="{{ uniqid }}-tab-container">
<ul role="tablist" class="nav nav-tabs">
{{# tabs }}
<li role="tab"
data-target="{{ uniqid }}-{{ id }}"
data-selected-class="active"
aria-controls="{{ uniqid }}-{{ id }}"
aria-selected="false" tabindex="-1">

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

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

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

The template requires a context that looks something like:
<pre>
{
"tabs": [
{"id":"tab1","name":"Tab 1","content":"This is tab 1 content <a href=\"#\">test</a>"},
{"id":"tab2","name":"Tab 2","content":"This is tab 2 content <a href=\"#\">test</a>"},
{"id":"tab3","name":"Tab 3","content":"This is tab 3 content <a href=\"#\">test</a>"}
]
}
</pre>

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

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

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

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

Here's what the page might look like:
<pre>
<html>
<header><title>User Profile</title></header>
<body>
{{< core/tabs }}
</body>
</html>
</pre>

That looks pretty simple! The only problem is, how do I get my content there? I would have to supply a context like this in order to display the tabs I want:
<pre>
{
"tabs": [
{"id":"tab1","name":"Name","content":"Your name is Mr. Test User."},
{"id":"tab2","name":"Email","content":"Your email is testuser@example.com"},
]
}
</pre>

Let's assume that the context for this page doesn't match what the tabs template is expecting though (as will be the case most of the time). Let's assume the tabs template is being rendered with this context:
<pre>
{
"name":"Mr. Test User",
"email":"testuser@example.com"
}
</pre>

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

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

Let's have another go at that template, this time leverging blocks:
<pre>
<div id="{{ uniqid }}-tab-container">
{{$ tabheader }}
<ul role="tablist" class="nav nav-tabs">
{{$ tablist }}
{{# tabs }}
<li role="tab"
data-target="{{ uniqid }}-{{ id }}"
data-selected-class="active"
aria-controls="{{ uniqid }}-{{ id }}"
aria-selected="false" tabindex="-1">

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

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

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

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

Now let's see what using this template looks like for your User Profile page:
<pre>
<html>
<header><title>User Profile</title></header>
<body>
{{> core/tabs }}
{{$ tablist }}
<li role="tab"
data-target="{{ uniqid }}-tab1"
data-selected-class="active"
aria-controls="{{ uniqid }}-tab1"
aria-selected="false" tabindex="-1">

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Cool, so let's see what that looks like in our example now:
<pre>
<html>
<header><title>User Profile</title></header>
<body>
{{> core/tabs }}
{{$ tablist }}
{{< core/tab_header_item }}
{{$ tabname }}Name{{/ tabname }}
{{/ core/tab_header_item }}
{{< core/tab_header_item }}
{{$ tabname }}Email{{/ tabname }}
{{/ core/tab_header_item }}
{{/ tablist }}
{{$ tabcontent }}
{{< core/tab_content_item }}
{{$ tabpanelcontent }}Your name is {{ name }}.{{/ tabpanelcontent }}
{{/ core/tab_content_item }}
{{< core/tab_content_item }}
{{$ tabpanelcontent }}Your email address is {{ email }}.{{/ tabpanelcontent }}
{{/ core/tab_content_item }}
{{/ tabcontent }}
{{/ core/tabs }}
</body>
</html>
</pre>

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

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

Git for developers

2017-01-20T20:48:39Z

Tqr: /* Keeping your public repository up-to-date */

This document is for helping you get started on Moodle development with Git. For further details of Git, see [[:Category:Git]].

== General workflow ==

'''A reasonable knowledge of the Git basics is a good idea before you start to use it for development. If you are new to Git, you are encouraged to go to 'See also' for some more general reading.'''

[[image:git-pushpull-model.png|right|thumb|400px|Moodle development workflow with Git]]
Detailed explanation of the workflow can be found in the [[Process]] page. In short, the Moodle development with Git looks like this:

* You as the contributor commit changes into your personal repository at your computer
* You push the changes into your public repository and publish links to your changes in the Moodle Tracker
* You request a peer review of your code from another developer
* When peer reviewer is happy they submit issue for integration
* Moodle integrators pull the changes from your public repository and if they like them, they put them into Moodle integration repository
* The integrated change is tested and finally pushed into Moodle production repository
* You update your local repository with all changes from the production repository and the next cycle may start again

This workflow runs in roughly weekly cycles. The integration happens on Monday and Tuesday and the testing on Wednesday. On Thursday (or Friday if testing takes too long), the production repository moodle.git is usually updated with changes from the last development week.

Most Moodle developers have their public repositories hosted at [http://github.com/ Github]. Alternatively you may want to try [http://gitorious.org Gitorious] or the legendary [http://repo.or.cz repo.or.cz]. In the examples in this guide we assume you'll set up your public repository at Github.

When you first register on tracker you can not assign issues to yourself or send them for peer review. You will be added to the developers group after your first bug fix is integrated. Before that just comment on the issue with a link to your branch and component lead or another developer will send issue for peer review for you.

== Installing Git on your computer ==

Install Git on your computer. Most Linux distributions have Git available as a package to install. On Debian/Ubuntu, type ''''sudo apt-get install git'''' on the terminal. If you are on Mac, [http://code.google.com/p/git-osx-installer/ git-osx-installer] installs it in a few clicks.

Immediately after the installation, set your name and contact e-mail. The name and e-mail will become part of your commits and they can't be changed later once your commits are accepted into the Moodle code. Therefore we ask contributors to use their real names written in capital letters, eg "John Smith" and not "john smith" or even "john5677".

git config --global user.name "Your Name"
git config --global user.email yourmail@domain.tld

Unless you are the repository maintainer, it is wise to set your Git to not push changes in file permissions:

git config --global core.filemode false

Also, it's recommended to verify that the your git installation is not performing any transformation between LFs and CRLFs. All Moodle '''uses only LFs''' and you should '''fetch/edit and push''' it that way (may need to configure your editor/IDE too). Note that having any "magic" enabled is known to cause [[Common unit test problems#The_test_file_.22evolution.test.22_should_not_contain_section_named_.22.5Blots_of_content.5D.22|problems with unit tests]] execution. So we recommend you to set:

git config --global core.autocrlf false

== Setting-up the public repository ==

1. Go to [http://github.com/ Github] and create an account.

2. Go to the [http://github.com/moodle/moodle official Moodle Github repository] and click on the Fork button. You now have your own Github Moodle repository.

3. Now you need to set up your SSH public key, so you can push to your Github Moodle repository from your local Moodle repository. On Mac you can go on this [http://help.github.com/mac-key-setup/ Github help page]. If you are on another system, go to your Github administration page, to the section SSH Public Keys, and you should see a link to a help page. Done? Good! That was the most difficult part!

== Setting-up the local repository at your computer ==

Create a local clone repository of your Github repository. In a terminal:

git clone git://github.com/YOUR_GITHUB_USERNAME/moodle.git LOCALDIR

(or: git clone git@github.com:YOUR_GITHUB_USERNAME/moodle.git LOCALDIR)

This command does several jobs for you. It creates a new folder, initializes an empty Git repository in it, sets your Github repository as the remote repository called 'origin' and makes a local checkout of the branch 'master' from it. The important point to remember now is that your Github repository is aliased as 'origin' for your local clone.

Note that the format of the URL here is important. In the first example, the URL starts "git://github.com" and this will give read-only access to the repository at github.com. If you use this URL, the "git push origin" command that appears later in this document will not work. Therefore, if you want to be able to update the "origin" repository, you should use the URL that starts "git@github.com", i.e. the second of the two "git clone" commands given above. This will give you read and write access to the repository on github.com.

== Keeping your public repository up-to-date ==

[[image:git-sync-github.png|right|thumb|400px|Fetching changes from upstream and pushing them to github]]
Your fork at Github is not updated automatically. To keep it synced with the upstream Moodle repository, you have to fetch the recent changes from the official moodle.git and push them to your public repository. To avoid problems with this it is strongly recommended that you never modify the standard Moodle branches. ''Remember: never commit directly into master and MOODLE_xx_STABLE branches.'' In other words, always create topic branches to work on. In Gitspeak, the master branch and MOODLE_xx_STABLE branches should be always fast-forwardable.

To keep your public repository up-to-date, we will register remote repository git://git.moodle.org/moodle.git under 'upstream' alias. Then we create a script to be run regularly that fetches changes from the upstream repository and pushes them to your public repository. Note that this procedure will not affect your local working directory.

To register the upstream remote:

cd moodle
git remote add upstream git://git.moodle.org/moodle.git

The following commands can be used to keep the standard Moodle branches at your Github repository synced with the upstream repository. You may wish to store them in a script so that you can run it every week after the upstream repository is updated.

#!/bin/bash
git fetch upstream
for BRANCH in MOODLE_{19..32}_STABLE master; do
git push origin refs/remotes/upstream/$BRANCH:$BRANCH
done

=== How it works ===

The git-fetch command does not modify your current working dir (your checkout). It just downloads all recent changes from a remote repository and stores them into so called remote-tracking branches. The git-push command takes these remote-tracking branches from upstream and pushes them to Github under the same name. Understanding this fully requires a bit knowledge of Git internals - see gitrevisions(7) man page.

Note there is no need to switch the local branch during this. You can even execute this via cron at your machine. Just note that the upstream repository updates typically just once a week.

=== New branches ===

Occasionally, moodle.org will create a new branch that does not exist in your public (e.g. Github.com) repository. If you try to push this new branch, you will see an error such as the following:

error: unable to push to unqualified destination: MOODLE_99_STABLE
The destination refspec neither matches an existing ref on the remote
nor begins with refs/, and we are unable to guess a prefix based on the source ref.
error: failed to push some refs to 'git@github.com:YOUR_GITHUB_USERNAME/moodle.git'

In the above example, "MOODLE_99_STABLE", is the name of the new branch that does not exist in your public repository. To fix the error, you need to create the new branch on your public repository, using the following commands, replacing "MOODLE_99_STABLE" with the name of the new branch you wish to create:

git checkout MOODLE_99_STABLE
git push origin MOODLE_99_STABLE:MOODLE_99_STABLE

The above code will create a new copy of the "MOODLE_99_STABLE" branch in your local repository. If you do not need to keep a local copy of the new branch - and probably you do not need it, you then can remove it from your local repository as follows:

git checkout master
git branch -D MOODLE_99_STABLE

== Preparing a patch ==

As said earlier at this page, you never work on standard Moodle branches directly. Every time you are going to edit something, switch to a local branch. Fork the local branch off the standard branch you think it should be merged to. So if you are working on a patch for 1.9 or 2.0, fork the branch off MOODLE_19_STABLE or MOODLE_20_STABLE, respectively. Patches for the next [[Moodle versions|major version]] should be based on the master branch.

git checkout -b MDL-xxxxx-nasty-bug origin/master

Note that if you forget to specify the starting point, the branch is based on the currently checked-out branch. It may not be what you want. It is recommended to always specify the starting point.

To check the current branch, run

git branch

The current branch is highlighted.

Now go and fix the issue with your favorite IDE. Check the status of the files, view the change to be committed and finally commit the change:

vim filename.php
git status
git diff
git commit -a

Note that this is safe as the commit is recorded just locally, nothing is sent to any server yet (as it would in CVS). To see history of the commits, use

git log

Once your local branch contains the change (note that it may consists of several patches) and you are happy with it, publish the branch at your public repository:

git push origin MDL-xxxxx-nasty-bug

Now as your branch is published, you can ask Moodle core developers to review it and eventually integrate it into the standard Moodle repository.

=== Changing commit message, reordering and squashing commits ===

It often happens that you made a mistake in your patch or in the commit message and helpful CiBot pointed it out for you. You can "rewrite the history" and change the existing commits.

Option 1. Reset all the changes in the branch and commit again.

git reset --mixed origin/master

Now all your changes are still present but all commits on top of "master" branch are gone. You can create a new commit

Option 2. Discover '''git rebase''' - this is a powerful tool to change the sequence of commit, change the commit messages, squash commits, etc. We will not cover it here, there are many articles in the Internet about it.

Whatever option you chose, you have "rewritten the history" and you can not simply push the changes to github again because they would need to overwrite the commits that were already pushed. If you try "git push MDL-xxxxx-nasty-bug" you will get an error message suggesting you to force push.
To force push the changed commits use:

git push -f origin MDL-xxxxx-nasty-bug

If an error occurs because you are still using the git protocol (read only), use this command :

git remote set-url origin https://github.com/<user.name>/moodle.git

A prompt will ask for your credentials, if you previously setup your SSH public key you can also use this one :

git remote set-url origin git@github.com:<user.name>/moodle.git

=== Checking if a branch has already been merged ===

After some time contributing to Moodle you would have a lot of branches both in your local repository and in your public repository. To prune their list and delete those that were accepted by upstream, use the following

git fetch upstream (1)
git branch --merged upstream/master (2)
git branch --merged upstream/MOODLE_20_STABLE (3)

The command (1) fetches the changes from your upstream repository at git.moodle.org (remember that git-fetch does not modify your working dir so it is safe to run it whenever). Command (2) and (3) print all branches that are merged into the upstream master branch and MOODLE_20_STABLE branch, respectively. To delete these local branches, use

git branch -d MDL-xxxxx-accepted-branch

The similar approach can be used to check the branches published at your origin repository at github.com

git fetch origin (1)
git fetch upstream
git branch -r --merged upstream/master (2)
git branch -r --merged upstream/MOODLE_20_STABLE (3)

The command (1) makes sure that you have all your branches from github.com recorded as the remote tracking branch locally. Commands (2) and (3) work the same as in the previous example but they list remote tracking branches only ([http://www.kernel.org/pub/software/scm/git/docs/git-branch.html see -r param]). To delete a branch at github.com, use

git push origin :MDL-xxxx-branch-to-delete

This syntax may look weird to you. However it is pretty logical. The general syntax of the git-push command is

git push <repository> <source ref>:<target ref>

so deleting a remote branch can be understood as pushing an "empty (null) reference" to it.

== Peer-reviewing someone else's code ==

To review a branch that someone else pushed into their public repository, you do not need to register a new remote (unless you work with such repository frequently, of course). Let us imagine your friend Alice pushed a work-in-progress branch called 'wip-feature' into her Github repository and asked you to review it. You need to know the read-only address of the repository and the name of the branch.

git fetch git://github.com/alice/moodle.git wip-feature

This will download all required data and will keep the pointer to the tip of the wip-feature branch in a local symbolic reference FETCH_HEAD. To see what's there on that branch, use

git log -p FETCH_HEAD

To see how a particular file looks at Alice's branch

git show FETCH_HEAD:admin/blocks.php

To create a new local branch called 'alice-wip-feature' containing the work by Alice, use

git checkout -b alice-wip-feature FETCH_HEAD

To merge Alice's work into your current branch:

git merge FETCH_HEAD

To see what would be merged into the current branch without actually modifying anything:

git diff ...FETCH_HEAD

Once you are all set and reviewing code, this [[Peer_reviewing_checklist|checklist]] should prove to be useful.

== Rebasing a branch ==

Rebasing is a process when you cut off the branch from its current start point and transplant it to another point. Let us assume the following history exists:

A---B---C topic
/
D---E---F---G master

From this point, the result of the command:

git rebase master topic

would be:

A'--B'--C' topic
/
D---E---F---G master

and would end with 'topic' being your current branch.

You may be asked to rebase your branch submitted for the integration if the submitted branch was based on an outdated commit. The typical case is if you create a new branch as a fork off the upstream master branch on Tuesday. Then on Wednesday, the upstream master branch grows as all changes from the last integration cycle are merged to it. To make diff easy on Github for next weekly pull request review, you want to rebase your branch against the updated master.

git rebase master MDL-xxxxx-topic-branch

Note that rebasing effectively rewrites the history of the branch. '''Do not rebase the branch if there is a chance that somebody has already forked it and based their own branch on it.''' For this reason, many Git tutorials discourage from rebasing any branch that has been published. However in Moodle, all branches submitted for integration are potential subject of rebase (even though we try to not to do it often) and you should not base your own branches on them.

=== Conflicts during rebase ===

During the rebase procedure, conflicts may appear. git-status commands reports the conflicted files. Explore them carefully and fix them in your editor (like you would do with CVS). Then add the files with 'git add' command and continue.

vim conflicted.php
git add conflicted.php
git rebase --continue

== Applying changes from one branch to another ==

Most bugs are fixed at a stable branch (like MOODLE_20_STABLE) and the fix must be prepared for other branches, too (like MOODLE_21_STABLE and the main development branch - master). In Moodle, we do not merge stable branches into the master one. So usually the contributor prepares at least two branches - with the fix for the stable branch(es) and with the fix for the master branch.

If you have a patch prepared on a local branch (let us say MDL-xxxx-topic_20_STABLE), it is possible to re-apply it to another branch.

=== Cherry-picking a single commit ===

Let us have two local Git repositories ~/public_html/moodle21 containing local installation of Moodle 2.1 and ~/public_html/moodledev with the local installation of most recent development version of Moodle. They both use your public repository at github.com as the origin. You have a branch in moodle21 called MDL-xxxx-topic_21_STABLE that was forked off MOODLE_21_STABLE. It contains one commit. Now you want to re-apply this commit to a branch MDL-xxxx-topic in moodledev.

cd ~/public_html/moodledev
git checkout -b MDL-xxxx-topic origin/master (1)
git fetch ../moodle21 MDL-xxxx-topic_21_STABLE (2)
git cherry-pick FETCH_HEAD (3)

The command (1) creates new local branch forked off the CONTHERE The command (1) fetches all data needed to re-apply the topic branch and stores the pointer to the tip of that branch to FETCH_HEAD symbolic reference. The command (2) picks the tip of the branch (the top-most commit on it) and tries to apply it on the current branch.
There is also a variant of the cherry-pick command that supports multiple commits, shortly (see its man page for details): <code bash>$ git cherry-pick A^..B</code> if you want to include from A - see '''^''' - to B, A should be older than B. We will use another approach for cherry-picking multiple commits.

=== Applying a set of patches ===

If the branch MDL-xxxx-topic_21_STABLE from the previous example consists of several commits, it may be easier to use git-format-patch and git-am combo to re-apply the whole set of patches (aka patchset). Firstly you will export all commits from the topic branch to files.

cd ~/public_html/moodle21
mkdir .patches
git format-patch -o .patches MOODLE_21_STABLE..MDL-xxxx-topic_21_STABLE (1)

The command (1) takes all commits from the topic branch that are not in MOODLE_21_STABLE and exports them one by one to the output directory .patches. Look at the generated files. They contain the patch itself (in diff format) and additional information about the commit. You could eg send these files by email to a friend of yours for peer-review. We will use them in another repository.

cd ~/public_html/moodledev
git checkout -b MDL-xxxx-topic origin/master
git am -3 ../moodle21/.patches/* (1)

The command (1) applies all the files from the .patches directory. When a patch does not apply cleanly, the command tries fall back on 3-way merge (see the -3 parameter). If conflicts occur during the procedure, you can either deal with them and then use `git am --continue` or abort the whole procedure with `git am --abort`.

== See also ==

; Moodle forum discussions
* [http://moodle.org/mod/forum/discuss.php?d=168094 GIT help needed]
* [http://moodle.org/mod/forum/discuss.php?d=165236 Best way to manage CONTRIB code with GIT]
* [http://moodle.org/mod/forum/discuss.php?d=167063 Handy Git tip for tracking 3rd-party modules and plugins]
* [http://moodle.org/mod/forum/discuss.php?d=167730 Moodle Git repositories]
* [http://moodle.org/mod/forum/discuss.php?d=183409 Git help!! I don't understand rebase enough...]
* [http://moodle.org/mod/forum/discuss.php?d=217617 add MOODLE_24_STABLE to github.com repository]

; External resources
* [http://www.kernel.org/pub/software/scm/git/docs/everyday.html Everyday GIT With 20 Commands Or So]
* [http://gitref.org/ Git Reference]
* [http://progit.org/book/ Pro Git book]
* [http://vimeo.com/14629850 Getting git by Scott Chacon] - an recording of an excellent 1-hour presentation that introducing git, including a simple introduction to what is going on under the hood.
* [http://tjhunt.blogspot.co.uk/2012/03/fixing-bug-in-moodle-core-mechanics.html Tim Hunt's blog: Fixing a bug in Moodle core: the mechanics]

[[Category:Git]]

[[ja:開発者用Git]]

LTI Improvements 3.2 Project

2016-08-06T07:04:10Z

Tqr: /* Summary */

{{Infobox Project
|name = Improvements to LTI for 3.2
|state = Developing
|tracker = MDL-54679
|discussion = https://moodle.org/mod/forum/discuss.php?d=xxx
|assignee = [[User:John Okely]]
}}

= Summary =
The Learning Tools Interoperability (LTI) provider was added to Moodle 3.1 - but unfortunately our LTI provider and consumer do not support the same standards, and as such are missing important functionality, therefore they need usability improvements.

'''Below are a range of issues that have been identified and are being worked on for Moodle 3.2.'''

== Improvements ==
The targeted improvements for 3.2 are:
* Offer cartridges in LTI provider
* <strike>Support standard icon element when importing LTI cartridges</strike>
* Upgrade enrol_lti to support LTI v2.0
* Ensure enrol_lti member syncronisation task works as expected
* Content Item support
* Add support for LTI Outcomes Management 2 services
* Caliper Analytics
* Run the LTI Test suite against Moodle (consumer + provider) and create issues for any failures (in this Epic)
* Fix auto-closing LTI config window
* Improve interface for managing course tools
* Add support for services via LTI1 (LTI1.2 spec)
* Improve accessibility of new LTI admin screen

To see the most recent set of issues and status of the project see https://tracker.moodle.org/browse/MDL-54679

==Progress==
* Cartridges patch is completed, waiting for integration review
* A Content-Item patch was started by Stephen Vickers. The patch has been altered and refactored. Working on automated testing now
* A patch has been created using the new LTI library provided by IMS to bring the provider up to LTI 2.
* Membership synchronisation is being looked at in conjunction with LTI2

==Prototype==
The [http://prototype.moodle.net/lti/ work in progress prototype] is available to view on the prototype site.
You can add tools via tool proxy, and via cartridge. You can configure a tool type when you add it using Content-item

Theme checklist

2016-07-14T18:46:51Z

Tqr: /* Quiz 'secure' pop-up */

{{Template:Themes}}So, you think your theme is finished? Well, Moodle is a big complex system and there are lots of obscure corners that you might not know about. This page lists lots of things that you might have missed when working on your theme. To be sure your theme is really complete, you need to check these out.

== Accessible colours ==

Are the colours you have chosen accessible? Is there a reasonable contrast difference between them?

== All the different forms of the front page ==

Depending on how many courses there are in your Moodle site, and how many of them the current user is enrolled in, the [[:en:Front_page|front page]] looks different. Have you tested all the different ways it can look?

== Big report tables ==

The [[:en:Gradebook|grader report]], and other similar reports like the quiz reports, are very big tables that don't fit on one screen. How does your theme cope. Is it easy for the teacher to scroll sideways to see all the data?

== Clean install ==

Have you installed and un-installed the theme on a 'pure' installation? That is an installation with no other contributed plugins. This allows you to check for unintentional dependencies.

== Code checker ==

[https://moodle.org/plugins/view.php?plugin=local_codechecker Code checker] checks your code against the Moodle [https://docs.moodle.org/dev/Coding coding standards]. It is a useful tool for spotting issues and making your code readable to all who are familiar with the core code. Do not take all messages literally, use your common sense and make changes that are sensible.

== Dependencies ==

Have you specified the correct dependencies for both parent themes and Moodle in the '[https://docs.moodle.org/dev/version.php version.php]' file?

== Fake blocks ==

While you are looking at the quiz, pay attention to the [[:en:Using_Quiz|Quiz navigation block]]. This is not a normal block that teachers or admins can add or remove, it is a 'Fake block' that looks like any other block but is part of the Moodle UI. Are you happy with where it appears, and how it looks?

Other parts of Moodle that use fake blocks are the [[:en:Lesson_module|Lesson activity]] and [[:en:Calendar|the calendar UI]].

Fake blocks are attached to the first region or the 'defaultregion' in the 'regions' array for the 'layout' in the 'layouts' array in the 'config.php' file. So if the order is ('side-pre', 'side-post') and you want fake blocks to be in 'side-post' change the 'defaultregion' to 'side-post' and the 'regions' array to ('side-post', 'side-pre').

===Adding a fake block to each pagelayout in your theme:===
(add following function to theme/yourtheme/lib.php)
<code php>
function theme_yourtheme_get_html_for_settings(renderer_base $output, moodle_page $page) function:

$bc = new block_contents();
$bc->title = 'fake title';
$bc->attributes['class'] = 'fakeblock';
$bc->content = 'fake content';
$page->blocks->add_fake_block($bc, 'side-pre');

</code>

== Instructions ==

Have you provided a 'readme' file containing: Install instructions, un-install instructions, version history and contact details for when things go wrong.

== License ==

Is all code GPLv3 (or compatible) licensed?

== Maturity ==

Have you correctly stated the maturity of the theme in the '[https://docs.moodle.org/dev/version.php version.php]' file? This gives users and idea of how stable the code is.

== Quiz 'secure' pop-up ==

When a quiz is set to [[:en:Quiz_settings#Extra_restrictions_on_attempts|Full screen pop-up with some JavaScript security]] then the page uses a special 'secure' layout template that should have minimal headers. NO footer and NO external links whatsoever.
See Clean theme secure.php [https://github.com/moodle/moodle/blob/master/theme/clean/layout/secure.php]

== Readable fonts ==

Are the fonts you have chosen readable? Will they be difficult to read on small devices?

== Right-to-left languages ==

In languages like Hebrew or Farsi, lots of things that you made left-aligned probably need to be right-aligned instead. Moodle adds .dir-rtl or .dir-ltr class to the body element, which you can use in CSS rules.

== Responsive ==

Have you tested your theme for responsiveness on small devices? Try resizing the browser window and see how it reacts.

== Theme developer mode ==

When 'Theme developer mode' is 'on', all of the CSS files are sent individually. When it is 'off', they are all combined together. This can lead to some issues. Check that your theme works with 'Theme designer mode off'.

== ... please add more things here in alphabetical order ... ==

Theme checklist

2016-07-14T18:44:18Z

Tqr: /* Quiz 'secure' pop-up */

{{Template:Themes}}So, you think your theme is finished? Well, Moodle is a big complex system and there are lots of obscure corners that you might not know about. This page lists lots of things that you might have missed when working on your theme. To be sure your theme is really complete, you need to check these out.

== Accessible colours ==

Are the colours you have chosen accessible? Is there a reasonable contrast difference between them?

== All the different forms of the front page ==

Depending on how many courses there are in your Moodle site, and how many of them the current user is enrolled in, the [[:en:Front_page|front page]] looks different. Have you tested all the different ways it can look?

== Big report tables ==

The [[:en:Gradebook|grader report]], and other similar reports like the quiz reports, are very big tables that don't fit on one screen. How does your theme cope. Is it easy for the teacher to scroll sideways to see all the data?

== Clean install ==

Have you installed and un-installed the theme on a 'pure' installation? That is an installation with no other contributed plugins. This allows you to check for unintentional dependencies.

== Code checker ==

[https://moodle.org/plugins/view.php?plugin=local_codechecker Code checker] checks your code against the Moodle [https://docs.moodle.org/dev/Coding coding standards]. It is a useful tool for spotting issues and making your code readable to all who are familiar with the core code. Do not take all messages literally, use your common sense and make changes that are sensible.

== Dependencies ==

Have you specified the correct dependencies for both parent themes and Moodle in the '[https://docs.moodle.org/dev/version.php version.php]' file?

== Fake blocks ==

While you are looking at the quiz, pay attention to the [[:en:Using_Quiz|Quiz navigation block]]. This is not a normal block that teachers or admins can add or remove, it is a 'Fake block' that looks like any other block but is part of the Moodle UI. Are you happy with where it appears, and how it looks?

Other parts of Moodle that use fake blocks are the [[:en:Lesson_module|Lesson activity]] and [[:en:Calendar|the calendar UI]].

Fake blocks are attached to the first region or the 'defaultregion' in the 'regions' array for the 'layout' in the 'layouts' array in the 'config.php' file. So if the order is ('side-pre', 'side-post') and you want fake blocks to be in 'side-post' change the 'defaultregion' to 'side-post' and the 'regions' array to ('side-post', 'side-pre').

===Adding a fake block to each pagelayout in your theme:===
(add following function to theme/yourtheme/lib.php)
<code php>
function theme_yourtheme_get_html_for_settings(renderer_base $output, moodle_page $page) function:

$bc = new block_contents();
$bc->title = 'fake title';
$bc->attributes['class'] = 'fakeblock';
$bc->content = 'fake content';
$page->blocks->add_fake_block($bc, 'side-pre');

</code>

== Instructions ==

Have you provided a 'readme' file containing: Install instructions, un-install instructions, version history and contact details for when things go wrong.

== License ==

Is all code GPLv3 (or compatible) licensed?

== Maturity ==

Have you correctly stated the maturity of the theme in the '[https://docs.moodle.org/dev/version.php version.php]' file? This gives users and idea of how stable the code is.

== Quiz 'secure' pop-up ==

When a quiz is set to [[:en:Quiz_settings#Extra_restrictions_on_attempts|Full screen pop-up with some JavaScript security]] then the page uses a special 'secure' layout template that should have minimal headers and NO external links whatsoever.
See Clean theme secure.php [https://github.com/moodle/moodle/blob/master/theme/clean/layout/secure.php]

== Readable fonts ==

Are the fonts you have chosen readable? Will they be difficult to read on small devices?

== Right-to-left languages ==

In languages like Hebrew or Farsi, lots of things that you made left-aligned probably need to be right-aligned instead. Moodle adds .dir-rtl or .dir-ltr class to the body element, which you can use in CSS rules.

== Responsive ==

Have you tested your theme for responsiveness on small devices? Try resizing the browser window and see how it reacts.

== Theme developer mode ==

When 'Theme developer mode' is 'on', all of the CSS files are sent individually. When it is 'off', they are all combined together. This can lead to some issues. Check that your theme works with 'Theme designer mode off'.

== ... please add more things here in alphabetical order ... ==

Theme And Navigation Project 3.2

2016-06-30T19:49:39Z

Tqr: /* Every page with settings should use a consistent, recognisable ui element to get to the settings */

{{Infobox Project
|name = Theme And Navigation Project 3.2
|state = Starting
|tracker = MDL-55070
|discussion = https://moodle.org/mod/forum/discuss.php?d=335638
|assignee = [[User:Damyon Wiese]]
}}

This page is dedicated to a set of changes for 3.2 all relating to the theme, and navigation in Moodle.

The requirements for the new theme are:
* use a CSS framework that will be supported upstream for a long time
* testing framework needs to be theme independent
* make the navigation simpler and more intuitive
* introduce quick navigation from course to course or section to section
* promote the content of each page rather than the peripheral sections (blocks)
* the visual design of Moodle should look distinct from older versions
* every page with settings should use a consistent, recognisable UI element to get to the settings
* add lots of settings to the new theme so it can be used for many sites without installing a child-theme

More details about each requirement follow:

= Use a CSS framework that will be supported upstream for a long time =
* Users affected: theme designers
* The problem: bootstrap 2 is unsupported
* The proposed solution: create a new theme based on Bootstrap 4
* Criteria for success: New moodle theme using a supported CSS framework with long term support that includes features for RTL and Accessibility and is popular with theme designers, the new theme should show proper styling for all pages
* MDL-55071

= Testing framework needs to be theme independent =
* Users affected: developers
* The problem: feature files are written assuming the theme will be “clean”
* The proposed solution: Theme specific steps need to be identified and the theme should form part of the behat context. Different step implementations should be available for different themes
* Criteria for success: You should be able to specify which theme to run behat with and all tests should pass
* MDL-55072

= Navigation is not intuitive =
* Users affected: new moodle users, experienced moodle users
* The problem: navigation is a complex tree with inconsistent structure
* The proposed solution: Only show the path to the current node in the navigation, and it’s siblings as a flat list.
* Criteria for success: It is easier to determine your location in the navigation tree, it is easier to find pages related to the current page
* MDL-55073

= Intuitively navigate from course to course or section to section =
* Users affected: new moodle users, experienced moodle users
* The problem: If the navigation tree is flattened, it is not possible to change between courses without leaving the course and entering a new one
* The proposed solution: Show a drop down menu for each item in the navbar
* Criteria for success: It is intuitive to quickly jump between courses and sections using the navbar
* MDL-55074

= Promote the content of each page rather than the peripheral sections (blocks) =
* Users affected: new moodle users, experienced moodle users
* The problem: blocks displayed around the content compete for attention and real-estate in the page
* The proposed solution: Move the blocks regions into an expandable menu
* Criteria for success: the content of each page should be the first thing that grabs your focus, blocks should still be discoverable and usable if needed
* MDL-55075

= The visual design of Moodle should look distinct from older versions =
* Users affected: new moodle users, themers
* The problem: We have not updated the look of the default theme in several years
* The proposed solution: Implement some new distinct styling in the new Moodle theme
* Criteria for success: The new moodle theme should look visually distinct. There should only be a minimum amount of custom styling for themers to override when extending this theme
* MDL-55076

= Every page with settings should use a consistent, recognisable UI element to get to the settings =
* Users affected: all moodle users
* The problem: Settings pages are buried in the navigation tree in inconsistent locations
* The proposed solution: Create a settings navigation renderable that shows a gear icon on the top right of the page and takes you straight to the settings page. Update all pages with settings in moodle to use the new thing.
* Criteria for success: All pages with settings in Moodle should show a gear icon which will take you to the settings page when clicked.
* MDL-55077

= Add lots of settings to the new theme so it can be used for many sites without installing a child-theme =
* Users affected: new moodle users
* The problem: Installing themes is hard/not possible in some environments. The new theme should be customisable enough to make it usable just by changing settings.
* The proposed solution: Review settings provided by community themes and add the common ones to this new theme.
* Criteria for success: Colours, fonts, logos should be customisable as well as additional settings supported by most community themes.
* MDL-55078

Theme And Navigation Project 3.2

2016-06-30T19:44:37Z

Tqr:

{{Infobox Project
|name = Theme And Navigation Project 3.2
|state = Starting
|tracker = MDL-55070
|discussion = https://moodle.org/mod/forum/discuss.php?d=335638
|assignee = [[User:Damyon Wiese]]
}}

This page is dedicated to a set of changes for 3.2 all relating to the theme, and navigation in Moodle.

The requirements for the new theme are:
* use a CSS framework that will be supported upstream for a long time
* testing framework needs to be theme independent
* make the navigation simpler and more intuitive
* introduce quick navigation from course to course or section to section
* promote the content of each page rather than the peripheral sections (blocks)
* the visual design of Moodle should look distinct from older versions
* every page with settings should use a consistent, recognisable UI element to get to the settings
* add lots of settings to the new theme so it can be used for many sites without installing a child-theme

More details about each requirement follow:

= Use a CSS framework that will be supported upstream for a long time =
* Users affected: theme designers
* The problem: bootstrap 2 is unsupported
* The proposed solution: create a new theme based on Bootstrap 4
* Criteria for success: New moodle theme using a supported CSS framework with long term support that includes features for RTL and Accessibility and is popular with theme designers, the new theme should show proper styling for all pages
* MDL-55071

= Testing framework needs to be theme independent =
* Users affected: developers
* The problem: feature files are written assuming the theme will be “clean”
* The proposed solution: Theme specific steps need to be identified and the theme should form part of the behat context. Different step implementations should be available for different themes
* Criteria for success: You should be able to specify which theme to run behat with and all tests should pass
* MDL-55072

= Navigation is not intuitive =
* Users affected: new moodle users, experienced moodle users
* The problem: navigation is a complex tree with inconsistent structure
* The proposed solution: Only show the path to the current node in the navigation, and it’s siblings as a flat list.
* Criteria for success: It is easier to determine your location in the navigation tree, it is easier to find pages related to the current page
* MDL-55073

= Intuitively navigate from course to course or section to section =
* Users affected: new moodle users, experienced moodle users
* The problem: If the navigation tree is flattened, it is not possible to change between courses without leaving the course and entering a new one
* The proposed solution: Show a drop down menu for each item in the navbar
* Criteria for success: It is intuitive to quickly jump between courses and sections using the navbar
* MDL-55074

= Promote the content of each page rather than the peripheral sections (blocks) =
* Users affected: new moodle users, experienced moodle users
* The problem: blocks displayed around the content compete for attention and real-estate in the page
* The proposed solution: Move the blocks regions into an expandable menu
* Criteria for success: the content of each page should be the first thing that grabs your focus, blocks should still be discoverable and usable if needed
* MDL-55075

= The visual design of Moodle should look distinct from older versions =
* Users affected: new moodle users, themers
* The problem: We have not updated the look of the default theme in several years
* The proposed solution: Implement some new distinct styling in the new Moodle theme
* Criteria for success: The new moodle theme should look visually distinct. There should only be a minimum amount of custom styling for themers to override when extending this theme
* MDL-55076

= Every page with settings should use a consistent, recognisable ui element to get to the settings =
* Users affected: all moodle users
* The problem: Settings pages are buried in the navigation tree in inconsistent locations
* The proposed solution: Create a settings navigation renderable that shows a gear icon on the top right of the page and takes you straight to the settings page. Update all pages with settings in moodle to use the new thing.
* Criteria for success: All pages with settings in Moodle should show a gear icon which will take you to the settings page when clicked.
* MDL-55077

= Add lots of settings to the new theme so it can be used for many sites without installing a child-theme =
* Users affected: new moodle users
* The problem: Installing themes is hard/not possible in some environments. The new theme should be customisable enough to make it usable just by changing settings.
* The proposed solution: Review settings provided by community themes and add the common ones to this new theme.
* Criteria for success: Colours, fonts, logos should be customisable as well as additional settings supported by most community themes.
* MDL-55078

Templates

2016-06-06T23:56:49Z

Tqr: /* Templates */

{{Moodle 2.9}}

= Templates =

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

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

So - putting this all together:

recipe.mustache
<code xml>
<h3>{{recipename}}</h3>
<p>{{description}}</p>
<h4>Ingredients</h4>
<ol>
{{#ingredients}}
<li>{{.}}</li>
{{/ingredients}}
</ol>
<h4>Steps</h4>
<ol>
{{#steps}}
<li>{{{.}}}</li>
{{/steps}}
</ol>
{{ > ratethisrecipe }}
</code>

When given this data:
<code javascript>
{
recipename: "Cheese sandwich",
description: "Who doesn't like a good cheese sandwich?",
ingredients: ["bread", "cheese", "butter"],
steps: ["<p>Step 1 is to spread the butter on the bread</p>", "<p>Step 2 is to put the cheese "in" the bread (not on top, or underneath)</p>"]
}
</code>

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

More info - there are much clearer explanations of templates on the [http://mustache.github.io/mustache.5.html Mustache] website. Try reading those pages "before" posting on stack overflow :) .

=== Blocks (Moodle 3.0 onwards) ===
Blocks are a feature of Mustache that deserves a special mention. The are used as a form of inheritance - and are crucial to building a library of re-usable templates. To use make use of "blocks" you define a parent template with replaceable sections. Each of those sections is marked with a "blocks" tag like this (A blocks tag looks like a regular tag, but the variable name is preceded with $):

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

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

<code xml>
{{< section}}
{{$sectionheading}}Latest News{{/sectionheading}}
{{$content}}Nothing happened today - sorry!{{/content}}
{{/section}}
</code>

Notice that when I include a template and I want to make use of blocks - the include tag points the other way:
<code xml>
{{< section}}
</code>
Not
<code xml>
{{> section}}
</code>

Blocks support looping and many other cool things - for more info see https://github.com/bobthecow/mustache.php/wiki/BLOCKS-pragma

== Where do I put my templates? ==

Templates go in the <componentdir>/templates folder and must have a .mustache file extension. When loading templates the template name is <componentname>/<filename> (no file extension).

So "mod_lesson/timer" would load the template at mod/lesson/templates/timer.mustache.

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

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

Rendering a template from javascript is fairly easy. There is a new AMD module that can load/cache and render a template for you.

<code javascript>
// This is AMD code for loading the "core/templates" module. see [Javascript Modules].
require(['core/templates'], function(templates) {

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

// This will call the function to load and render our template.
var promise = templates.render('block_looneytunes/profile', context);

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

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

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

// Sometimes things fail
promise.fail(function(ex) {
// Deal with this exception (I recommend core/notify exception function for this).
});
});
</code>

Under the hood, this did many clever things for us. It loaded the template via an ajax call if it was not cached. It found any missing lang strings in the template and loaded them in a single ajax request, it split the JS from the HTML and returned us both in easy to use way. Read on for how to nicely deal with the javascript parameter.

Note: with some nice chaining and sugar, we can shorten the above example quite a bit:
<code javascript>
require(['core/templates', 'core/notification'], function(templates, notification) {
var context = { name: 'Tweety bird', intelligence: 2 };
templates.render('block_looneytunes/profile', context)
.done(doneCallback)
.fail(notification.exception);
});
</code>

== What if a template contains javascript? ==

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

Example
profile.mustache
<code xml>
<div id="profile">
<p>Name: {{name}}</p>
<p>Intelligence: {{intelligence}}</p>
</div>
{{#js}}
require('jquery', function($) {
// Effects! Can we have "blink"?
$('#profile').slideDown();
});
{{/js}}
</code>

If this template is rendered by PHP, the javascript is separated from the HTML, and is appended to a special section in the footer of the page "after" requirejs has loaded. This provides the optimal page loading speed. If the template is rendered by javascript, the javascript source will be passed to the "done" handler from the promise. Then, when the "done" handler has added the template to the DOM, it can call
<code javascript>templates.runTemplateJS(javascript);</code>
which will run the javascript (by creating a new script tag and appending it to the page head).

== What other helpers can I use? ==

=== {{# str }} ===

There is a string helper for loading language strings.

<code xml>
{{# str }} helloworld, mod_greeting {{/ str }}
</code>

The first 2 parameters are the string id and the component name. So this is effectively Mustache variant of <code>get_string('helloworld', 'mod_greeting')</code>.

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

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

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

Variable tags are allowed to define the value of the <code>$a</code> placeholder:

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

For strings that accept complex placeholder, see the following section.

=== {{# quote }} ===

As shown in the previous section, the <code>{{# str }}</code> helper may need complex data structures passed as the value of the <code>$a</code> placeholder. You can use a JSON object syntax in that case:

<code xml>
{{# str }} iscool, mod_cool, { "firstname": "David", "lastname": "Beckham" } {{/ str }}
</code>

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

<code xml>
{{! DO NOT DO THIS !}}
{{# str }} iscool, mod_cool, { "firstname": "{{ firstname }}", "lastname": "{{ lastname }}" } {{/ str }}
</code>

There is a potential problem though. If the variable tag <code>{{ firstname }}</code> or <code>{{ lastname }}</code> evaluates to a string containing the double quote character, that will break the JSON syntax. We need to escape the double quotes potentially appearing in the variable tags. For this, use the <code>{{# quote }}</code> helper:

<code xml>
{{! This is OK !}}
{{# str }} iscool, mod_cool, { "firstname": {{# quote }}{{ firstname }}{{/ quote }}, "lastname": {{# quote }}{{ lastname }}{{/ quote }} } {{/ str }}
</code>

See MDL-52136 for details.
=== {{# pix }} ===

There is a pix icon helper for generating pix icon tags.

<code xml>
{{# pix }} t/edit, core, Edit David Beckham {{/ pix }}
</code>

The first 2 parameters are the string id and the component name, the rest is the alt text for the image.

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

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

== How do templates work with renderers? ==

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

So - I have "some" data in my renderable and some logic and html generation in my render method for that renderable - how do I refactor this to use a template?

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

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

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

return $data;
}
</code>

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

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

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

== Should I document my templates? ==

Yes!!!! Theme designers need to know the limits of what they can expect to change without breaking anything. As a further benefit - your beautiful new template can be displayed in the "Template Library" tool shipped with Moodle. In order to provide nice documentation and examples for the Template Library, you should follow these conventions when documenting your template.

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

The template library will look for a mustache comment that contains this special marker as the documentation to display, and the source of an example context.

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

==== Useful things to include in the documentation for a template ====
===== Classes required for JS =====
This is a list of classes that are used by the javascript for this template. If removing a class from an element in the template will break the javascript, list it here.

===== Data attributes required for JS =====
This is a list of data attributes (e.g. data-enhance="true") that are used by the javascript for this template. If removing a data attribute from an element in the template will break the javascript, list it here.

===== Context variables required for this template =====
This is a description of the data that may be contained in the context that is passed to the template. Be explicit and document every attribute.

===== Example context (json) =====
The Template Library will look for this data in your documentation comment as it allows it to render a "preview" of the template right in the Template Library. This is useful for theme designers to test all the available templates in their new theme to make sure they look nice in a new theme. It is also useful to make sure the template responds to different screen sizes, languages and devices. The format is a json encoded object that is passed directly into the render method for this template.

==== A full example ====
lib/templates/pix_icon.mustache
<pre>
{{!
This file is part of Moodle - http://moodle.org/

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

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

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

Moodle pix_icon template.

The purpose of this template is to render a pix_icon.

Classes required for JS:
* none

Data attributes required for JS:
* none

Context variables required for this template:
* attributes Array of name / value pairs.

Example context (json):
{
"attributes": [
{ "name": "src", "value": "http://moodle.com/wp-content/themes/moodle/images/logo-hat2.png" },
{ "name": "class", "value": "iconsmall" }
]
}

}}
<img {{#attributes}}{{name}}="{{value}}" {{/attributes}}/>
</pre>

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

=== Include GPL at the top of each template ===

Templates are a form of code and it is appropriate to license them like any other code.

===Include a documentation comment for each template===

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

===Use data-attributes for JS hooks===

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

===Avoid custom CSS for templates===

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

===Re-use core templates as much as possible===

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

===Do use the CSS framework classes directly in the templates===

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

===Avoid IDs for styling or javascript===

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

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

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

===Follow CSS coding style===

https://docs.moodle.org/dev/CSS_coding_style

Use hyphens as word-separators for class names.
Use lower case class names.

===Wrap each template in one node with a classname that matches the template name===

Generate a class name by combining the component and template names and separating words with underscore.

e.g.

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

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

===Iterating over php arrays in a mustache template===

Mustache treats hashes and arrays differently because of cross language compatibility
In php arrays and hashes are the same, but mustache treats them differently
It decides a php array is a hash and will not iterate over it if it is non 0 indexed and/or has a gap in the key numbers
so in short
you need to
<code php>
$datafortemplate->mylist = array_values($myarraywithnonnumerickeys)
</code>
you could also use
<code php>
$datafortemplate->mylist = new ArrayIterator($myarraywithnonnumerickeys);
</code>
BUT this fails when $myarraywithnonnumerickeys is empty and you try to use
<code html5>
{{#mylist}}
with an array iterator if mylist is empty this block will not run
{{/mylist}}
{{^mylist}}
with an array iterator mylist will not run this block either because it is not quite empty
{{/mylist}}
</code>

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

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

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

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

First we can create a basic template to get the general structure down, let's call it tabs. Here's what it might look like:
<pre>
<div id="{{ uniqid }}-tab-container">
<ul role="tablist" class="nav nav-tabs">
{{# tabs }}
<li role="tab"
data-target="{{ uniqid }}-{{ id }}"
data-selected-class="active"
aria-controls="{{ uniqid }}-{{ id }}"
aria-selected="false" tabindex="-1">

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

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

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

The template requires a context that looks something like:
<pre>
{
"tabs": [
{"id":"tab1","name":"Tab 1","content":"This is tab 1 content <a href=\"#\">test</a>"},
{"id":"tab2","name":"Tab 2","content":"This is tab 2 content <a href=\"#\">test</a>"},
{"id":"tab3","name":"Tab 3","content":"This is tab 3 content <a href=\"#\">test</a>"}
]
}
</pre>

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

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

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

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

Here's what the page might look like:
<pre>
<html>
<header><title>User Profile</title></header>
<body>
{{< core/tabs }}
</body>
</html>
</pre>

That looks pretty simple! The only problem is, how do I get my content there? I would have to supply a context like this in order to display the tabs I want:
<pre>
{
"tabs": [
{"id":"tab1","name":"Name","content":"Your name is Mr. Test User."},
{"id":"tab2","name":"Email","content":"Your email is testuser@example.com"},
]
}
</pre>

Let's assume that the context for this page doesn't match what the tabs template is expecting though (as will be the case most of the time). Let's assume the tabs template is being rendered with this context:
<pre>
{
"name":"Mr. Test User",
"email":"testuser@example.com"
}
</pre>

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

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

Let's have another go at that template, this time leverging blocks:
<pre>
<div id="{{ uniqid }}-tab-container">
{{$ tabheader }}
<ul role="tablist" class="nav nav-tabs">
{{$ tablist }}
{{# tabs }}
<li role="tab"
data-target="{{ uniqid }}-{{ id }}"
data-selected-class="active"
aria-controls="{{ uniqid }}-{{ id }}"
aria-selected="false" tabindex="-1">

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

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

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

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

Now let's see what using this template looks like for your User Profile page:
<pre>
<html>
<header><title>User Profile</title></header>
<body>
{{> core/tabs }}
{{$ tablist }}
<li role="tab"
data-target="{{ uniqid }}-tab1"
data-selected-class="active"
aria-controls="{{ uniqid }}-tab1"
aria-selected="false" tabindex="-1">

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Cool, so let's see what that looks like in our example now:
<pre>
<html>
<header><title>User Profile</title></header>
<body>
{{> core/tabs }}
{{$ tablist }}
{{> core/tab_header_item }}
{{$ tabname }}Name{{/ tabname }}
{{/ core/tab_header_item }}
{{> core/tab_header_item }}
{{$ tabname }}Email{{/ tabname }}
{{/ core/tab_header_item }}
{{/ tablist }}
{{$ tabcontent }}
{{> core/tab_content_item }}
{{$ tabpanelcontent }}Your name is {{ name }}.{{/ tabpanelcontent }}
{{/ core/tab_content_item }}
{{> core/tab_content_item }}
{{$ tabpanelcontent }}Your email address is {{ email }}.{{/ tabpanelcontent }}
{{/ core/tab_content_item }}
{{/ tabcontent }}
{{/ core/tabs }}
</body>
</html>
</pre>

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

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

More theme

2015-11-11T01:05:20Z

Tqr: Created page with "Place holder for More theme documentation."

Place holder for More theme documentation.

Themes 2.2 how to clone a Moodle 2.2 theme

2015-11-11T01:01:16Z

Tqr:

{{Template:Themes}}{{Moodle 2.2}}This document describes how to clone Afterburner theme so that you can build on this to create a theme of your own. It assumes you have some understanding of how themes work within Moodle 2.2, as well as a basic understanding of HTML and CSS. Also, because of the rapid development within Moodle, resulting in a number of versions available namely 2.0.x, 2.1.x, 2.2.x, 2.3.x and soon to be announced Moodle 2.4.x, it is important to understand that this tutorial is only valid for Moodle 2.2 and 2.3 themes. For more recent themes based on Clean and More, please check out the README.txt [https://github.com/moodle/moodle/blob/master/theme/clean/README.txt] file contained in the Clean folder.

==Getting started==

From your Moodle '''theme''' directory '''right click''' on '''afterburner''' and then '''''copy''' and '''paste''''' back into your Moodle '''theme''' directory. You should now have a folder called '''Copy of afterburner'''. If you '''right click''' this folder you are given the option to '''Rename''' it. So rename this folder to '''mytheme''' (or to whatever name you want to call your '''cloned''' theme). '''It is important to use only lower case letters and underscores'''.

If you open the '''mytheme''' directory you will find several directories, sub-directories and files within it.

These are:
; config.php : Where all the theme configurations are made.
; lib.php : Where all the functions for the themes settings are found.
; renderers.php : Where all the renderers for this theme are found.
; settings.php : Where all the setting for this theme are created.
; version.php : Where the version number and plugin componant information is kept.
; /lang/ : This directory contains all language sub-directories for other languages if and when you want to add them.
; /lang/en/ : This sub-directory contains your language files, in this case ''English''.
; /lang/en/theme_afterburner.php : This file contains all the language strings for your theme.
; /layout/ : This directory contains all the layout files for this theme.
; /layout/default.php : Layout file for front page and general pages combined.
; /layout/embedded.php : Layout file for embedded pages.
; /style/ : This directory contains all the CSS files for this theme.
; /pix/ : This directory contains a screen shot of this theme as well as a favicon and any images used in the theme.
; /pix_core/ :
; /pix_plugins/ :

==Renaming Elements==

The problem when '''cloning''' a theme is that ''you need to rename all those instances where the old theme name occurs'', in this case '''afterburner'''. The first place to look is '''config.php''', where you you need to define the name of your theme. So change
<code php>
$THEME->name = 'afterburner';
</code>
to the name of your new theme.

You will need to change the name of '''lang/en/theme_afterburner.php'''. This file, as well as needing to be renamed, also needs some of its content renaming too. So before you forget, '''right click''' on this file and '''rename''' it to the name of your new theme before you open it.

=== Language Strings ===

When you open '''theme_mytheme.php''' the first thing you will see are the '''credits''' for the theme.
<code php>
/**
* Strings for component 'theme_afterburner', language 'en'
*
* @package theme_afterburner
* @copyright 2011
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>
Here you will need to change the reference from '''afterburner''' to '''mytheme''', you can leave the rest of this as it is.

The next things you will find in this file are what are known as the '''language strings'''. These are all the customised '''''words'' or ''phrases''''' used in this theme.

<code php>
$string['configtitle'] = 'Afterburner Custom Settings';
$string['pluginname'] = 'Afterburner';
$string['region-side-post'] = 'Right';
$string['region-side-pre'] = 'Left';
...
...
</code>

In the $string section above, you will need to change ALL instances of the old theme name Afterburner to your new theme name. In this next section alone you will find seven instances of the name Afterburner to rename.

The only section you may want to change completely is the '''choosereadme'''. You could write something like this instead.

<code php>
$string['choosereadme'] = 'My theme is a customised Moodle theme
based on the Moodle 2.2 Afterburner theme by Mary Evans.';
</code>

When you have finished all the changes in this file save it and close it.

== Custom Settings ==

Now that you have had a chance to search for and change all the instances in the language file, you will be more familiar for what you are looking for when you begin the mamoth task of going through the files associated with the Custom Settings for the Afterburner theme.
There are three files to check through. These are...
;settings.php
;renderers.php
;lib.php

But do be sure to rename ALL the instances in these three files, as there are quite a number of them.

== Version ==

The last file to change is version.php, here you will find the following...

<code php>
/**
* Theme version info
*
* @package theme
* @subpackage afterburner
* @copyright 2011 Mary Evans
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

defined('MOODLE_INTERNAL') || die;

$plugin->version = 2011082400; // The current module version (Date: YYYYMMDDXX)
$plugin->requires = 2011081700; // Requires this Moodle version
$plugin->component = 'theme_afterburner'; // Full name of the plugin (used for diagnostics)
</code>
Just as long as you change the instance of afterburner to your new theme's name you will be almost ready to try out this theme in your Moodle 2.2. installation.

== CSS Stylesheets ==

If you want this theme to use the same CSS rules from the Afterburner theme, then you need to make one more change to your new theme's config.php file.

First you will need to ADD afterburner to the parent theme array like this...

<code php>
$THEME->parents = array('afterburner', 'base');
</code>

Next you can delete all these style sheets from this list bar one file...that is afterburner_settings.css. This is important as your theme will need to rely on this stylesheet for your custom settings. So delete this list...

<code php>
$THEME->sheets = array(
'afterburner_layout', /** Must come first: Page layout **/
'afterburner_styles', /** Must come second: default styles **/
'afterburner_menu',
'afterburner_blocks',
'afterburner_mod',
'afterburner_calendar',
'afterburner_dock',
'afterburner_settings',
'rtl'
);
</code>

but leave afterburner_settings.css which you could just rename to settings.css.

<code php>
$THEME->sheets = array('settings');
</code>

You will then be able to delete all the stylesheets from your new theme's style directory leaving just editor.css and afterburner_settings.css which you will also need to rename to settings.css.

So whenever you need to change the CSS for your new theme, you can do this in your theme's settings page, by going to Site Administration > Appearance > Themes > and choose your new theme from those names listed.

== Cut to the chase ==

Patience is a virtue! :)

If you have only just got here and not read the above Tutorial then you have missed the best part. If on the other hand you have finished this tutorial, then please let me have some feedback.

If after reading this you run into problems, and need more help, then do please ask in the Themes Forum, [http://moodle.org/mod/forum/view.php?id=46] where you will find lots of help with your new theme project.

--[[User:Mary Evans 2|Mary Evans 2]] 06:03, 7 April 2012 (WST)

Themes 2.2 how to clone a Moodle 2.2 theme

2015-11-11T00:57:59Z

Tqr:

{{Template:Themes}}{{Moodle 2.2}}This document describes how to clone Afterburner theme so that you can build on this to create a theme of your own. It assumes you have some understanding of how themes work within Moodle 2.2, as well as a basic understanding of HTML and CSS. Also, because of the rapid development within Moodle, resulting in a number of versions available namely 2.0.x, 2.1.x, 2.2.x, 2.3.x and soon to be announced Moodle 2.4.x, it is important to understand that this tutorial is only valid for Moodle 2.2 and 2.3 themes. For more recent themes based on Clean and More, please check out the [[ReadMe|https://github.com/moodle/moodle/blob/master/theme/clean/README.txt]] file contained in the Clean folder.

==Getting started==

From your Moodle '''theme''' directory '''right click''' on '''afterburner''' and then '''''copy''' and '''paste''''' back into your Moodle '''theme''' directory. You should now have a folder called '''Copy of afterburner'''. If you '''right click''' this folder you are given the option to '''Rename''' it. So rename this folder to '''mytheme''' (or to whatever name you want to call your '''cloned''' theme). '''It is important to use only lower case letters and underscores'''.

If you open the '''mytheme''' directory you will find several directories, sub-directories and files within it.

These are:
; config.php : Where all the theme configurations are made.
; lib.php : Where all the functions for the themes settings are found.
; renderers.php : Where all the renderers for this theme are found.
; settings.php : Where all the setting for this theme are created.
; version.php : Where the version number and plugin componant information is kept.
; /lang/ : This directory contains all language sub-directories for other languages if and when you want to add them.
; /lang/en/ : This sub-directory contains your language files, in this case ''English''.
; /lang/en/theme_afterburner.php : This file contains all the language strings for your theme.
; /layout/ : This directory contains all the layout files for this theme.
; /layout/default.php : Layout file for front page and general pages combined.
; /layout/embedded.php : Layout file for embedded pages.
; /style/ : This directory contains all the CSS files for this theme.
; /pix/ : This directory contains a screen shot of this theme as well as a favicon and any images used in the theme.
; /pix_core/ :
; /pix_plugins/ :

==Renaming Elements==

The problem when '''cloning''' a theme is that ''you need to rename all those instances where the old theme name occurs'', in this case '''afterburner'''. The first place to look is '''config.php''', where you you need to define the name of your theme. So change
<code php>
$THEME->name = 'afterburner';
</code>
to the name of your new theme.

You will need to change the name of '''lang/en/theme_afterburner.php'''. This file, as well as needing to be renamed, also needs some of its content renaming too. So before you forget, '''right click''' on this file and '''rename''' it to the name of your new theme before you open it.

=== Language Strings ===

When you open '''theme_mytheme.php''' the first thing you will see are the '''credits''' for the theme.
<code php>
/**
* Strings for component 'theme_afterburner', language 'en'
*
* @package theme_afterburner
* @copyright 2011
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>
Here you will need to change the reference from '''afterburner''' to '''mytheme''', you can leave the rest of this as it is.

The next things you will find in this file are what are known as the '''language strings'''. These are all the customised '''''words'' or ''phrases''''' used in this theme.

<code php>
$string['configtitle'] = 'Afterburner Custom Settings';
$string['pluginname'] = 'Afterburner';
$string['region-side-post'] = 'Right';
$string['region-side-pre'] = 'Left';
...
...
</code>

In the $string section above, you will need to change ALL instances of the old theme name Afterburner to your new theme name. In this next section alone you will find seven instances of the name Afterburner to rename.

The only section you may want to change completely is the '''choosereadme'''. You could write something like this instead.

<code php>
$string['choosereadme'] = 'My theme is a customised Moodle theme
based on the Moodle 2.2 Afterburner theme by Mary Evans.';
</code>

When you have finished all the changes in this file save it and close it.

== Custom Settings ==

Now that you have had a chance to search for and change all the instances in the language file, you will be more familiar for what you are looking for when you begin the mamoth task of going through the files associated with the Custom Settings for the Afterburner theme.
There are three files to check through. These are...
;settings.php
;renderers.php
;lib.php

But do be sure to rename ALL the instances in these three files, as there are quite a number of them.

== Version ==

The last file to change is version.php, here you will find the following...

<code php>
/**
* Theme version info
*
* @package theme
* @subpackage afterburner
* @copyright 2011 Mary Evans
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

defined('MOODLE_INTERNAL') || die;

$plugin->version = 2011082400; // The current module version (Date: YYYYMMDDXX)
$plugin->requires = 2011081700; // Requires this Moodle version
$plugin->component = 'theme_afterburner'; // Full name of the plugin (used for diagnostics)
</code>
Just as long as you change the instance of afterburner to your new theme's name you will be almost ready to try out this theme in your Moodle 2.2. installation.

== CSS Stylesheets ==

If you want this theme to use the same CSS rules from the Afterburner theme, then you need to make one more change to your new theme's config.php file.

First you will need to ADD afterburner to the parent theme array like this...

<code php>
$THEME->parents = array('afterburner', 'base');
</code>

Next you can delete all these style sheets from this list bar one file...that is afterburner_settings.css. This is important as your theme will need to rely on this stylesheet for your custom settings. So delete this list...

<code php>
$THEME->sheets = array(
'afterburner_layout', /** Must come first: Page layout **/
'afterburner_styles', /** Must come second: default styles **/
'afterburner_menu',
'afterburner_blocks',
'afterburner_mod',
'afterburner_calendar',
'afterburner_dock',
'afterburner_settings',
'rtl'
);
</code>

but leave afterburner_settings.css which you could just rename to settings.css.

<code php>
$THEME->sheets = array('settings');
</code>

You will then be able to delete all the stylesheets from your new theme's style directory leaving just editor.css and afterburner_settings.css which you will also need to rename to settings.css.

So whenever you need to change the CSS for your new theme, you can do this in your theme's settings page, by going to Site Administration > Appearance > Themes > and choose your new theme from those names listed.

== Cut to the chase ==

Patience is a virtue! :)

If you have only just got here and not read the above Tutorial then you have missed the best part. If on the other hand you have finished this tutorial, then please let me have some feedback.

If after reading this you run into problems, and need more help, then do please ask in the Themes Forum, [http://moodle.org/mod/forum/view.php?id=46] where you will find lots of help with your new theme project.

--[[User:Mary Evans 2|Mary Evans 2]] 06:03, 7 April 2012 (WST)

CSS Coding Style

2015-08-30T23:54:25Z

Tqr: /* Values and properties */

{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=275476}}

== Overview ==

=== Scope ===

This document describes style guidelines for developers working on or with Moodle code. It talks purely about the mechanics of code layout and the choices we have made for Moodle.

=== Goals ===

Consistent coding style is important in any development project, and particularly when many developers are involved. A standard style helps to ensure that the code is easier to read and understand, which helps overall quality.

Abstract goals we strive for:

* simplicity
* readability
* tool friendliness

== File naming ==

Within plugins, CSS files are normally named <code>styles.css</code>.

In the theme, files can be named according to the theme designer's wishes but should:

* use lowercase letters and '-' to separate words
* be as succinct as possible
* be descriptive
* be placed in the folder <code>style/</code> for CSS files, or in <code>less/</code> for LESS files.

== Blocks ==

* Each selector should be on its own line. If there is a comma in a selector list, follow it with a line break.
* Property-value pairs should be on their own line, with four spaces of indentation and an ending semicolon.
* The closing brace should use the same level of indentation as the opening selector.
* Leave one line between blocks.

=== Correct ===

<code css>@media only screen and (min-width: 768px) {
.selector-one,
.selector-two {
color: #fff;
background-color: #000;
}
}</code>

=== Incorrect ===

<code css>.selector_one, .selector_two { color: #fff; background-color: #000; }</code>

== Selectors ==

* Always use lower case and underscores or hyphens. Hyphens are preferred.
* Names should be made of simple English words.
* Verbosity is encouraged: names should be as illustrative as is practical to enhance understanding.
* Use [http://css-tricks.com/semantic-class-names/ semantic names]: names tell what this is instead of what should it look like.
* Avoid using IDs. They are far more difficult to maintain and override.
* Do not over-qualify your rules by combining a tagname with a class or ID.

=== Correct ===

<code css>.selector_name {
color: #fff;
}

.selector-name {
color: #fff;
}
</code>

=== Incorrect ===

<code css>div#selName {
color: #fff;
}

.Color-White {
color: #fff;
}</code>

== Properties and values ==

* Should be separated by a colon and a single space, do not minify them.
* Should be lowercase, except for font names and vendor-specific properties.
* For color codes, lowercase is preferred and a shorthand whenever possible.
* For color codes, if you use HSLA or RGBA, always provide a hex fallback.
* Use shorthand (except when overriding styles) for background, border, font, list-style, margin, and padding values.
* Do not use <code>!important</code>. If there is no alternative something is wrong with the CSS you are trying to override.
* Prefixed vendor-specific properties pairs should appear directly before the generic property they refer to.
* Indent vendor prefixed declarations so that their values are aligned

=== Correct ===

<code css>.selector {
color: #fff;
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

.selector {
margin-top: 1px;
color: #f90;
color: hsla(0, 0%, 100%, 1);
}</code>

=== Incorrect ===

<code css>#selector {
color: hsla(0, 0%, 100%, 1);
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

#selector {
margin-top:1px;
color :#ff9900 !important;
}</code>

== Units ==

* Prefer the usage of ''em'' over ''px''.
* Do not use the units ''pt'' or ''rem''. MDL-39934
* Do not declare the unit when the value is 0.

=== Correct ===

<code css>.something {
margin-top: 0;
font-size: 1.25em;
}</code>

=== Incorrect ===

<code css>.something {
margin-top: 0px;
font-size: 1.25rem;
}</code>

== Documentation and comments ==

Following the general [[Coding style]], comments should start with a capital letter and end with a period.

A block-style comment at the top of the CSS file should explain the purpose of the rules in the file.
<code css>
/**
* File base.css.
* Contains base styles for theme basic.
*/
</code>

Block-style comments can also be used to denote a section in a CSS file where all rules pertain to a specific component, view, or functionality:
<code css>
/**
* SCORM Navigation Sidebar.
*/
</code>

Use single-line comments to provide more information to other developers about a single rule or small subset of rules:
<code css>
/* Required because YUI resets add a black border to all tables */
</code>

== Progressive enhancement ==

* Fallbacks should always be provided. For example, provide a background color fallback to background images and gradients.
* Use vendor prefixes only when the supported browser in question does not support the unprefixed property.
* The standard property should come after the vendor-prefixed property.

<code css>.selector {
background-color: #444; /* Fallback for browsers that don't support gradients. */
filter: progid:DXImageTransform.Microsoft.gradient(startColorStr='#444', EndColorStr='#999'); /* IE6-IE9. */
background-image: -webkit-gradient(linear, left top, left bottom, from(#444), to(#999)); /* Safari 4+, Chrome. */
background-image: -webkit-linear-gradient(top, #444, #999); /* Chrome 10+, Safari 5.1+, iOS 5+. */
background-image: -moz-linear-gradient(top, #444, #999); /* Firefox 3.6. */
background-image: -ms-linear-gradient(top, #444, #999); /* IE10. */
background-image: -o-linear-gradient(top, #444, #999); /* Opera 11.10+. */
background-image: linear-gradient(top, #444, #999); /* W3C Standard. */
}</code>

== Browser Hacks ==

* Do not use any browser-specific hacks. Moodle provides a more appropriate way to write browser-specific CSS using classes that are added to the body element. For example:

<code css>
.ie7 .forum-post {
min-height: 1px;
}
</code>

* It is not necessary to include hacks for versions of browsers that Moodle core does not provide support for (e.g. IE6 in Moodle 2, except legacy theme).

== Plugins ==

In plugins, the file names can be:

* styles.css (Recommended)
* styles_<theme name>.css (Not recommended, reserved to 3rd party plugins)

=== Barebones ===

Plugins should define the strict minimum, no text sizes, colours, etc ... those should belong to the theme and not be hardcoded in plugins to allow for easy theming. Of course, this requires Moodle core to provide re-usable classes to style the elements. As Moodle 2.7 has made Bootstrap 2 by default we can start using their classes, but we should make sure that there is a sensible fallback for themes not extending ''bootstrapbase'', such as ''base''.

== Right-to-left ==

Developers always have to pay attention to RTL languages.

=== Selector ===

Always use the selector <code>.dir-rtl</code> to define RTL rules. That class is set on the BODY tag, and it should be placed first if you are combining it with another BODY class. When you are using LESS, encapsulate all the rules in <code>.dir-rtl</code>.

==== Correct ====

<code css>.dir-rtl .something {
margin-left: 0;
margin-right: 1em;
}
.dir-rtl.page-mod-something p {
padding-left: 0;
padding-right: 1em;
}</code>

<code css>.dir-rtl {
&.page-mod-something {
p {
padding-left: 0;
padding-right: 1em;
}
}
.something {
margin-left: 0;
margin-right: 1em;
}
}</code>

==== Incorrect ====

<code css>body.dir-rtl .something {
margin-left: 0;
margin-right: 1em;
}
.page-mod-something.dir-rtl p {
padding-left: 0;
padding-right: 1em;
}</code>

<code css>.dir-rtl {
&.page-mod-something {
p {
padding-left: 0;
padding-right: 1em;
}
}
}
.dir-rtl {
.something {
margin-left: 0;
margin-right: 1em;
}
}</code>

=== Rule placement ===

The RTL rules should be written close to the LTR ones, not in another file. Placing them close to the LTR ones helps (and reminds) the developers to fix both, without the need to search for the existence of RTL rules. If you are using LESS, it is advised to split a huge block into smaller chunks to help locating the corresponding LTR rules.

=== Automatic compliance ===

Whenever possible you should try to avoid writing specific RTL rules. It is more often than one would think possible to have one rule working for both LTR and RTL.

==== Recommended ====

<code css>p {
margin: 0 1em;
}</code>

==== To avoid ====

<code css>p {
margin-left: 1em;
}
.dir-rtl p {
margin-right: 1em;
margin-left: 0;
}</code>

=== What to style ===

RTL rules should only apply to positioning properties, nothing else. And in most cases you will want to revert the LTR rules, to make sure that the rest works as expected.

==== Correct ====

<code css>.something {
text-color: red;
padding-left: 1em;
}
.dir-rtl .something {
padding-left: 0;
padding-right: 1em;
}
</code>

==== Incorrect ====

<code css>
.dir-rtl .something {
text-color: red;
padding-right: 1em;
}
</code>

== LESS ==

[http://lesscss.org/ LESS] works like CSS with some extra features. It should follow the CSS guidelines.

=== Variables ===

* They should use camelCase to follow Bootstrap 2 that is used in core.
* As for CSS selectors, use semantic names: names tell what this is instead of what should it look like.
* As Bootstrap 2 does, do not add the word "Color" to variables for _background_ or _border_ and their derivatives.
* Declaring new variables should be done sparingly, too many variables kill the purpose of using them. If you declare one, try to set its default value from another one.
* Do not declare more variables than necessary. E.g.: If the background color and border color are likely to always be the same, prefer one variable.

==== Correct ====

<code css>@textColor: red;
@wellBackground: #ccc;
@tableBackground: blue;
@blockBackground: @wellBackground;
@calendarGroupEvent: #f90;</code>

==== Incorrect ====

<code css>@text-color: red;
@wellBackground: #ccc;
@tableBackgrounColor: blue;
@blockBackground: #ccc;
@calendarGroupEventBackground: #f90;
@calendarGroupEventBorder: #f90;</code>

=== Selectors ===

* Selectors should be encapsulated rather than duplicated.

==== Correct ====

<code css>div {
.something {
color: red;
a {
color: blue;
}
}
.something-else a {
color: green;
}
}</code>

==== Incorrect ====

<code css>div .something {
color: red;
}
div .something a {
color: blue;
}
div .something-else a {
color: green;
}</code>

=== Values and properties ===

* Colours, font sizes, etc... should never be hardcoded. You should, where possible, use a variable instead.
* The use of 'mixins' is encouraged instead of duplicating values and properties.

==== Correct ====

<code css>.error {
font-size: @fontSizeSmall;
color: @errorText;
padding: 1em;
background-color: @errorBackground;
}
div .form-error {
.error;
}</code>

==== Incorrect ====

<code css>.error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}
div .form-error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}</code>

== Themes Clean and More ==

Clean theme should, where possible, not contain any CSS or LESS content. More theme, in comparison, inherits CSS styles for the logo from Clean theme, but also contains a small amount of LESS as an example for when customising a theme. Both Clean and More inherit fully all the CSS from their parent theme 'Bootstrap Base'.

== Credits ==

This document was drawn from the following sources:

# The [http://codex.wordpress.org/CSS_Coding_Standards WordPress CSS Coding Standards]

== See Also ==

* [[Coding]]
* [[Coding_style|Coding style]]

[[Category:Coding guidelines|CSS Coding style]]

CSS Coding Style

2015-08-30T23:47:48Z

Tqr: /* Themes Clean and More */

{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=275476}}

== Overview ==

=== Scope ===

This document describes style guidelines for developers working on or with Moodle code. It talks purely about the mechanics of code layout and the choices we have made for Moodle.

=== Goals ===

Consistent coding style is important in any development project, and particularly when many developers are involved. A standard style helps to ensure that the code is easier to read and understand, which helps overall quality.

Abstract goals we strive for:

* simplicity
* readability
* tool friendliness

== File naming ==

Within plugins, CSS files are normally named <code>styles.css</code>.

In the theme, files can be named according to the theme designer's wishes but should:

* use lowercase letters and '-' to separate words
* be as succinct as possible
* be descriptive
* be placed in the folder <code>style/</code> for CSS files, or in <code>less/</code> for LESS files.

== Blocks ==

* Each selector should be on its own line. If there is a comma in a selector list, follow it with a line break.
* Property-value pairs should be on their own line, with four spaces of indentation and an ending semicolon.
* The closing brace should use the same level of indentation as the opening selector.
* Leave one line between blocks.

=== Correct ===

<code css>@media only screen and (min-width: 768px) {
.selector-one,
.selector-two {
color: #fff;
background-color: #000;
}
}</code>

=== Incorrect ===

<code css>.selector_one, .selector_two { color: #fff; background-color: #000; }</code>

== Selectors ==

* Always use lower case and underscores or hyphens. Hyphens are preferred.
* Names should be made of simple English words.
* Verbosity is encouraged: names should be as illustrative as is practical to enhance understanding.
* Use [http://css-tricks.com/semantic-class-names/ semantic names]: names tell what this is instead of what should it look like.
* Avoid using IDs. They are far more difficult to maintain and override.
* Do not over-qualify your rules by combining a tagname with a class or ID.

=== Correct ===

<code css>.selector_name {
color: #fff;
}

.selector-name {
color: #fff;
}
</code>

=== Incorrect ===

<code css>div#selName {
color: #fff;
}

.Color-White {
color: #fff;
}</code>

== Properties and values ==

* Should be separated by a colon and a single space, do not minify them.
* Should be lowercase, except for font names and vendor-specific properties.
* For color codes, lowercase is preferred and a shorthand whenever possible.
* For color codes, if you use HSLA or RGBA, always provide a hex fallback.
* Use shorthand (except when overriding styles) for background, border, font, list-style, margin, and padding values.
* Do not use <code>!important</code>. If there is no alternative something is wrong with the CSS you are trying to override.
* Prefixed vendor-specific properties pairs should appear directly before the generic property they refer to.
* Indent vendor prefixed declarations so that their values are aligned

=== Correct ===

<code css>.selector {
color: #fff;
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

.selector {
margin-top: 1px;
color: #f90;
color: hsla(0, 0%, 100%, 1);
}</code>

=== Incorrect ===

<code css>#selector {
color: hsla(0, 0%, 100%, 1);
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

#selector {
margin-top:1px;
color :#ff9900 !important;
}</code>

== Units ==

* Prefer the usage of ''em'' over ''px''.
* Do not use the units ''pt'' or ''rem''. MDL-39934
* Do not declare the unit when the value is 0.

=== Correct ===

<code css>.something {
margin-top: 0;
font-size: 1.25em;
}</code>

=== Incorrect ===

<code css>.something {
margin-top: 0px;
font-size: 1.25rem;
}</code>

== Documentation and comments ==

Following the general [[Coding style]], comments should start with a capital letter and end with a period.

A block-style comment at the top of the CSS file should explain the purpose of the rules in the file.
<code css>
/**
* File base.css.
* Contains base styles for theme basic.
*/
</code>

Block-style comments can also be used to denote a section in a CSS file where all rules pertain to a specific component, view, or functionality:
<code css>
/**
* SCORM Navigation Sidebar.
*/
</code>

Use single-line comments to provide more information to other developers about a single rule or small subset of rules:
<code css>
/* Required because YUI resets add a black border to all tables */
</code>

== Progressive enhancement ==

* Fallbacks should always be provided. For example, provide a background color fallback to background images and gradients.
* Use vendor prefixes only when the supported browser in question does not support the unprefixed property.
* The standard property should come after the vendor-prefixed property.

<code css>.selector {
background-color: #444; /* Fallback for browsers that don't support gradients. */
filter: progid:DXImageTransform.Microsoft.gradient(startColorStr='#444', EndColorStr='#999'); /* IE6-IE9. */
background-image: -webkit-gradient(linear, left top, left bottom, from(#444), to(#999)); /* Safari 4+, Chrome. */
background-image: -webkit-linear-gradient(top, #444, #999); /* Chrome 10+, Safari 5.1+, iOS 5+. */
background-image: -moz-linear-gradient(top, #444, #999); /* Firefox 3.6. */
background-image: -ms-linear-gradient(top, #444, #999); /* IE10. */
background-image: -o-linear-gradient(top, #444, #999); /* Opera 11.10+. */
background-image: linear-gradient(top, #444, #999); /* W3C Standard. */
}</code>

== Browser Hacks ==

* Do not use any browser-specific hacks. Moodle provides a more appropriate way to write browser-specific CSS using classes that are added to the body element. For example:

<code css>
.ie7 .forum-post {
min-height: 1px;
}
</code>

* It is not necessary to include hacks for versions of browsers that Moodle core does not provide support for (e.g. IE6 in Moodle 2, except legacy theme).

== Plugins ==

In plugins, the file names can be:

* styles.css (Recommended)
* styles_<theme name>.css (Not recommended, reserved to 3rd party plugins)

=== Barebones ===

Plugins should define the strict minimum, no text sizes, colours, etc ... those should belong to the theme and not be hardcoded in plugins to allow for easy theming. Of course, this requires Moodle core to provide re-usable classes to style the elements. As Moodle 2.7 has made Bootstrap 2 by default we can start using their classes, but we should make sure that there is a sensible fallback for themes not extending ''bootstrapbase'', such as ''base''.

== Right-to-left ==

Developers always have to pay attention to RTL languages.

=== Selector ===

Always use the selector <code>.dir-rtl</code> to define RTL rules. That class is set on the BODY tag, and it should be placed first if you are combining it with another BODY class. When you are using LESS, encapsulate all the rules in <code>.dir-rtl</code>.

==== Correct ====

<code css>.dir-rtl .something {
margin-left: 0;
margin-right: 1em;
}
.dir-rtl.page-mod-something p {
padding-left: 0;
padding-right: 1em;
}</code>

<code css>.dir-rtl {
&.page-mod-something {
p {
padding-left: 0;
padding-right: 1em;
}
}
.something {
margin-left: 0;
margin-right: 1em;
}
}</code>

==== Incorrect ====

<code css>body.dir-rtl .something {
margin-left: 0;
margin-right: 1em;
}
.page-mod-something.dir-rtl p {
padding-left: 0;
padding-right: 1em;
}</code>

<code css>.dir-rtl {
&.page-mod-something {
p {
padding-left: 0;
padding-right: 1em;
}
}
}
.dir-rtl {
.something {
margin-left: 0;
margin-right: 1em;
}
}</code>

=== Rule placement ===

The RTL rules should be written close to the LTR ones, not in another file. Placing them close to the LTR ones helps (and reminds) the developers to fix both, without the need to search for the existence of RTL rules. If you are using LESS, it is advised to split a huge block into smaller chunks to help locating the corresponding LTR rules.

=== Automatic compliance ===

Whenever possible you should try to avoid writing specific RTL rules. It is more often than one would think possible to have one rule working for both LTR and RTL.

==== Recommended ====

<code css>p {
margin: 0 1em;
}</code>

==== To avoid ====

<code css>p {
margin-left: 1em;
}
.dir-rtl p {
margin-right: 1em;
margin-left: 0;
}</code>

=== What to style ===

RTL rules should only apply to positioning properties, nothing else. And in most cases you will want to revert the LTR rules, to make sure that the rest works as expected.

==== Correct ====

<code css>.something {
text-color: red;
padding-left: 1em;
}
.dir-rtl .something {
padding-left: 0;
padding-right: 1em;
}
</code>

==== Incorrect ====

<code css>
.dir-rtl .something {
text-color: red;
padding-right: 1em;
}
</code>

== LESS ==

[http://lesscss.org/ LESS] works like CSS with some extra features. It should follow the CSS guidelines.

=== Variables ===

* They should use camelCase to follow Bootstrap 2 that is used in core.
* As for CSS selectors, use semantic names: names tell what this is instead of what should it look like.
* As Bootstrap 2 does, do not add the word "Color" to variables for _background_ or _border_ and their derivatives.
* Declaring new variables should be done sparingly, too many variables kill the purpose of using them. If you declare one, try to set its default value from another one.
* Do not declare more variables than necessary. E.g.: If the background color and border color are likely to always be the same, prefer one variable.

==== Correct ====

<code css>@textColor: red;
@wellBackground: #ccc;
@tableBackground: blue;
@blockBackground: @wellBackground;
@calendarGroupEvent: #f90;</code>

==== Incorrect ====

<code css>@text-color: red;
@wellBackground: #ccc;
@tableBackgrounColor: blue;
@blockBackground: #ccc;
@calendarGroupEventBackground: #f90;
@calendarGroupEventBorder: #f90;</code>

=== Selectors ===

* Selectors should be encapsulated rather than duplicated.

==== Correct ====

<code css>div {
.something {
color: red;
a {
color: blue;
}
}
.something-else a {
color: green;
}
}</code>

==== Incorrect ====

<code css>div .something {
color: red;
}
div .something a {
color: blue;
}
div .something-else a {
color: green;
}</code>

=== Values and properties ===

* Colours, font sizes, etc... should never be hardcoded, use a variable instead.
* Use mixins instead of duplicating values and properties.

==== Correct ====

<code css>.error {
font-size: @fontSizeSmall;
color: @errorText;
padding: 1em;
background-color: @errorBackground;
}
div .form-error {
.error;
}</code>

==== Incorrect ====

<code css>.error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}
div .form-error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}</code>

== Themes Clean and More ==

Clean theme should, where possible, not contain any CSS or LESS content. More theme, in comparison, inherits CSS styles for the logo from Clean theme, but also contains a small amount of LESS as an example for when customising a theme. Both Clean and More inherit fully all the CSS from their parent theme 'Bootstrap Base'.

== Credits ==

This document was drawn from the following sources:

# The [http://codex.wordpress.org/CSS_Coding_Standards WordPress CSS Coding Standards]

== See Also ==

* [[Coding]]
* [[Coding_style|Coding style]]

[[Category:Coding guidelines|CSS Coding style]]

CSS Coding Style

2015-08-30T23:36:39Z

Tqr: /* Themes Clean and More */

{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=275476}}

== Overview ==

=== Scope ===

This document describes style guidelines for developers working on or with Moodle code. It talks purely about the mechanics of code layout and the choices we have made for Moodle.

=== Goals ===

Consistent coding style is important in any development project, and particularly when many developers are involved. A standard style helps to ensure that the code is easier to read and understand, which helps overall quality.

Abstract goals we strive for:

* simplicity
* readability
* tool friendliness

== File naming ==

Within plugins, CSS files are normally named <code>styles.css</code>.

In the theme, files can be named according to the theme designer's wishes but should:

* use lowercase letters and '-' to separate words
* be as succinct as possible
* be descriptive
* be placed in the folder <code>style/</code> for CSS files, or in <code>less/</code> for LESS files.

== Blocks ==

* Each selector should be on its own line. If there is a comma in a selector list, follow it with a line break.
* Property-value pairs should be on their own line, with four spaces of indentation and an ending semicolon.
* The closing brace should use the same level of indentation as the opening selector.
* Leave one line between blocks.

=== Correct ===

<code css>@media only screen and (min-width: 768px) {
.selector-one,
.selector-two {
color: #fff;
background-color: #000;
}
}</code>

=== Incorrect ===

<code css>.selector_one, .selector_two { color: #fff; background-color: #000; }</code>

== Selectors ==

* Always use lower case and underscores or hyphens. Hyphens are preferred.
* Names should be made of simple English words.
* Verbosity is encouraged: names should be as illustrative as is practical to enhance understanding.
* Use [http://css-tricks.com/semantic-class-names/ semantic names]: names tell what this is instead of what should it look like.
* Avoid using IDs. They are far more difficult to maintain and override.
* Do not over-qualify your rules by combining a tagname with a class or ID.

=== Correct ===

<code css>.selector_name {
color: #fff;
}

.selector-name {
color: #fff;
}
</code>

=== Incorrect ===

<code css>div#selName {
color: #fff;
}

.Color-White {
color: #fff;
}</code>

== Properties and values ==

* Should be separated by a colon and a single space, do not minify them.
* Should be lowercase, except for font names and vendor-specific properties.
* For color codes, lowercase is preferred and a shorthand whenever possible.
* For color codes, if you use HSLA or RGBA, always provide a hex fallback.
* Use shorthand (except when overriding styles) for background, border, font, list-style, margin, and padding values.
* Do not use <code>!important</code>. If there is no alternative something is wrong with the CSS you are trying to override.
* Prefixed vendor-specific properties pairs should appear directly before the generic property they refer to.
* Indent vendor prefixed declarations so that their values are aligned

=== Correct ===

<code css>.selector {
color: #fff;
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

.selector {
margin-top: 1px;
color: #f90;
color: hsla(0, 0%, 100%, 1);
}</code>

=== Incorrect ===

<code css>#selector {
color: hsla(0, 0%, 100%, 1);
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

#selector {
margin-top:1px;
color :#ff9900 !important;
}</code>

== Units ==

* Prefer the usage of ''em'' over ''px''.
* Do not use the units ''pt'' or ''rem''. MDL-39934
* Do not declare the unit when the value is 0.

=== Correct ===

<code css>.something {
margin-top: 0;
font-size: 1.25em;
}</code>

=== Incorrect ===

<code css>.something {
margin-top: 0px;
font-size: 1.25rem;
}</code>

== Documentation and comments ==

Following the general [[Coding style]], comments should start with a capital letter and end with a period.

A block-style comment at the top of the CSS file should explain the purpose of the rules in the file.
<code css>
/**
* File base.css.
* Contains base styles for theme basic.
*/
</code>

Block-style comments can also be used to denote a section in a CSS file where all rules pertain to a specific component, view, or functionality:
<code css>
/**
* SCORM Navigation Sidebar.
*/
</code>

Use single-line comments to provide more information to other developers about a single rule or small subset of rules:
<code css>
/* Required because YUI resets add a black border to all tables */
</code>

== Progressive enhancement ==

* Fallbacks should always be provided. For example, provide a background color fallback to background images and gradients.
* Use vendor prefixes only when the supported browser in question does not support the unprefixed property.
* The standard property should come after the vendor-prefixed property.

<code css>.selector {
background-color: #444; /* Fallback for browsers that don't support gradients. */
filter: progid:DXImageTransform.Microsoft.gradient(startColorStr='#444', EndColorStr='#999'); /* IE6-IE9. */
background-image: -webkit-gradient(linear, left top, left bottom, from(#444), to(#999)); /* Safari 4+, Chrome. */
background-image: -webkit-linear-gradient(top, #444, #999); /* Chrome 10+, Safari 5.1+, iOS 5+. */
background-image: -moz-linear-gradient(top, #444, #999); /* Firefox 3.6. */
background-image: -ms-linear-gradient(top, #444, #999); /* IE10. */
background-image: -o-linear-gradient(top, #444, #999); /* Opera 11.10+. */
background-image: linear-gradient(top, #444, #999); /* W3C Standard. */
}</code>

== Browser Hacks ==

* Do not use any browser-specific hacks. Moodle provides a more appropriate way to write browser-specific CSS using classes that are added to the body element. For example:

<code css>
.ie7 .forum-post {
min-height: 1px;
}
</code>

* It is not necessary to include hacks for versions of browsers that Moodle core does not provide support for (e.g. IE6 in Moodle 2, except legacy theme).

== Plugins ==

In plugins, the file names can be:

* styles.css (Recommended)
* styles_<theme name>.css (Not recommended, reserved to 3rd party plugins)

=== Barebones ===

Plugins should define the strict minimum, no text sizes, colours, etc ... those should belong to the theme and not be hardcoded in plugins to allow for easy theming. Of course, this requires Moodle core to provide re-usable classes to style the elements. As Moodle 2.7 has made Bootstrap 2 by default we can start using their classes, but we should make sure that there is a sensible fallback for themes not extending ''bootstrapbase'', such as ''base''.

== Right-to-left ==

Developers always have to pay attention to RTL languages.

=== Selector ===

Always use the selector <code>.dir-rtl</code> to define RTL rules. That class is set on the BODY tag, and it should be placed first if you are combining it with another BODY class. When you are using LESS, encapsulate all the rules in <code>.dir-rtl</code>.

==== Correct ====

<code css>.dir-rtl .something {
margin-left: 0;
margin-right: 1em;
}
.dir-rtl.page-mod-something p {
padding-left: 0;
padding-right: 1em;
}</code>

<code css>.dir-rtl {
&.page-mod-something {
p {
padding-left: 0;
padding-right: 1em;
}
}
.something {
margin-left: 0;
margin-right: 1em;
}
}</code>

==== Incorrect ====

<code css>body.dir-rtl .something {
margin-left: 0;
margin-right: 1em;
}
.page-mod-something.dir-rtl p {
padding-left: 0;
padding-right: 1em;
}</code>

<code css>.dir-rtl {
&.page-mod-something {
p {
padding-left: 0;
padding-right: 1em;
}
}
}
.dir-rtl {
.something {
margin-left: 0;
margin-right: 1em;
}
}</code>

=== Rule placement ===

The RTL rules should be written close to the LTR ones, not in another file. Placing them close to the LTR ones helps (and reminds) the developers to fix both, without the need to search for the existence of RTL rules. If you are using LESS, it is advised to split a huge block into smaller chunks to help locating the corresponding LTR rules.

=== Automatic compliance ===

Whenever possible you should try to avoid writing specific RTL rules. It is more often than one would think possible to have one rule working for both LTR and RTL.

==== Recommended ====

<code css>p {
margin: 0 1em;
}</code>

==== To avoid ====

<code css>p {
margin-left: 1em;
}
.dir-rtl p {
margin-right: 1em;
margin-left: 0;
}</code>

=== What to style ===

RTL rules should only apply to positioning properties, nothing else. And in most cases you will want to revert the LTR rules, to make sure that the rest works as expected.

==== Correct ====

<code css>.something {
text-color: red;
padding-left: 1em;
}
.dir-rtl .something {
padding-left: 0;
padding-right: 1em;
}
</code>

==== Incorrect ====

<code css>
.dir-rtl .something {
text-color: red;
padding-right: 1em;
}
</code>

== LESS ==

[http://lesscss.org/ LESS] works like CSS with some extra features. It should follow the CSS guidelines.

=== Variables ===

* They should use camelCase to follow Bootstrap 2 that is used in core.
* As for CSS selectors, use semantic names: names tell what this is instead of what should it look like.
* As Bootstrap 2 does, do not add the word "Color" to variables for _background_ or _border_ and their derivatives.
* Declaring new variables should be done sparingly, too many variables kill the purpose of using them. If you declare one, try to set its default value from another one.
* Do not declare more variables than necessary. E.g.: If the background color and border color are likely to always be the same, prefer one variable.

==== Correct ====

<code css>@textColor: red;
@wellBackground: #ccc;
@tableBackground: blue;
@blockBackground: @wellBackground;
@calendarGroupEvent: #f90;</code>

==== Incorrect ====

<code css>@text-color: red;
@wellBackground: #ccc;
@tableBackgrounColor: blue;
@blockBackground: #ccc;
@calendarGroupEventBackground: #f90;
@calendarGroupEventBorder: #f90;</code>

=== Selectors ===

* Selectors should be encapsulated rather than duplicated.

==== Correct ====

<code css>div {
.something {
color: red;
a {
color: blue;
}
}
.something-else a {
color: green;
}
}</code>

==== Incorrect ====

<code css>div .something {
color: red;
}
div .something a {
color: blue;
}
div .something-else a {
color: green;
}</code>

=== Values and properties ===

* Colours, font sizes, etc... should never be hardcoded, use a variable instead.
* Use mixins instead of duplicating values and properties.

==== Correct ====

<code css>.error {
font-size: @fontSizeSmall;
color: @errorText;
padding: 1em;
background-color: @errorBackground;
}
div .form-error {
.error;
}</code>

==== Incorrect ====

<code css>.error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}
div .form-error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}</code>

== Themes Clean and More ==

Clean theme should not contain any CSS or LESS content, it should fully inherit from ''theme_bootstrapbase''. More can contain a little portion of LESS to ensure that customization is possible, but it should be almost inherit fully from ''theme_bootstrapbase'' unless pertinent to the theme,
<pre>
For example:
div.logo {
background: url([[setting:logo]]) no-repeat 0 0;
display: block;
float: left;
height: 75px;
margin: 0;
padding: 0;
width: 100%;
}
}</pre>

== Credits ==

This document was drawn from the following sources:

# The [http://codex.wordpress.org/CSS_Coding_Standards WordPress CSS Coding Standards]

== See Also ==

* [[Coding]]
* [[Coding_style|Coding style]]

[[Category:Coding guidelines|CSS Coding style]]

CSS Coding Style

2015-08-30T23:35:57Z

Tqr: /* Themes Clean and More */

{{Work in progress|forumurl=https://moodle.org/mod/forum/discuss.php?d=275476}}

== Overview ==

=== Scope ===

This document describes style guidelines for developers working on or with Moodle code. It talks purely about the mechanics of code layout and the choices we have made for Moodle.

=== Goals ===

Consistent coding style is important in any development project, and particularly when many developers are involved. A standard style helps to ensure that the code is easier to read and understand, which helps overall quality.

Abstract goals we strive for:

* simplicity
* readability
* tool friendliness

== File naming ==

Within plugins, CSS files are normally named <code>styles.css</code>.

In the theme, files can be named according to the theme designer's wishes but should:

* use lowercase letters and '-' to separate words
* be as succinct as possible
* be descriptive
* be placed in the folder <code>style/</code> for CSS files, or in <code>less/</code> for LESS files.

== Blocks ==

* Each selector should be on its own line. If there is a comma in a selector list, follow it with a line break.
* Property-value pairs should be on their own line, with four spaces of indentation and an ending semicolon.
* The closing brace should use the same level of indentation as the opening selector.
* Leave one line between blocks.

=== Correct ===

<code css>@media only screen and (min-width: 768px) {
.selector-one,
.selector-two {
color: #fff;
background-color: #000;
}
}</code>

=== Incorrect ===

<code css>.selector_one, .selector_two { color: #fff; background-color: #000; }</code>

== Selectors ==

* Always use lower case and underscores or hyphens. Hyphens are preferred.
* Names should be made of simple English words.
* Verbosity is encouraged: names should be as illustrative as is practical to enhance understanding.
* Use [http://css-tricks.com/semantic-class-names/ semantic names]: names tell what this is instead of what should it look like.
* Avoid using IDs. They are far more difficult to maintain and override.
* Do not over-qualify your rules by combining a tagname with a class or ID.

=== Correct ===

<code css>.selector_name {
color: #fff;
}

.selector-name {
color: #fff;
}
</code>

=== Incorrect ===

<code css>div#selName {
color: #fff;
}

.Color-White {
color: #fff;
}</code>

== Properties and values ==

* Should be separated by a colon and a single space, do not minify them.
* Should be lowercase, except for font names and vendor-specific properties.
* For color codes, lowercase is preferred and a shorthand whenever possible.
* For color codes, if you use HSLA or RGBA, always provide a hex fallback.
* Use shorthand (except when overriding styles) for background, border, font, list-style, margin, and padding values.
* Do not use <code>!important</code>. If there is no alternative something is wrong with the CSS you are trying to override.
* Prefixed vendor-specific properties pairs should appear directly before the generic property they refer to.
* Indent vendor prefixed declarations so that their values are aligned

=== Correct ===

<code css>.selector {
color: #fff;
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

.selector {
margin-top: 1px;
color: #f90;
color: hsla(0, 0%, 100%, 1);
}</code>

=== Incorrect ===

<code css>#selector {
color: hsla(0, 0%, 100%, 1);
-webkit-border-radius: 4px;
-moz-border-radius: 4px;
border-radius: 4px;
}

#selector {
margin-top:1px;
color :#ff9900 !important;
}</code>

== Units ==

* Prefer the usage of ''em'' over ''px''.
* Do not use the units ''pt'' or ''rem''. MDL-39934
* Do not declare the unit when the value is 0.

=== Correct ===

<code css>.something {
margin-top: 0;
font-size: 1.25em;
}</code>

=== Incorrect ===

<code css>.something {
margin-top: 0px;
font-size: 1.25rem;
}</code>

== Documentation and comments ==

Following the general [[Coding style]], comments should start with a capital letter and end with a period.

A block-style comment at the top of the CSS file should explain the purpose of the rules in the file.
<code css>
/**
* File base.css.
* Contains base styles for theme basic.
*/
</code>

Block-style comments can also be used to denote a section in a CSS file where all rules pertain to a specific component, view, or functionality:
<code css>
/**
* SCORM Navigation Sidebar.
*/
</code>

Use single-line comments to provide more information to other developers about a single rule or small subset of rules:
<code css>
/* Required because YUI resets add a black border to all tables */
</code>

== Progressive enhancement ==

* Fallbacks should always be provided. For example, provide a background color fallback to background images and gradients.
* Use vendor prefixes only when the supported browser in question does not support the unprefixed property.
* The standard property should come after the vendor-prefixed property.

<code css>.selector {
background-color: #444; /* Fallback for browsers that don't support gradients. */
filter: progid:DXImageTransform.Microsoft.gradient(startColorStr='#444', EndColorStr='#999'); /* IE6-IE9. */
background-image: -webkit-gradient(linear, left top, left bottom, from(#444), to(#999)); /* Safari 4+, Chrome. */
background-image: -webkit-linear-gradient(top, #444, #999); /* Chrome 10+, Safari 5.1+, iOS 5+. */
background-image: -moz-linear-gradient(top, #444, #999); /* Firefox 3.6. */
background-image: -ms-linear-gradient(top, #444, #999); /* IE10. */
background-image: -o-linear-gradient(top, #444, #999); /* Opera 11.10+. */
background-image: linear-gradient(top, #444, #999); /* W3C Standard. */
}</code>

== Browser Hacks ==

* Do not use any browser-specific hacks. Moodle provides a more appropriate way to write browser-specific CSS using classes that are added to the body element. For example:

<code css>
.ie7 .forum-post {
min-height: 1px;
}
</code>

* It is not necessary to include hacks for versions of browsers that Moodle core does not provide support for (e.g. IE6 in Moodle 2, except legacy theme).

== Plugins ==

In plugins, the file names can be:

* styles.css (Recommended)
* styles_<theme name>.css (Not recommended, reserved to 3rd party plugins)

=== Barebones ===

Plugins should define the strict minimum, no text sizes, colours, etc ... those should belong to the theme and not be hardcoded in plugins to allow for easy theming. Of course, this requires Moodle core to provide re-usable classes to style the elements. As Moodle 2.7 has made Bootstrap 2 by default we can start using their classes, but we should make sure that there is a sensible fallback for themes not extending ''bootstrapbase'', such as ''base''.

== Right-to-left ==

Developers always have to pay attention to RTL languages.

=== Selector ===

Always use the selector <code>.dir-rtl</code> to define RTL rules. That class is set on the BODY tag, and it should be placed first if you are combining it with another BODY class. When you are using LESS, encapsulate all the rules in <code>.dir-rtl</code>.

==== Correct ====

<code css>.dir-rtl .something {
margin-left: 0;
margin-right: 1em;
}
.dir-rtl.page-mod-something p {
padding-left: 0;
padding-right: 1em;
}</code>

<code css>.dir-rtl {
&.page-mod-something {
p {
padding-left: 0;
padding-right: 1em;
}
}
.something {
margin-left: 0;
margin-right: 1em;
}
}</code>

==== Incorrect ====

<code css>body.dir-rtl .something {
margin-left: 0;
margin-right: 1em;
}
.page-mod-something.dir-rtl p {
padding-left: 0;
padding-right: 1em;
}</code>

<code css>.dir-rtl {
&.page-mod-something {
p {
padding-left: 0;
padding-right: 1em;
}
}
}
.dir-rtl {
.something {
margin-left: 0;
margin-right: 1em;
}
}</code>

=== Rule placement ===

The RTL rules should be written close to the LTR ones, not in another file. Placing them close to the LTR ones helps (and reminds) the developers to fix both, without the need to search for the existence of RTL rules. If you are using LESS, it is advised to split a huge block into smaller chunks to help locating the corresponding LTR rules.

=== Automatic compliance ===

Whenever possible you should try to avoid writing specific RTL rules. It is more often than one would think possible to have one rule working for both LTR and RTL.

==== Recommended ====

<code css>p {
margin: 0 1em;
}</code>

==== To avoid ====

<code css>p {
margin-left: 1em;
}
.dir-rtl p {
margin-right: 1em;
margin-left: 0;
}</code>

=== What to style ===

RTL rules should only apply to positioning properties, nothing else. And in most cases you will want to revert the LTR rules, to make sure that the rest works as expected.

==== Correct ====

<code css>.something {
text-color: red;
padding-left: 1em;
}
.dir-rtl .something {
padding-left: 0;
padding-right: 1em;
}
</code>

==== Incorrect ====

<code css>
.dir-rtl .something {
text-color: red;
padding-right: 1em;
}
</code>

== LESS ==

[http://lesscss.org/ LESS] works like CSS with some extra features. It should follow the CSS guidelines.

=== Variables ===

* They should use camelCase to follow Bootstrap 2 that is used in core.
* As for CSS selectors, use semantic names: names tell what this is instead of what should it look like.
* As Bootstrap 2 does, do not add the word "Color" to variables for _background_ or _border_ and their derivatives.
* Declaring new variables should be done sparingly, too many variables kill the purpose of using them. If you declare one, try to set its default value from another one.
* Do not declare more variables than necessary. E.g.: If the background color and border color are likely to always be the same, prefer one variable.

==== Correct ====

<code css>@textColor: red;
@wellBackground: #ccc;
@tableBackground: blue;
@blockBackground: @wellBackground;
@calendarGroupEvent: #f90;</code>

==== Incorrect ====

<code css>@text-color: red;
@wellBackground: #ccc;
@tableBackgrounColor: blue;
@blockBackground: #ccc;
@calendarGroupEventBackground: #f90;
@calendarGroupEventBorder: #f90;</code>

=== Selectors ===

* Selectors should be encapsulated rather than duplicated.

==== Correct ====

<code css>div {
.something {
color: red;
a {
color: blue;
}
}
.something-else a {
color: green;
}
}</code>

==== Incorrect ====

<code css>div .something {
color: red;
}
div .something a {
color: blue;
}
div .something-else a {
color: green;
}</code>

=== Values and properties ===

* Colours, font sizes, etc... should never be hardcoded, use a variable instead.
* Use mixins instead of duplicating values and properties.

==== Correct ====

<code css>.error {
font-size: @fontSizeSmall;
color: @errorText;
padding: 1em;
background-color: @errorBackground;
}
div .form-error {
.error;
}</code>

==== Incorrect ====

<code css>.error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}
div .form-error {
font-size: 12px;
color: red;
padding: 1em;
background-color: white;
}</code>

== Themes Clean and More ==

Clean theme should not contain any CSS or LESS content, it should fully inherit from ''theme_bootstrapbase''. More can contain a little portion of LESS to ensure that customization is possible, but it should be almost inherit fully from ''theme_bootstrapbase'' unless pertinent to the theme,

<pre>
For example:
div.logo {
background: url([[setting:logo]]) no-repeat 0 0;
display: block;
float: left;
height: 75px;
margin: 0;
padding: 0;
width: 100%;
}
}</pre>

== Credits ==

This document was drawn from the following sources:

# The [http://codex.wordpress.org/CSS_Coding_Standards WordPress CSS Coding Standards]

== See Also ==

* [[Coding]]
* [[Coding_style|Coding style]]

[[Category:Coding guidelines|CSS Coding style]]

LESS

2015-08-25T23:36:19Z

Tqr: /* Windows 7, 8 & 10 */

== Overview ==

LESS ([http://lesscss.org lesscss.org]) extends CSS with dynamic behavior such as variables, mixins, operations and functions. It's an advanced way of writing CSS that we use in some themes within Moodle.

Browsers don't interpret it themselves, however, so LESS files need to be converted into normal CSS before use.

Recess is one tool used to compile and compress LESS into CSS under *nix based systems. There are [https://github.com/cloudhead/less.js/wiki/GUI-compilers-that-use-LESS.js many others tools for LESS].

== The bootstrapbase theme ==

Moodle's [[Bootstrap]] base theme has rules written using LESS.

The main LESS file is '''theme/bootstrapbase/less/moodle.less''', with additional files in '''theme/bootstrapbase/less/moodle/''' imported by the main file.

After compiling the LESS files, CSS ends up in '''theme/bootstrapbase/style/moodle.css'''. This file should not be edited manually.

== Installing Recess ==

=== Ubuntu ===

The following commands should be run to install Recess

<code bash>
sudo apt-get install npm nodejs
# If the above fails due to the error "The following packages have unmet dependencies",
# run the commands separately, ie.
# sudo apt-get install npm
# and then
# sudo apt-get install nodejs
npm install recess -g
# If the above fails with a "..permission denied.." error,
# run npm install with sudo:
# sudo npm install recess -g
</code>

If you find problem installing nodejs with npm, you can use [http://nodejs.org/download/ node.js binaries]
# Download Linux Binaries [http://nodejs.org/download/ node.js binaries]
# untar it to your local directory and add it to the PATH.
You can also use following script to get latest version.
<code bash>
CURRENT=$(node -v)
VERSION=$(curl -L -s http://nodejs.org/dist/latest/ \
| egrep -o '[0-9]+\.[0-9]+\.[0-9]+' \
| tail -n1)
PLATFORM=linux
ARCH=x64
PREFIX="$HOME/node-v$VERSION-$PLATFORM-$ARCH"

if test "v$VERSION" != "$CURRENT"; then
echo "Installing node v$VERSION ..."
mkdir -p "$PREFIX" && \
curl -# -L http://nodejs.org/dist/v$VERSION/node-v$VERSION-$PLATFORM-$ARCH.tar.gz \
| tar xzvf - --strip-components=1 -C "$PREFIX"
echo 'export PATH=$PATH:'"$PREFIX" >> $HOME/.bashrc
echo "Latest stable version installed at $PREFIX"
else
echo "Latest stable version of node already installed."
fi
</code>
<code>npm</code> stands for Node Package Manager, and is the equivalent of apt-get for node.js packages.

=== Mac OS X ===
1. Install the basic node packages from the web site: [http://nodejs.org http://nodejs.org] (or use your favourite package manager to install <code>node</code> and <code>npm</code>).

2. On the command line, install recess like this:
<code bash>
npm install recess -g
</code>

=== FreeBSD ===
1. Install npm (will also install nodes ie nodejs as a dependency)

Using packages on: <code>pkg install npm</code>

Build port in /usr/port/www: <code>cd /usr/port/www/npm; make install clean</code>

Using portmaster: <code>portmaster npm</code>

2. On the command line, install recess like this: <code>npm install recess -g</code>

=== Windows 7, 8, & 10 ===

In order to install Recess you need to have Node.js installed first, which is relatively simple to do.

Go to nodejs.org click install.

When installed go to -> Start -> All Programs -> type Node.js into the Search box, then select Node.js Command prompt (black icon) from the list. Now you are ready to install Recess. So at the command line prompt type the following:

<code bash>
npm install recess -g
</code>

<code>npm</code> stands for Node Package Manager, and is the equivalent of apt-get for node.js packages.

== Using Recess ==

After editing the LESS files, compile (minified) your CSS as follows:

<code bash>
cd theme/bootstrapbase/less/
recess --compile --compress moodle.less > ../style/moodle.css
</code>

or if you prefer to run it from the top-level:

<code bash>
recess --compile --compress theme/bootstrapbase/less/moodle.less > theme/bootstrapbase/style/moodle.css
</code>

This will compile and compress the moodle.less file (and all the LESS and CSS files it imports) into a single file, moodle.css, and store it in the style folder of the bootstrapbase theme.

Alternatively if you want to view the normal (un-minified) CSS then use the following method.

<pre>
recess --compile moodle.less > ../style/moodle.css
</pre>

'''NOTE:''' if you are getting an empty moodle.css file, this is being caused by a parsing error in your LESS code. A bug in <code>recess</code> currently prevents it giving you helpful error messages in many cases. You will need to examine what you have altered or written to make sure it is complete and the syntax is correct. The <code>lessc</code> compiler is what is used by <code>recess</code> to do the actual compiling and will have been installed automatically along with it. If you call it directly as <code>lessc moodle.less</code> it should give you a helpful error message that points you to where the problem is.

jQuery

2015-04-23T23:21:33Z

Tqr:

{{Moodle 2.9}}

Before Moodle 2.9 we used [[YUI]] to write javascript in Moodle. As of Moodle 2.9 we are transitioning to jQuery and [[Javascript Modules]] because Yahoo has ceased all new development on YUI (http://yahooeng.tumblr.com/post/96098168666/important-announcement-regarding-yui).

This page explains the recommended way to use jQuery in core and plugins, although other [[jQuery pre2.9|older]] methods of including jQuery will still work.

== Why do we need JQuery? ==
JQuery is useful for handling browser inconsistencies, and for utility functions that would otherwise be duplicated all over the code. Some particular things that JQuery is good at are:
* DOM Manipulations
* Promises ($.Deferred)
* Ajax

== How to use JQuery ==
As of Moodle 2.9, the recommended way to write javascript is in AMD Modules. For more information on writing AMD modules in Moodle see [[ Javascript Modules ]].

JQuery has been added as an AMD Module and is available to all AMD javascript.

To make use of JQuery, either list it as a dependency of your module, or use a require call to load it.

=== As a dependency of a module ===
<code>
define(['jquery'], function($) {
// Private functions.
var privateFunc = function(a) {
// JQuery is available via $ if I want it
return a + 1;
};

// Public functions.
return {
publicFunc: function(b) {
// JQuery is available via $ if I want it
return privateFunc(b) + 1;
}
}
});
</code>

=== With a require call ===
<code>
require(['jquery'], function($) {
// JQuery is available via $
});
// JQuery is not in scope and cannot be used.
</code>

== What about JQuery UI ? ==
JQuery UI is a separate project containing a library of reusable widgets that relies on JQuery. JQuery UI is available for plugins to use, but it should not be used in core code.

The problems with JQuery UI are:
* It uses an entirely different themeing system for CSS that does not work well with Moodle themes
* It introduces CSS conflicts with bootstrap
* The widgets have some accessibility features - but only if used in a very specific way which is not well documented

Over time we will build up a library of widgets in core either by wrapping a suitable library or implementing from scratch.

If you STILL want to use JQuery UI in your plugin, it is available as an AMD module named 'jqueryui'.

<code>
require(['jquery', 'jqueryui'], function($, jqui) {
// JQuery is available via $
// JQuery UI is available via jqui
});
// JQuery is not in scope and cannot be used.
// JQuery UI is not in scope and cannot be used.
</code>

==See also==
* [[Javascript Modules]]
* [[jQuery pre2.9]]
* [http://jquery.com jQuery]
* [http://jqueryui.com jQuery User Interface]

[[Category:Javascript]]

Javascript Modules

2015-04-23T14:15:08Z

Tqr:

{{Moodle 2.9}}

= Javascript Modules =

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

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

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

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

a) Each smaller piece is simpler to understand / debug

b) Each smaller piece is simpler to test

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

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

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

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

== Install grunt ==
The AMD modules in Moodle must be processed by some build tools before they will be visible to your web browser. We use "[http://gruntjs.com/ grunt]" as a build tool to wrap our different processes. Grunt is a build tool written in Javascript that runs in the "[http://nodejs.org/ nodejs]" environment. This means you first have to install nodejs - and it's package manager "[https://www.npmjs.com/ npm]". The details of how to install those packages will vary by operating system, but on Linux it's probably similar to "sudo apt-get install nodejs npm". There are downloadable packages for other operating systems here: http://nodejs.org/download/. Once this is done, you can run the command: "npm install" from the top of the Moodle directory to install all of the required tools.

== Running grunt ==
Grunt is a special node package in that it comes in 2 parts. One part is the grunt package that is installed in the node_modules folder by the "npm install" command listed in the previous section. The second part is that you also need to install the grunt-cli package globally in order to have a "grunt" command in your path. To do this run "npm install -g grunt-cli" (you may need additional permissions to do this).

Now you can run the "grunt" command from any folder in Moodle and it should "build" all of the javascript from that directory and it's sub directories.

When grunt runs it currently does 3 things:

* - it runs [https://github.com/yui/shifter shifter] to build any YUI modules in the source tree. See [YUI/Shifter] for more information on shifter
* - it runs [http://jshint.com/ jshint] to detect invalid Javascript, or Javascript that does not comply with our coding guidelines
* - it runs [http://lisperator.net/uglifyjs/ uglifyjs] to reduce the size of any Javascript by removing whitespace, stripping comments, shortening variable names etc.

You must run "grunt" after making any change to the Javascript in Moodle.

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

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

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

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

Lets create a simple module now:

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

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

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

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

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

};

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Creating a theme

2015-04-20T16:57:01Z

Tqr:

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

For Themes in Moodle 2.2 onwards please read the tutorial about [https://docs.moodle.org/dev/Themes_2.2_how_to_clone_a_Moodle_2.2_theme How to clone a Moodle 2.2 theme].

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

Creating a theme

2015-04-20T16:55:21Z

Tqr:

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

For Themes in Moodle 2.2 onwards please read the tutorial about [https://docs.moodle.org/dev/Themes_2.2_how_to_clone_a_Moodle_2.2_theme| How to clone a Moodle 2.2 theme].

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

Creating a theme

2015-04-20T16:52:10Z

Tqr:

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

For Themes in Moodle 2.2 onwards please read the tutorial about [https://docs.moodle.org/dev/Themes_2.2_how_to_clone_a_Moodle_2.2_theme | How to clone a Moodle 2.2 theme].

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

Creating a theme settings page

2014-09-24T22:34:29Z

Tqr: /* Finishing settings.php */

{{Template:Themes}}This document looks at how to create a settings page for your Moodle 2.x.x theme and how to make use of those settings within the CSS and layout files for your theme.

This is a pretty advanced topic and will require that you have at least an intermediate knowledge of PHP, CSS, and development in general.

==Before we begin==
[[Image:Theme.settings.page.03.png|350px|thumb|Our end goal. The settings page.]]
[[Image:Theme.settings.page.10.png|350px|thumb|And what it can do.]]
There is a huge body of knowledge that we must cover in following through this document and as such I think the best way to write this is as a tutorial.

My intentions for this tutorial are to replicate the standard theme but with a settings page that allows the administrator to set a background colour, set a logo to use with the page, and probably several other minor settings to change the way in which the theme is displayed.

I will start this tutorial by creating a new theme which will be largely a copy/paste of the current standard theme. I expect that anyone working through this tutorial has previously read the tutorial I wrote on [[Themes 2.0 creating your first theme|creating your first theme]]. If you haven't go read it now because I'm not going to go into much detail until we get to the actual process of customising the theme and introducing the settings page.

So before we finally get this started please ensure you can check off everything on the following requirements list.
* Have a Moodle installation that has already been installed and configured and is ready to use.
* Have full read/write access to that installation.
* Be prepared to delete that installation at the end of this... we will destroy it!
* Have a development environment prepared and ready to use. This includes:
** Your favourite editor installed, running, and pointed at the themes directory of your installation.
** Your browser open and your site visible.
** A bottomless coffee pot... decaf won't help you with this one.
* Have set the following settings:
** '''themedesignermode''' if you don't know what this is please read the [[Themes 2.0 creating your first theme|creating your first theme]] tutorial.
** '''allowthemechangeonurl''' turn this on, it allows you to change themes on the URL and is very handy when developing themes. ''Site Administration > Appearance > Themes > Theme settings''
** '''langstringcache''' if you don't turn this off you won't see your strings when they are added. ''Site Administration > Language > Language settings''
* And finally an insane ambition to create a customisable theme.

For those interested the theme that I create throughout this tutorial can be downloaded from the forum post in which I announce this document: http://moodle.org/mod/forum/discuss.php?d=152053
<br style="clear:right;" />

==Our goals for this tutorial==
The following is just a list goals that I hope to achieve during this tutorial. They are laid out here so that I can easily refer back to them and so that you can easily find them.
# Create a new theme called '''demystified''' based upon the standard theme within Moodle 2.0.
# Make some minor changes to that theme to allow us to more easily see what is going on.
# Create a settings page for the demystified theme.
# Add several settings to our settings page.
# Use some of those settings to alter our CSS.
# Use the rest of those settings within our layout file..
# Discuss the good, the bad, and limits of what we have just created.

So I can see you are all very excited about this point and that you would love to know what settings we are going to create; So here they are:

A setting to ...
* change the background colour (CSS).
* set the path to an image that we will use as a logo on all pages (Layout files).
* override the width of the block regions (CSS).
* allow a note to be added to the footer of all pages (Layout files).
* allow custom CSS to be written to do anything the user wants. (CSS)

==Creating the demystified theme==
Before we start here I want to remind you that I am going to look at this only briefly as I am making the assumption that you have read the [[Themes 2.0 creating your first theme|creating your first theme]] tutorial.

Well lets get into it....

The first thing we need to do is create a directory for our theme which we will call demystified.

So within your Moodle directory create the following folder '''moodle/theme/demystified'''. At the same time you can also create the following files and folders which we will get to soon.
* The file '''moodle/theme/demystified/config.php''' for our config information.
* The directory '''moodle/theme/demystified/layout''' for our layout files.
* The directory '''moodle/theme/demystified/style''' for our css files.
* The file '''moodle/theme/demystified/style/core.css''' which will contain our special CSS.

Next we will copy the layout files from the base theme to our new theme demystified. We are basing the demystified theme on the standard theme however that doesn't use it's own layout files it uses the base theme's layout files so those are the ones we want.

The reason that we are coping these layout files is that later on in this tutorial we will be modifying them to make use of our new settings... so copy all of the layout files from '''moodle/theme/base/layout''' to '''moodle/theme/demystified/layout'''.

There should be three files that you just copied:
# embedded.php
# frontpage.php
# general.php

Now we need to populate demystified/config.php with the settings for our new theme. They are as follows:
<code php>
$THEME->name = 'demystified';
</code>
Simply sets the name of our theme.

<code php>
$THEME->parents = array('standard','base');
</code>
This theme is extending both the standard theme and the base theme. Remember when extending a theme you also need to extend its parents or things might not work correctly.

<code php>
$THEME->sheets = array('core');
</code>
This tells our theme that we want to use the file '''demystified/style/core.css''' with this theme.

<div style="height:300px;overflow-y:scroll;">
<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-post',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'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),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>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),
),
// 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),
),
);
</code>
</div>
Now that all looks very complicated however its really not too bad as it is just copied from the base theme's config.php file. We can do this because we copied the layout files from the base theme to begin with and for the time being there are no changes that we wish to make. Simply open up '''theme/base/config.php''' and copy the layouts from there.

And that is it. The config.php file for our demystified theme is complete. The full source is shown below:
<div style="height:300px;overflow-y:scroll;">
<code php>
<?php

// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* The demystified theme config file
*
* This theme was created to document the process of adding a settings page to a theme
*
* @copyright 2010 Sam Hemelryk
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

// The name of our theme
$THEME->name = 'demystified';

// The other themes this theme extends
$THEME->parents = array('standard','base');

// The CSS files this theme uses (located in the style directory)
$THEME->sheets = array('core');

// The layout definitions for this theme
$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-post',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'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),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>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),
),
// 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),
),
);
</code>
</div>

The screenshot below shows both the directory structure we have now created and the theme presently.

[[Image:Theme.settings.page.01.png]]

To view the theme so far open you browser and enter the URL of your site followed by '''?theme=demystified'''. You should see the theme that we just created which will look exactly like the base standard theme.

The final thing that we want to do is add a little bit of CSS to the demystified theme that will both visually set this theme apart from the standard theme and second build a the base which our settings can later extend.

I added the following snippet of CSS to the file '''demystified/style/core.css'''.
<code css>
html {background-color:#DDD;}
body {margin:30px;padding:0;border:1px solid #333;border-width:0 10px 0 10px;background-color:#333;}
body #page {background-color:#FFF;position:relative;top:-10px;}
.block .header {background-image:none;background-color:#0C5CAC;border:1px solid #0C5CAC;color:#FFF;}
.block {border-color:#4BA7FF;background-color:#DDEEFF;}
.block .content {background-color:#F1F8FF;}
a:link,
a:visited {color:#0C5CAC;}
a:hover {color:#C77500;}
#page #page-header {background-color:#0C5CAC;margin:0;padding:0;width:100%;color:#fff;}
#page #page-header a:link, #page #page-header a:visited {color:#FFAC02}
#page #page-header .navbar, #page #page-header .navbar a:link, #page #page-header .navbar a:visited {color:#0C5CAC;}
</code>

The CSS that we have just added to our theme sets a couple of colours on the front page. Presently this is the only CSS I will add, I know it isn't complete by any means but it achieves it's purpose as the screenshot below illustrates.

[[Image:Theme.settings.page.02.png|715px|thumb|left|The newly styles demystified theme]]<br style="clear:both;" />

And with that I will move on to the real purpose of this tutorial, creating the settings page

==Setting up the settings page==
With the demystified theme set up it is time to create the settings page. This is where the real PHP fun begins.

For those of you who happen to be familiar with development of modules, blocks or other plugin types you have probably encountered settings pages before and this is not going to be any different.

However for those who haven't which I imagine is most of you this is going to be quite a challenge. I will try to walk through this step by step however if at any point you get stuck don't hesitate to ask in the forums as I imagine you will get a speedy response.

===How settings pages work in Moodle===
Settings pages can be used by nearly every plugin type, of which themes is of course one. The way in which it all works isn't too tricky to understand.

All of the settings for Moodle can be configured through the administrator interfaces when logged in. I am sure that everyone here has seen those pages and has changed a setting or two before so you will all know what I am talking about. Well the settings page for a theme is no different. It will be shown in the administration pages tree under '''Appearance > Themes''' and all we have to do is tell Moodle what settings there are.

This is done by creating a settings.php file within our theme into which we will add code that tells Moodle about the settings we want to add/use.

When telling Moodle about each setting we are simply creating a new ''admin_setting'' instance of the type we want and the properties we want and then adding it to our settings page.

There is really not much more too it at this level. Things can get very complex very fast so the best thing we can do now is start creating our settings.php file for the demystified theme and see where it leads us.

===Creating the settings page===
So as mentioned before we need a settings.php file which we will create now. To begin with create the file '''theme/demystified/settings.php''' and open it in your favourite editor so its ready to go.

Before we start adding code however lets just remember the settings that we want to create:
* change the background colour (CSS).
* set the path to an image that we will use as a logo on all pages (Layout files).
* override the width of the block regions (CSS).
* allow a note to be added to the footer of all pages (Layout files).
* allow custom CSS to be written to do anything the user wants. (CSS)

Alright.

Now thinking about this the first setting is as basic as it gets, all we need is a text box that the user can type a colour into.

The second is to allow a logo to be used in the header of each page. What we want here is a path but should it be a physical path e.g. C:/path/to/image.png or should it be a web path e.g. <nowiki>http://mysite.com/path/to/image.png</nowiki>?
For the purpose of this tutorial I am going to go with a web path because it is going to be easier to code and will hopefully be a little easier to understand to begin with.

The third setting is a little more complex. For this I want a drop down box with some specific widths that the administrator can select.

The forth and the fifth settings are both pretty straight forward, there we want a textarea into which the user can enter what ever they want and we will do something useful with it.

Now that we have an understanding about the settings we wish to define pull up your editor and lets start coding....

<code php>
<?php

/**
* Settings for the demystified theme
*/
defined('MOODLE_INTERNAL') || die;

if ($ADMIN->fulltree) {
</code>
This is the first bit of code we must enter, the first line is of course just the opening php tag, secondly we have a comment that describes this file, and then we get create a new '''admin_settingspage object'''.

This admin_settingspage object that we have just created is a representation of our settings page and is the what we add our new settings to. When creating it we give it two arguments, first the name of the page which is in this case '''theme_''themename''''' and the title for the page which we get with the get_string method.

At the moment I'm not going to worry about adding the string, we will get to that later once we have defined all of our settings.

====Background colour====

With the page now created lets add our first setting: Background colour.

<code php>
// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$setting = new admin_setting_configtext($name, $title, $description, $default, PARAM_CLEAN, 12);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
Thankfully this isn't as difficult as it initially looks.

The first line of code is creating a variable for the name of the background colour setting. In this case it is '''theme_demystified/backgroundcolor'''.

The name is very important, for the setting to be usable we have to follow a strict naming convention. '''theme_''themename''/''settingname''''' where '''''themename''''' is the name of the theme the setting belongs to and '''''settingname''''' is the name for the setting by which we will use it.

The second line of code creates a variable that contains the title of the setting. This is what the user sees to the right of the setting on the settings page and should be a short description of the setting. Here we are again using the ''get_string'' method so we will need to remember to add that string later on.

The third line of code sets the description. This should describe what the setting does or how it works and again we will use the get_string method.

The fourth line creates a variable that will be used as the default value for the setting. Because this setting is a colour we want an HTML colour to be the default value.

The fifth line is where we put it all together. Here we create a new '''admin_setting_configtext''' object. This object will represent the background colour setting.

When we create it we need to give it 6 different things.
# The name of the setting. In this case we have a variable '''$name'''.
# The title for this setting. We used the variable '''$title'''.
# The description of the setting '''$description'''.
# The default value for the setting. '''$default''' is the variable this.
# The type of value we want the user to enter. For this we have used PARAM_CLEAN which tells Moodle to get rid of any nasties from what the user enters.
# The size of the field. In our case 12 characters will be plenty.

The sixth and final line of code adds our newly created setting to the administration page we created earlier.

That is it we have successfully created and added our first setting, however there are several more to settings to do, and there are a couple of important things that you need to be aware of before we move on.

First: There are several different types of settings that you can create and add to a page, and each one may differ in what they need you to give them. In this case it was name, title, description, default, type, and size. However other settings will likely require different things. Smart editors like Netbeans or Eclipse can tell you what is required, otherwise you will need to research it.

Second: Normally settings are declared on one line as follows:
<code php>
$setting->add(new admin_setting_configtext('theme_demystified/backgroundcolor', get_string('backgroundcolor','theme_demystified'), get_string('backgroundcolordesc', 'theme_demystified'), '#DDD', PARAM_CLEAN, 12));
</code>
While this is structurally identical as all we have done is move everything onto one line and do away with the variables it is a little harder to read when you are learning all of this.

====The logo file====
Time to create the second setting that will allow the user to enter a URL to an image they wish to use as the logo on their site.
<code php>
// Logo file setting
$name = 'theme_demystified/logo';
$title = get_string('logo','theme_demystified');
$description = get_string('logodesc', 'theme_demystified');
$setting = new admin_setting_configtext($name, $title, $description, '', PARAM_URL);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
The first thing that you will notice about this setting that it is very similar to the first setting, in fact all we have changed is the name, title, description, and default value. We have however changed the value type from PARAM_CLEAN to PARAM_URL, this makes sure the user enters a URL. You will also notice that for this one we don't set a size for the field as we have no idea how long the URL will be.

====Block region width====
The third setting should allow the user to set a width for the block regions that will be used as columns.

For this setting I want to do something a little different from the previous two, here I want to use a select box so that the user selects a width for the column from a list I provide.
<code php>
// Block region width
$name = 'theme_demystified/regionwidth';
$title = get_string('regionwidth','theme_demystified');
$description = get_string('regionwidthdesc', 'theme_demystified');
$default = 200;
$choices = array(150=>'150px', 170=>'170px', 200=>'200px', 240=>'240px', 290=>'290px', 350=>'350px', 420=>'420px');
$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
So looking at the code: The first four lines you will recognise. $name, $title, $description, and $default are all being set.

The fifth line of code however introduces something new. Of course in order to have a select box we have to have options, in this case we have an array of options stored in the variable $choices.

The array of options is constructed of a collection of '''''value''' => '''label''''' pairs. Notice how we don't add '''px''' to the value. This is is very intentional as later on I need to do a little bit of math with that value so we need it to be a number.

The lines after should look familiar again, the only difference being that instead of a ''admin_setting_configtext'' setting we have created a ''admin_setting_configselect'' for which we must give the choices for the select box as the fifth argument.

Woohoo, we've just created our first select box setting.

====Foot note====
Now to create the foot note setting. Here we want the user to be able to enter some arbitrary text that will be used in the footer of the page. For this I want the user to be able to enter some HTML so I will create an editor setting.
<code php>
// Foot note setting
$name = 'theme_demystified/footnote';
$title = get_string('footnote','theme_demystified');
$description = get_string('footnotedesc', 'theme_demystified');
$setting = new admin_setting_confightmleditor($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
How simple is that!

It is just about identical to the first two settings except that for this we have created a ''admin_setting_confightmleditor'' setting rather than a text setting.

Note: You can also set the columns and rows for the editor setting using the fifth and sixth arguments.

====Custom CSS====
The final setting is to allow the user to add some custom CSS to the theme that will be used on every page. I want this to be a plain textarea into which the user can enter CSS.
<code php>
// Custom CSS file
$name = 'theme_demystified/customcss';
$title = get_string('customcss','theme_demystified');
$description = get_string('customcssdesc', 'theme_demystified');
$setting = new admin_setting_configtextarea($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
Just like the editor or text settings. It's getting very easy now!

====Finishing settings.php====
With all of our settings defined and added to our page that we created right at the beginning it is time to finish it all off.
<code php>
} // This is the closing brace that encloses all the above settings.
</code>
The above line is the final line for the page. It is adding the page that we have created '''$setting''' to the admin tree structure. In this case it is adding it to the themes branch.

The following is the completed source for our settings.php ..... for your copy/paste pleasure.
<div style='height:300px;overflow:auto;'>
<code php>
<?php
/**
* Settings for the demystified theme
*/
defined('MOODLE_INTERNAL') || die;

if ($ADMIN->fulltree) {

// Background colour setting
name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$setting = new admin_setting_configtext($name, $title, $description, $default, PARAM_CLEAN, 12);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);

// Logo file setting.
$name = 'theme_demystified/logo';
$title = get_string('logo','theme_demystified');
$description = get_string('logodesc', 'theme_demystified');
$setting = new admin_setting_configtext($name, $title, $description, '', PARAM_URL);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);

// Block region width.
$name = 'theme_demystified/regionwidth';
$title = get_string('regionwidth','theme_demystified');
$description = get_string('regionwidthdesc', 'theme_demystified');
$default = 200;
$choices = array(150=>'150px', 170=>'170px', 200=>'200px', 240=>'240px', 290=>'290px', 350=>'350px', 420=>'420px');
$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);

// Foot note setting.
$name = 'theme_demystified/footnote';
$title = get_string('footnote','theme_demystified');
$description = get_string('footnotedesc', 'theme_demystified');
$setting = new admin_setting_confightmleditor($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);

// Custom CSS file.
$name = 'theme_demystified/customcss';
$title = get_string('customcss','theme_demystified');
$description = get_string('customcssdesc', 'theme_demystified');
$setting = new admin_setting_configtextarea($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
}
</code>

===Creating a language file and adding our strings===
As I'm sure none of you have forgotten, throughout the creation of the our settings.php page, we used a lot of strings that I mentioned we would set later on. Well now is the time to set those strings.

First up create the following directories and file for our language strings:
* Directory '''theme/demystified/lang'''
* Directory '''theme/demystified/lang/en'''
* File '''theme/demystified/lang/theme_demystified.php'''

What we have created here is the required structure for Moodle to start looking for language strings.

First Moodle locates the lang directory, once found it looks within that directory for another directory that uses the character code for the language the user has selected, by default this is '''en''' for English. Once that is found it looks for the appropriate language file, in this case '''theme_demystified.php''' from which it will load all language strings for our theme.

If English isn't your chosen language simply replace the ''en'' directory with one that uses your chosen languages character code (two letters).

We can now add our language strings to '''theme/demystified/lang/theme_demystified.php'''. Copy and paste the following lines of PHP into this file.
<code php>
<?php

/**
* This file contains the strings used by the demystified theme
*/

$string['backgroundcolor'] = 'Background colour';
$string['backgroundcolordesc'] = 'This sets the background colour for the theme.';
$string['configtitle'] = 'Demystified theme';
$string['customcss'] = 'Custom CSS';
$string['customcssdesc'] = 'Any CSS you enter here will be added to every page allowing your to easily customise this theme.';
$string['footnote'] = 'Footnote';
$string['footnotedesc'] = 'The content from this textarea will be displayed in the footer of every page.';
$string['logo'] = 'Logo';
$string['logodesc'] = 'Enter the URL to an image to use as the logo for this site. Should be http://www.yoursite.com/path/to/logo.png';
$string['pluginname'] = 'Demystified';
$string['regionwidth'] = 'Column width';
$string['regionwidthdesc'] = 'This sets the width of the two block regions that form the left and right columns.';
</code>

In the above lines of code I have added an entry for each language string we used within ''settings.php''. When adding language strings like this make sure you use single quotes and try to keep things alphabetical - it helps greatly when managing strings.

Now when we view the settings page there will not be any errors or strings missing.

===Having a look at what we have created===
Now that we have created our settings page (settings.php) and added all of the language strings it is time to have a look at things in your browser.

Open your browser and enter the URL to your site. When you arrive at your site login as an administrator.

If you are not redirected to view the new settings change your URL to <nowiki>http://www.yoursite.com/admin/</nowiki> and your will see a screen to set the new theme settings we have just created. This lets us know that everything has worked correctly.

At any point now you are able to log in as administrator and within the settings block browse to '''Site administration > Appearance > Themes > Demystified theme''' to change those settings.

The screenshot below shows you what you should see at this point:

[[Image:Theme.settings.page.03.png|715px|thumb|left|The settings page we just created]]
<br style="clear:both;" />

==Using the settings in CSS==
With the settings page now created and operational it is time to make use of our new settings. The settings that we want to use within our CSS is as follows:

; backgroundcolor : Will be used to set the background colour in CSS.
; regionwidth : Will be the width of the column for CSS.
; customcss : Will be some custom CSS to add to our stylesheet.

At this point those names are the names we used for our setting with the slash and everything before it having been removed.

Before we start tearing into some code it is important that we have a look at what we are going to do and how we are going to go about it.

===How it all works within Moodle===
The first thing to understand is that while Moodle allows you to create a settings page and automates it inclusion and management right into the administration interfaces there is no smart equivalent for using the settings. This is simply because there is no way to predict how people will want to use the settings.

However don't think of this as a disadvantage, in fact it is quite the contrary. Although we can't just ''use'' our settings we can take full control over how and where we use them. It means it will take a little more code but in the end that will work to our advantage as we can do anything we want.

Moodle does help us out a little but not in an obvious way. The first thing that Moodle does is look for a config variable '''csspostprocess''' that should be the name of a function which we want called to make any changes to the CSS after it has been prepared.

The second thing Moodle does is include a lib.php from the theme's directory if one exists (also for the themes the current theme extends.) which ensures that as long as we write our code within '''theme/demystified/lib.php''' it will be included and ready to be used.

The third and final thing Moodle does that will help us out here is ensure that by the time any of code is ready to execute the settings have been prepared and are ready to be used within a theme config object which is passed into our ''csspostprocess'' function.

===Our plan===
As you have already probably guessed we will need to create a function to make the changes to the CSS that we want. We will then set the theme config option '''$THEME->csspostprocess''' to the name of our function.

By doing this when Moodle builds the CSS file it will call our function afterwards with the CSS and the theme object that contains our setting.

Now we know that we will use the ''csspostprocess'' function but how are we going to change the CSS, we could get the function to add CSS, or we could get the function to replace something within the CSS. My personal preference is to replace something within the CSS, just like what is happening with images. If you want to use an image within CSS you would write <nowiki>[[pix:theme|imagename]]</nowiki>.

For settings I am going to use <nowiki>[[setting:settingname]]</nowiki>, this way it looks a bit like something you are already familiar with.

What we need to decide upon next is the best way in which to replace our settings tag with the settings that the user has set.

There are two immediate options available to us:
# Make the ''csspostprocess'' function do all the work.
# Make the ''csspostprocess'' function call a separate function for each setting.
Solution 1 might sound like the simplest however it is going to result in a '''VERY''' complex function. Remember the user might have left settings blank or entered something that wouldn't be valid so we would need to make the sure there is some validation and a good default.
Because of this I think that solution 2 is the better solution.

So we are going to need a ''csspostprocess'' function and then a function for each of the three settings we have that will do the replacements.
<code php>
// This is our css post process function
function demystified_process_css($css, $theme) {};
// This replaces [[setting:backgroundcolor]] with the background colour
function demystified_set_backgroundcolor($css, $backgroundcolor) {};
// This replaces [[setting:regionwidth]] with the correct region width
function demystified_set_regionwidth() {$css, $regionwidth};
// This replaces [[setting:customcss]] with the custom css
function demystified_set_customcss() {$css, $customcss};
</code>

What you should note about the above functions is that they all start with the theme's name. This is required to ensure that the functions are named uniquely as it is VERY unlikely that someone has already created these functions.

So with our plan set out lets start writing the code.

===Writing the code===
The very first thing that we need to do is create a lib.php for our theme into which our css processing functions are going to go. So please at this point create '''theme/demystified/lib.php''' and open it in your editor ready to go.

The first bit of code we have to write is the function that will be called by Moodle to do the processing '''demystified_process_css'''.

Before we start out please remember that the wonderful thing about coding is that there is any number of solutions to a problem. The solutions that you are seeing here in this tutorial are solutions that I have come up with to meet fulfil the needs of the tutorial without being so complex that they are hard to understand. This probably isn't how I would go about it normally but this is a little easier to understand for those who aren't overly familiar with PHP and object orientation.

====The function: demystified_process_css====

<code php>
function demystified_process_css($css, $theme) {

if (!empty($theme->settings->backgroundcolor)) {
$backgroundcolor = $theme->settings->backgroundcolor;
} else {
$backgroundcolor = null;
}
$css = demystified_set_backgroundcolor($css, $backgroundcolor);

if (!empty($theme->settings->regionwidth)) {
$regionwidth = $theme->settings->regionwidth;
} else {
$regionwidth = null;
}
$css = demystified_set_regionwidth($css, $regionwidth);

if (!empty($theme->settings->customcss)) {
$customcss = $theme->settings->customcss;
} else {
$customcss = null;
}
$css = demystified_set_customcss($css, $customcss);

return $css;
}
</code>

So lets look at the things that make up this function:

<code php>
function demystified_process_css($css, $theme) {
//.....
return $css
}
</code>

This of course is the function declaration.

The function gets given two variables, the first '''$css''' is a pile of CSS as one big string, and the second is the theme object '''$theme''' that contains all of the configuration, options, and settings for our theme.

It then returns the ''$css'' variable, essentially returning the modified CSS.

<code php>
//...
if (!empty($theme->settings->backgroundcolor)) {
$backgroundcolor = $theme->settings->backgroundcolor;
} else {
$backgroundcolor = null;
}
$css = demystified_set_backgroundcolor($css, $backgroundcolor);
//...
</code>

Here we are processing our first setting ''backgroundcolor''.

The first thing that we need to do is check whether it has been set and whether it has a value. If it has then we store that value in '''$backgroundcolor'''. It is doesn't have a value then we set ''$backgroundcolor'' to null. This ensures that ''$backgroundcolor'' is set because if it isn't then you are going to get a notice (if you have debugging on).

The final line of this block calls the function '''demystified_set_backgroundcolor'''. We haven't written this function yet but we will shortly. When we call it we give it the ''$css'' variable that contains all of the CSS and we give it the background colour variable ''$backgroundcolor''. Once this function is finished it returns the ''$css'' variable with all of the changes made much like how our css processing function works.

What you should also note about this code is this:
<code php>
$theme->settings->backgroundcolor
</code>
As mentioned earlier ''$theme'' is an object that contains all of the configuration and settings for our theme. The ''$theme'' object has a $settings property which contains all of the settings for our theme, and finally the settings property contains a variable backgroundcolor that is the value the user entered for that setting. That is how we get a settings value.

<code php>
if (!empty($theme->settings->regionwidth)) {
$regionwidth = $theme->settings->regionwidth;
} else {
$regionwidth = null;
}
$css = demystified_set_regionwidth($css, $regionwidth);

if (!empty($theme->settings->customcss)) {
$customcss = $theme->settings->customcss;
} else {
$customcss = null;
}
$css = demystified_set_customcss($css, $customcss);
</code>

These two routines are nearly identical to the routine above. For both the regionwidth and the customcss we make sure it has a value and then store it in a variable. We then call the relevant function to make the changes for that setting.

Now that we have the general processing function it is time to write the three functions we have used but not written, ''demystified_set_backgroundcolor'', ''demystified_set_regionwidth'', ''demystified_set_customcss''.

====The function: demystified_set_backgroundcolor====

First up demystified_set_backgroundcolor.

<code php>
/**
* Sets the background colour variable in CSS
*
* @param string $css
* @param mixed $backgroundcolor
* @return string
*/
function demystified_set_backgroundcolor($css, $backgroundcolor) {
$tag = '[[setting:backgroundcolor]]';
$replacement = $backgroundcolor;
if (is_null($replacement)) {
$replacement = '#DDDDDD';
}
$css = str_replace($tag, $replacement, $css);
return $css;
}
</code>

Ok so what is happening here?

First we need a variable '''$tag''' that contains the tag we are going to replace. As mentioned earlier we are going to use tags that look like the image tags you are already familiar with ''<nowiki>[[setting:settingname]]</nowiki>'', in this case ''<nowiki>[[setting:backgroundcolor]]</nowiki>''.

Next I am going to create a variable called '''$replacement''' into which I put '''$backgroundcolor'''.

The '''IF''' statement that comes next checks ''$replacement'' to make sure it is not null. If it is then we need to set it to a default value. In this case I have used ''#DDD'' as that was the default for the settings.

The line after the IF statement puts it all together. The ''str_replace'' function that we are calling takes three arguments in this order:
# The text to search for.
# The text to replace it with.
# The text to do the replacement in.
It then returns the text with all of the replacements made. So in this case we are replacing the tag with the background colour and it is returning the changed CSS.

The final thing is to return the ''$css'' variable which now contains the correct background colour.

====The function: demystified_set_regionwidth====

Next we have the demystified_set_regionwidth function.
<code php>
/**
* Sets the region width variable in CSS
*
* @param string $css
* @param mixed $regionwidth
* @return string
*/
function demystified_set_regionwidth($css, $regionwidth) {
$tag = '[[setting:regionwidth]]';
$doubletag = '[[setting:regionwidthdouble]]';
$replacement = $regionwidth;
if (is_null($replacement)) {
$replacement = 200;
}
$css = str_replace($tag, $replacement.'px', $css);
$css = str_replace($doubletag, ($replacement*2).'px', $css);
return $css;
}
</code>

This function is very similar to the above function however there is one key thing we are doing different. We are doing two replacements.

# The first replacement is for the width that the user selected. In this case I am replacing the tag ''<nowiki>[[setting:regionwidth]]</nowiki>'' with the width.
# The second replacement is for the width x 2. This is because the page layout requires that the width be doubled for some of the CSS. Here I will replace ''<nowiki>[[setting:regionwidthdouble]]</nowiki>'' with the doubled width.

Remember because it is still just a number we need to add '''px''' to the end of each before we do the replacement.

So the overall process of this function is:
# Define the two tags as '''$tag''' and '''$doubletag'''.
# Make '''$replacement''' the region width ''$regionwidth''.
# Set ''$replacement'' to a default value of 200 is it is null.
# Replace '''<nowiki>[[setting:regionwidth]]</nowiki>''' with the width.
# Replace '''<nowiki>[[setting:regionwidthdouble]]</nowiki>''' with the width x 2.
# Return the changed CSS.

====The function: demystified_set_customcss====

The final function that we need to write is the demystified_set_customcss function.
<code php>
/**
* Sets the custom css variable in CSS
*
* @param string $css
* @param mixed $customcss
* @return string
*/
function demystified_set_customcss($css, $customcss) {
$tag = '[[setting:customcss]]';
$replacement = $customcss;
if (is_null($replacement)) {
$replacement = '';
}
$css = str_replace($tag, $replacement, $css);
return $css;
}
</code>

This function is just like the first function. I'm going to let you work it out on your own.

And that is it no more PHP... Hallelujah I can hear you yelling. The final thing we need to do is tell our theme about the functions we have written and put the settings tags into the CSS.

===Finishing it all off===

So there are two things we have to do in order to complete this section and have our the settings page implemented and our settings being used.

First we need to tell our theme that we want to use the function ''demystified_process_css'' as the ''csspostprocess'' function. This is done very simply by adding the following line of PHP to the bottom of our theme's config.php file '''theme/demystified/config.php'''.

<code php>
$THEME->csspostprocess = 'demystified_process_css';
</code>

With that done the only thing left is to add the settings tag into the CSS. Remember those settings tags are:

; <nowiki>[[setting:backgroundcolor]]</nowiki> : We need to add this where ever we want the background colour setting to be used.
; <nowiki>[[setting:regionwidth]]</nowiki> : We need to add this where ever we want to set the width of the block regions.
; <nowiki>[[setting:regionwidthdouble]]</nowiki> : We need to add this where ever we want to set the doubled width of the block regions.
; <nowiki>[[setting:customcss]]</nowiki> : We need to add this to the bottom of the CSS file that we want the custom CSS added to.

So lets make those changes in CSS now, open up your ''core.css'' file and replace the CSS with the CSS below:
<code css>
/** Background color is a setting **/
html {background-color:[[setting:backgroundcolor]];}
body {margin:30px;padding:0;border:1px solid #333;border-width:0 10px 0 10px;background-color:#333;}
body #page {background-color:#FFF;position:relative;top:-10px;}
.block .header {background-image:none;background-color:#0C5CAC;border:1px solid #0C5CAC;color:#FFF;}
.block {border-color:#4BA7FF;background-color:#DDEEFF;}
.block .content {background-color:#F1F8FF;}
a:link,
a:visited {color:#0C5CAC;}
a:hover {color:#C77500;}
#page #page-header {background-color:#0C5CAC;margin:0;padding:0;width:100%;color:#fff;}
#page #page-header a:link, #page #page-header a:visited {color:#FFAC02}
#page #page-header .navbar, #page #page-header .navbar a:link, #page #page-header .navbar a:visited {color:#0C5CAC;}
/** Override the region width **/
#page-content #region-main-box {left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidthdouble]];}
#page-content #region-main-box #region-post-box #region-pre {width:[[setting:regionwidth]];left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-post {width:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidthdouble]];}
.side-pre-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-pre-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
/** Custom CSS **/
[[setting:customcss]]
</code>

You will notice that <nowiki>[[setting:backgroundcolor]]</nowiki> has been used for the html tags background colour:
<code css>
html {background-color:[[setting:backgroundcolor]];}
</code>

We have also set the width of the block regions by adding <nowiki>[[setting:regionwidth]]</nowiki> as the width for region-pre and region-post as shown below:
<code css>
#page-content #region-main-box {left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidthdouble]];}
#page-content #region-main-box #region-post-box #region-pre {width:[[setting:regionwidth]];left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-post {width:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidthdouble]];}
.side-pre-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-pre-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
</code>
You'll notice here that we have to set several different widths and margins using the regionwidth setting and make use of the special regionwidthdouble setting that we added.

The final thing that we did was add the <nowiki>[[setting:customcss]]</nowiki> to the bottom of the file to ensure that the custom CSS comes last (and therefore can override all other CSS).

And with that we are finished. The screenshot below shows how this now looks in the browser if I set the background colour setting to '''<span style='color:#FFA800;'>#FFA800</span>''' and made the column width 240px;

[[Image:Theme.settings.page.04.png|715px|thumb|left|Our settings in action]]<br style="clear:both;" />

==Using the settings within our layout files==
Now that we have utilised the first three settings within our theme's CSS file it is time to implement the other two settings within the layout files so that they are written directly into the page.

You'll be glad to know this is no where near as difficult as utilising settings within a CSS file although it still does require a little bit of PHP.

First up is the logo setting. Into this setting the user is able to enter the URL to an image to use as the logo for the site. In my case I want this to be just a background logo on top of which I want to position the page header.

Before I start there is one thing I need to do however and that is create a default logo background that gets shown if the user hasn't set a specific logo file. To do this I simply created an image '''logo.jpg''' and put it into a pix directory within the demystified theme. You should end up with '''theme/demystified/pix/logo.jpg'''.

Next open up the front-page layout file ''theme/demystified/layout/frontpage.php''. At the top of the file is the PHP that checks what blocks regions the page has and a bit of other stuff. Well right below the existing bit of PHP we want to add the following code:
<code php>
if (!empty($PAGE->theme->settings->logo)) {
$logourl = $PAGE->theme->settings->logo;
} else {
$logourl = $OUTPUT->pix_url('logo', 'theme');
}
</code>
What we are doing here is creating a variable called $logourl that will contain the URL to a logo file that was either entered by the user or if they left it blank is that of our default logo file.

There are two things that you should notice about this. First the logo setting can be retrieved through '''$PAGE->theme->settings->logo''' and second we get the default logo url by calling '''$OUTPUT->pix_url('logo', 'theme')'''.

Now that we have the logo URL we are going to use we need to add an image to the header section of the page as shown below:
<code php>
<div id="page-header" class="clearfix">
<img class="sitelogo" src="<?php echo $logourl;?>" alt="Custom logo here" />
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
....
</code>

If you save that and browse to your sites front page you will notice that the logo file is now being shown. Hooray. However it is probably not styled too nicely so lets quickly fix that. Open up the core.css file and add the following lines of CSS to the bottom of the file.
<code css>
#page-header {position:relative;min-height:100px;}
#page-header .sitelogo {float:left;}
#page-header .headermain {position:absolute;left:0.5em;top:50px;margin:0;float:none;font-size:40px;}
</code>
These three lines position the image correctly and if you now refresh everything should appear perfectly.

With the logo done the last setting we need to deal with is the footnote setting. The idea with this setting was that the administrator could enter some text into the editor and it would be displayed in the footer of the page.

This is probably the easiest setting to implement.

Within the front page layout file that we edited above add the following lines below those we added previously.

<code php>
if (!empty($PAGE->theme->settings->footnote)) {
$footnote = $PAGE->theme->settings->footnote;
} else {
$footnote = '';
}
</code>

Here we are just collecting the footnote into a variable '''$footnote''' and setting a default footnote comment if the user hasn't entered one.

We can now echo the $footnote variable within the page footer. This can be done as shown below.

<code php>

<div id="page-footer">
<div class="footnote"><?php echo $footnote; ?></div>
<p class="helplink">
<?php echo page_doc_link(get_string('moodledocslink')) ?>
</p>
</code>

And with that done we are finished! Congratulations if you got this far.

The screenshot below shows the demystified theme we have just created that is styled by the settings page.

[[Image:Theme.settings.page.05.png|715px|thumb|left|My finished demystified theme]]<br style="clear:both" />

==Testing our creation==
Congratulations to you! If you've made it this far you have done very well. Now it is time to have a look at what we have created and give it a quick test run.

So in this tutorial we have achieved the following:

* We created a theme called demystified that is based on the standard theme.
* We added a settings page to our new theme.
* We added the following settings to our settings page:
** We can set a background colour through the admin interface.
** We can change the logo of the site.
** We can change the block region width.
** We can add a footnote to the page footer
** We can add some custom CSS to seal the deal.
* Those settings were then used in the CSS files for our theme.
* They were also used in the layout files for our theme.
* And here we are testing it all.

The screenshots below show my testing process and I change each setting and view the outcome. The great thing about this is that with theme designer mode on you see the changes as soon as the form refreshes.

[[Image:Theme.settings.page.06.png|300px|thumb|left|Default settings]]
[[Image:Theme.settings.page.07.png|300px|thumb|left|Changed the background colour setting]]
[[Image:Theme.settings.page.08.png|300px|thumb|left|Changed the logo and region width]]
[[Image:Theme.settings.page.09.png|300px|thumb|left|Added a footnote]]
[[Image:Theme.settings.page.10.png|300px|thumb|left|Added some custom CSS]]
<br style="clear:both" />

==The different settings you can use==
During this tutorial we use four different kinds of settings, a text box, text area, a select (dropdown) and the editor however as I'm sure you have all guessed there is many more some of which will certainly be useful for theme settings.

The following are examples of some of the different settings. I should add that these build upon what we have already done within the tutorial but are not included in the download.

===Colour picker===
[[Image:Theme.settings.page.11.png|400px|thumb|The colour picker]]
I can hear you all asking now 'Why didn't you mention this one earlier?' well the answer is simple it didn't exist when I first wrote the tutorial. It is an admin setting that I wrote several days after because of the fantastic effort people were putting into trying out settings pages.

A bit about the colour picker. First up it is a text box that when the page loads turns into a colour picker that can be used to select a colour and can even preview the selected colour in the page (by clicking the preview button). It is designed to be very easy to use and the code is just about as simple as creating a normal text box setting.

In the image to the left I have replaced the background colour setting we created during the tutorial with the colour picker. Lets have a look at the code involved for that.
<code php>
// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$previewconfig = array('selector'=>'html', 'style'=>'backgroundColor');
$setting = new admin_setting_configcolourpicker($name, $title, $description, $default, $previewconfig);
$temp->add($setting);
</code>
So first thing you should notice is that the first four lines of code have not changed at all!

The first change we have is to create a variable '''$previewconfig'''.
This variable is used to tell the colour picker what to do when the user clicks the preview button. It should be an array that contains two things, first a selector, and second a style.
# The selector is a CSS selector like ''.page .header h2''.
# The style is a what should change, there are two immediate values it can be, either '''backgroundColor''' or '''color'''.
In my case the selector is '''html''' to target the html tag and the style is backgroundColor to change the background colour.

The second change is to use '''admin_setting_configcolourpicker''' instead of ''admin_setting_configtext''. The arguments are nearly identical as well except that there is an extra argument to which we give the '''$previewconfig''' variable.

And that is it! it is all you need to get the colour picker up and running.

'''Extra note:''' The $previewconfig variable is optional. If you don't want a preview button the simply set ''$previewconfig = null''

==Common pitfalls and useful notes==

This section is really just a collection of pointers, tips, notes, and other short useful stuff that may be of use to those attempting this tutorial.

# First up and most importantly there are very few limitations to what you achieve in this fashion.
# If you get stuck or need a hand ask in the forums, there's always someone round who can help.
# If you do something really cool let us know, I know everyone in the community loves finding our what others are achieving.
# You don't have to use ''admin_settingpage'' you can also use '''admin_externalpage''' if you prefer. It should be noted however that it is not the preferred way to do it as admin_externalpage's were only left in Moodle 2.0 for backwards compatibility (although they are more flexible one day they will be deprecated or removed). Thank you to Darryl for raising this.
# If you find that your language strings aren't being used (you are getting language string notices) and you have double checked that you have turned '''langstringcache''' off then you may need to delete the language cache directory. This is located in the moodledata directory for you installation: moodledata/cache/lang/*. You should delete the directory for your chosen language by default ''en''.

==See also==

* [[Adding theme upgrade code]]
* [[Styling and customising the dock]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=152053 Theme 2.0: Adding a settings page to your theme] forum discussion

Creating a theme settings page

2014-09-24T22:33:30Z

Tqr: /* Finishing settings.php */

{{Template:Themes}}This document looks at how to create a settings page for your Moodle 2.x.x theme and how to make use of those settings within the CSS and layout files for your theme.

This is a pretty advanced topic and will require that you have at least an intermediate knowledge of PHP, CSS, and development in general.

==Before we begin==
[[Image:Theme.settings.page.03.png|350px|thumb|Our end goal. The settings page.]]
[[Image:Theme.settings.page.10.png|350px|thumb|And what it can do.]]
There is a huge body of knowledge that we must cover in following through this document and as such I think the best way to write this is as a tutorial.

My intentions for this tutorial are to replicate the standard theme but with a settings page that allows the administrator to set a background colour, set a logo to use with the page, and probably several other minor settings to change the way in which the theme is displayed.

I will start this tutorial by creating a new theme which will be largely a copy/paste of the current standard theme. I expect that anyone working through this tutorial has previously read the tutorial I wrote on [[Themes 2.0 creating your first theme|creating your first theme]]. If you haven't go read it now because I'm not going to go into much detail until we get to the actual process of customising the theme and introducing the settings page.

So before we finally get this started please ensure you can check off everything on the following requirements list.
* Have a Moodle installation that has already been installed and configured and is ready to use.
* Have full read/write access to that installation.
* Be prepared to delete that installation at the end of this... we will destroy it!
* Have a development environment prepared and ready to use. This includes:
** Your favourite editor installed, running, and pointed at the themes directory of your installation.
** Your browser open and your site visible.
** A bottomless coffee pot... decaf won't help you with this one.
* Have set the following settings:
** '''themedesignermode''' if you don't know what this is please read the [[Themes 2.0 creating your first theme|creating your first theme]] tutorial.
** '''allowthemechangeonurl''' turn this on, it allows you to change themes on the URL and is very handy when developing themes. ''Site Administration > Appearance > Themes > Theme settings''
** '''langstringcache''' if you don't turn this off you won't see your strings when they are added. ''Site Administration > Language > Language settings''
* And finally an insane ambition to create a customisable theme.

For those interested the theme that I create throughout this tutorial can be downloaded from the forum post in which I announce this document: http://moodle.org/mod/forum/discuss.php?d=152053
<br style="clear:right;" />

==Our goals for this tutorial==
The following is just a list goals that I hope to achieve during this tutorial. They are laid out here so that I can easily refer back to them and so that you can easily find them.
# Create a new theme called '''demystified''' based upon the standard theme within Moodle 2.0.
# Make some minor changes to that theme to allow us to more easily see what is going on.
# Create a settings page for the demystified theme.
# Add several settings to our settings page.
# Use some of those settings to alter our CSS.
# Use the rest of those settings within our layout file..
# Discuss the good, the bad, and limits of what we have just created.

So I can see you are all very excited about this point and that you would love to know what settings we are going to create; So here they are:

A setting to ...
* change the background colour (CSS).
* set the path to an image that we will use as a logo on all pages (Layout files).
* override the width of the block regions (CSS).
* allow a note to be added to the footer of all pages (Layout files).
* allow custom CSS to be written to do anything the user wants. (CSS)

==Creating the demystified theme==
Before we start here I want to remind you that I am going to look at this only briefly as I am making the assumption that you have read the [[Themes 2.0 creating your first theme|creating your first theme]] tutorial.

Well lets get into it....

The first thing we need to do is create a directory for our theme which we will call demystified.

So within your Moodle directory create the following folder '''moodle/theme/demystified'''. At the same time you can also create the following files and folders which we will get to soon.
* The file '''moodle/theme/demystified/config.php''' for our config information.
* The directory '''moodle/theme/demystified/layout''' for our layout files.
* The directory '''moodle/theme/demystified/style''' for our css files.
* The file '''moodle/theme/demystified/style/core.css''' which will contain our special CSS.

Next we will copy the layout files from the base theme to our new theme demystified. We are basing the demystified theme on the standard theme however that doesn't use it's own layout files it uses the base theme's layout files so those are the ones we want.

The reason that we are coping these layout files is that later on in this tutorial we will be modifying them to make use of our new settings... so copy all of the layout files from '''moodle/theme/base/layout''' to '''moodle/theme/demystified/layout'''.

There should be three files that you just copied:
# embedded.php
# frontpage.php
# general.php

Now we need to populate demystified/config.php with the settings for our new theme. They are as follows:
<code php>
$THEME->name = 'demystified';
</code>
Simply sets the name of our theme.

<code php>
$THEME->parents = array('standard','base');
</code>
This theme is extending both the standard theme and the base theme. Remember when extending a theme you also need to extend its parents or things might not work correctly.

<code php>
$THEME->sheets = array('core');
</code>
This tells our theme that we want to use the file '''demystified/style/core.css''' with this theme.

<div style="height:300px;overflow-y:scroll;">
<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-post',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'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),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>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),
),
// 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),
),
);
</code>
</div>
Now that all looks very complicated however its really not too bad as it is just copied from the base theme's config.php file. We can do this because we copied the layout files from the base theme to begin with and for the time being there are no changes that we wish to make. Simply open up '''theme/base/config.php''' and copy the layouts from there.

And that is it. The config.php file for our demystified theme is complete. The full source is shown below:
<div style="height:300px;overflow-y:scroll;">
<code php>
<?php

// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* The demystified theme config file
*
* This theme was created to document the process of adding a settings page to a theme
*
* @copyright 2010 Sam Hemelryk
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

// The name of our theme
$THEME->name = 'demystified';

// The other themes this theme extends
$THEME->parents = array('standard','base');

// The CSS files this theme uses (located in the style directory)
$THEME->sheets = array('core');

// The layout definitions for this theme
$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-post',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'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),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>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),
),
// 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),
),
);
</code>
</div>

The screenshot below shows both the directory structure we have now created and the theme presently.

[[Image:Theme.settings.page.01.png]]

To view the theme so far open you browser and enter the URL of your site followed by '''?theme=demystified'''. You should see the theme that we just created which will look exactly like the base standard theme.

The final thing that we want to do is add a little bit of CSS to the demystified theme that will both visually set this theme apart from the standard theme and second build a the base which our settings can later extend.

I added the following snippet of CSS to the file '''demystified/style/core.css'''.
<code css>
html {background-color:#DDD;}
body {margin:30px;padding:0;border:1px solid #333;border-width:0 10px 0 10px;background-color:#333;}
body #page {background-color:#FFF;position:relative;top:-10px;}
.block .header {background-image:none;background-color:#0C5CAC;border:1px solid #0C5CAC;color:#FFF;}
.block {border-color:#4BA7FF;background-color:#DDEEFF;}
.block .content {background-color:#F1F8FF;}
a:link,
a:visited {color:#0C5CAC;}
a:hover {color:#C77500;}
#page #page-header {background-color:#0C5CAC;margin:0;padding:0;width:100%;color:#fff;}
#page #page-header a:link, #page #page-header a:visited {color:#FFAC02}
#page #page-header .navbar, #page #page-header .navbar a:link, #page #page-header .navbar a:visited {color:#0C5CAC;}
</code>

The CSS that we have just added to our theme sets a couple of colours on the front page. Presently this is the only CSS I will add, I know it isn't complete by any means but it achieves it's purpose as the screenshot below illustrates.

[[Image:Theme.settings.page.02.png|715px|thumb|left|The newly styles demystified theme]]<br style="clear:both;" />

And with that I will move on to the real purpose of this tutorial, creating the settings page

==Setting up the settings page==
With the demystified theme set up it is time to create the settings page. This is where the real PHP fun begins.

For those of you who happen to be familiar with development of modules, blocks or other plugin types you have probably encountered settings pages before and this is not going to be any different.

However for those who haven't which I imagine is most of you this is going to be quite a challenge. I will try to walk through this step by step however if at any point you get stuck don't hesitate to ask in the forums as I imagine you will get a speedy response.

===How settings pages work in Moodle===
Settings pages can be used by nearly every plugin type, of which themes is of course one. The way in which it all works isn't too tricky to understand.

All of the settings for Moodle can be configured through the administrator interfaces when logged in. I am sure that everyone here has seen those pages and has changed a setting or two before so you will all know what I am talking about. Well the settings page for a theme is no different. It will be shown in the administration pages tree under '''Appearance > Themes''' and all we have to do is tell Moodle what settings there are.

This is done by creating a settings.php file within our theme into which we will add code that tells Moodle about the settings we want to add/use.

When telling Moodle about each setting we are simply creating a new ''admin_setting'' instance of the type we want and the properties we want and then adding it to our settings page.

There is really not much more too it at this level. Things can get very complex very fast so the best thing we can do now is start creating our settings.php file for the demystified theme and see where it leads us.

===Creating the settings page===
So as mentioned before we need a settings.php file which we will create now. To begin with create the file '''theme/demystified/settings.php''' and open it in your favourite editor so its ready to go.

Before we start adding code however lets just remember the settings that we want to create:
* change the background colour (CSS).
* set the path to an image that we will use as a logo on all pages (Layout files).
* override the width of the block regions (CSS).
* allow a note to be added to the footer of all pages (Layout files).
* allow custom CSS to be written to do anything the user wants. (CSS)

Alright.

Now thinking about this the first setting is as basic as it gets, all we need is a text box that the user can type a colour into.

The second is to allow a logo to be used in the header of each page. What we want here is a path but should it be a physical path e.g. C:/path/to/image.png or should it be a web path e.g. <nowiki>http://mysite.com/path/to/image.png</nowiki>?
For the purpose of this tutorial I am going to go with a web path because it is going to be easier to code and will hopefully be a little easier to understand to begin with.

The third setting is a little more complex. For this I want a drop down box with some specific widths that the administrator can select.

The forth and the fifth settings are both pretty straight forward, there we want a textarea into which the user can enter what ever they want and we will do something useful with it.

Now that we have an understanding about the settings we wish to define pull up your editor and lets start coding....

<code php>
<?php

/**
* Settings for the demystified theme
*/
defined('MOODLE_INTERNAL') || die;

if ($ADMIN->fulltree) {
</code>
This is the first bit of code we must enter, the first line is of course just the opening php tag, secondly we have a comment that describes this file, and then we get create a new '''admin_settingspage object'''.

This admin_settingspage object that we have just created is a representation of our settings page and is the what we add our new settings to. When creating it we give it two arguments, first the name of the page which is in this case '''theme_''themename''''' and the title for the page which we get with the get_string method.

At the moment I'm not going to worry about adding the string, we will get to that later once we have defined all of our settings.

====Background colour====

With the page now created lets add our first setting: Background colour.

<code php>
// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$setting = new admin_setting_configtext($name, $title, $description, $default, PARAM_CLEAN, 12);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
Thankfully this isn't as difficult as it initially looks.

The first line of code is creating a variable for the name of the background colour setting. In this case it is '''theme_demystified/backgroundcolor'''.

The name is very important, for the setting to be usable we have to follow a strict naming convention. '''theme_''themename''/''settingname''''' where '''''themename''''' is the name of the theme the setting belongs to and '''''settingname''''' is the name for the setting by which we will use it.

The second line of code creates a variable that contains the title of the setting. This is what the user sees to the right of the setting on the settings page and should be a short description of the setting. Here we are again using the ''get_string'' method so we will need to remember to add that string later on.

The third line of code sets the description. This should describe what the setting does or how it works and again we will use the get_string method.

The fourth line creates a variable that will be used as the default value for the setting. Because this setting is a colour we want an HTML colour to be the default value.

The fifth line is where we put it all together. Here we create a new '''admin_setting_configtext''' object. This object will represent the background colour setting.

When we create it we need to give it 6 different things.
# The name of the setting. In this case we have a variable '''$name'''.
# The title for this setting. We used the variable '''$title'''.
# The description of the setting '''$description'''.
# The default value for the setting. '''$default''' is the variable this.
# The type of value we want the user to enter. For this we have used PARAM_CLEAN which tells Moodle to get rid of any nasties from what the user enters.
# The size of the field. In our case 12 characters will be plenty.

The sixth and final line of code adds our newly created setting to the administration page we created earlier.

That is it we have successfully created and added our first setting, however there are several more to settings to do, and there are a couple of important things that you need to be aware of before we move on.

First: There are several different types of settings that you can create and add to a page, and each one may differ in what they need you to give them. In this case it was name, title, description, default, type, and size. However other settings will likely require different things. Smart editors like Netbeans or Eclipse can tell you what is required, otherwise you will need to research it.

Second: Normally settings are declared on one line as follows:
<code php>
$setting->add(new admin_setting_configtext('theme_demystified/backgroundcolor', get_string('backgroundcolor','theme_demystified'), get_string('backgroundcolordesc', 'theme_demystified'), '#DDD', PARAM_CLEAN, 12));
</code>
While this is structurally identical as all we have done is move everything onto one line and do away with the variables it is a little harder to read when you are learning all of this.

====The logo file====
Time to create the second setting that will allow the user to enter a URL to an image they wish to use as the logo on their site.
<code php>
// Logo file setting
$name = 'theme_demystified/logo';
$title = get_string('logo','theme_demystified');
$description = get_string('logodesc', 'theme_demystified');
$setting = new admin_setting_configtext($name, $title, $description, '', PARAM_URL);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
The first thing that you will notice about this setting that it is very similar to the first setting, in fact all we have changed is the name, title, description, and default value. We have however changed the value type from PARAM_CLEAN to PARAM_URL, this makes sure the user enters a URL. You will also notice that for this one we don't set a size for the field as we have no idea how long the URL will be.

====Block region width====
The third setting should allow the user to set a width for the block regions that will be used as columns.

For this setting I want to do something a little different from the previous two, here I want to use a select box so that the user selects a width for the column from a list I provide.
<code php>
// Block region width
$name = 'theme_demystified/regionwidth';
$title = get_string('regionwidth','theme_demystified');
$description = get_string('regionwidthdesc', 'theme_demystified');
$default = 200;
$choices = array(150=>'150px', 170=>'170px', 200=>'200px', 240=>'240px', 290=>'290px', 350=>'350px', 420=>'420px');
$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
So looking at the code: The first four lines you will recognise. $name, $title, $description, and $default are all being set.

The fifth line of code however introduces something new. Of course in order to have a select box we have to have options, in this case we have an array of options stored in the variable $choices.

The array of options is constructed of a collection of '''''value''' => '''label''''' pairs. Notice how we don't add '''px''' to the value. This is is very intentional as later on I need to do a little bit of math with that value so we need it to be a number.

The lines after should look familiar again, the only difference being that instead of a ''admin_setting_configtext'' setting we have created a ''admin_setting_configselect'' for which we must give the choices for the select box as the fifth argument.

Woohoo, we've just created our first select box setting.

====Foot note====
Now to create the foot note setting. Here we want the user to be able to enter some arbitrary text that will be used in the footer of the page. For this I want the user to be able to enter some HTML so I will create an editor setting.
<code php>
// Foot note setting
$name = 'theme_demystified/footnote';
$title = get_string('footnote','theme_demystified');
$description = get_string('footnotedesc', 'theme_demystified');
$setting = new admin_setting_confightmleditor($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
How simple is that!

It is just about identical to the first two settings except that for this we have created a ''admin_setting_confightmleditor'' setting rather than a text setting.

Note: You can also set the columns and rows for the editor setting using the fifth and sixth arguments.

====Custom CSS====
The final setting is to allow the user to add some custom CSS to the theme that will be used on every page. I want this to be a plain textarea into which the user can enter CSS.
<code php>
// Custom CSS file
$name = 'theme_demystified/customcss';
$title = get_string('customcss','theme_demystified');
$description = get_string('customcssdesc', 'theme_demystified');
$setting = new admin_setting_configtextarea($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
Just like the editor or text settings. It's getting very easy now!

====Finishing settings.php====
With all of our settings defined and added to our page that we created right at the beginning it is time to finish it all off.
<code php>
} // This is the closing brace that encloses all the above settings.
</code>
The above line is the final line for the page. It is adding the page that we have created '''$setting''' to the admin tree structure. In this case it is adding it to the themes branch.

The following is the completed source for our settings.php ..... for your copy/paste pleasure.
<div style='height:300px;width:90%;overflow:auto;'>
<code php>
<?php
/**
* Settings for the demystified theme
*/
defined('MOODLE_INTERNAL') || die;

if ($ADMIN->fulltree) {

// Background colour setting
name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$setting = new admin_setting_configtext($name, $title, $description, $default, PARAM_CLEAN, 12);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);

// Logo file setting.
$name = 'theme_demystified/logo';
$title = get_string('logo','theme_demystified');
$description = get_string('logodesc', 'theme_demystified');
$setting = new admin_setting_configtext($name, $title, $description, '', PARAM_URL);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);

// Block region width.
$name = 'theme_demystified/regionwidth';
$title = get_string('regionwidth','theme_demystified');
$description = get_string('regionwidthdesc', 'theme_demystified');
$default = 200;
$choices = array(150=>'150px', 170=>'170px', 200=>'200px', 240=>'240px', 290=>'290px', 350=>'350px', 420=>'420px');
$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);

// Foot note setting.
$name = 'theme_demystified/footnote';
$title = get_string('footnote','theme_demystified');
$description = get_string('footnotedesc', 'theme_demystified');
$setting = new admin_setting_confightmleditor($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);

// Custom CSS file.
$name = 'theme_demystified/customcss';
$title = get_string('customcss','theme_demystified');
$description = get_string('customcssdesc', 'theme_demystified');
$setting = new admin_setting_configtextarea($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
}
</code>

===Creating a language file and adding our strings===
As I'm sure none of you have forgotten, throughout the creation of the our settings.php page, we used a lot of strings that I mentioned we would set later on. Well now is the time to set those strings.

First up create the following directories and file for our language strings:
* Directory '''theme/demystified/lang'''
* Directory '''theme/demystified/lang/en'''
* File '''theme/demystified/lang/theme_demystified.php'''

What we have created here is the required structure for Moodle to start looking for language strings.

First Moodle locates the lang directory, once found it looks within that directory for another directory that uses the character code for the language the user has selected, by default this is '''en''' for English. Once that is found it looks for the appropriate language file, in this case '''theme_demystified.php''' from which it will load all language strings for our theme.

If English isn't your chosen language simply replace the ''en'' directory with one that uses your chosen languages character code (two letters).

We can now add our language strings to '''theme/demystified/lang/theme_demystified.php'''. Copy and paste the following lines of PHP into this file.
<code php>
<?php

/**
* This file contains the strings used by the demystified theme
*/

$string['backgroundcolor'] = 'Background colour';
$string['backgroundcolordesc'] = 'This sets the background colour for the theme.';
$string['configtitle'] = 'Demystified theme';
$string['customcss'] = 'Custom CSS';
$string['customcssdesc'] = 'Any CSS you enter here will be added to every page allowing your to easily customise this theme.';
$string['footnote'] = 'Footnote';
$string['footnotedesc'] = 'The content from this textarea will be displayed in the footer of every page.';
$string['logo'] = 'Logo';
$string['logodesc'] = 'Enter the URL to an image to use as the logo for this site. Should be http://www.yoursite.com/path/to/logo.png';
$string['pluginname'] = 'Demystified';
$string['regionwidth'] = 'Column width';
$string['regionwidthdesc'] = 'This sets the width of the two block regions that form the left and right columns.';
</code>

In the above lines of code I have added an entry for each language string we used within ''settings.php''. When adding language strings like this make sure you use single quotes and try to keep things alphabetical - it helps greatly when managing strings.

Now when we view the settings page there will not be any errors or strings missing.

===Having a look at what we have created===
Now that we have created our settings page (settings.php) and added all of the language strings it is time to have a look at things in your browser.

Open your browser and enter the URL to your site. When you arrive at your site login as an administrator.

If you are not redirected to view the new settings change your URL to <nowiki>http://www.yoursite.com/admin/</nowiki> and your will see a screen to set the new theme settings we have just created. This lets us know that everything has worked correctly.

At any point now you are able to log in as administrator and within the settings block browse to '''Site administration > Appearance > Themes > Demystified theme''' to change those settings.

The screenshot below shows you what you should see at this point:

[[Image:Theme.settings.page.03.png|715px|thumb|left|The settings page we just created]]
<br style="clear:both;" />

==Using the settings in CSS==
With the settings page now created and operational it is time to make use of our new settings. The settings that we want to use within our CSS is as follows:

; backgroundcolor : Will be used to set the background colour in CSS.
; regionwidth : Will be the width of the column for CSS.
; customcss : Will be some custom CSS to add to our stylesheet.

At this point those names are the names we used for our setting with the slash and everything before it having been removed.

Before we start tearing into some code it is important that we have a look at what we are going to do and how we are going to go about it.

===How it all works within Moodle===
The first thing to understand is that while Moodle allows you to create a settings page and automates it inclusion and management right into the administration interfaces there is no smart equivalent for using the settings. This is simply because there is no way to predict how people will want to use the settings.

However don't think of this as a disadvantage, in fact it is quite the contrary. Although we can't just ''use'' our settings we can take full control over how and where we use them. It means it will take a little more code but in the end that will work to our advantage as we can do anything we want.

Moodle does help us out a little but not in an obvious way. The first thing that Moodle does is look for a config variable '''csspostprocess''' that should be the name of a function which we want called to make any changes to the CSS after it has been prepared.

The second thing Moodle does is include a lib.php from the theme's directory if one exists (also for the themes the current theme extends.) which ensures that as long as we write our code within '''theme/demystified/lib.php''' it will be included and ready to be used.

The third and final thing Moodle does that will help us out here is ensure that by the time any of code is ready to execute the settings have been prepared and are ready to be used within a theme config object which is passed into our ''csspostprocess'' function.

===Our plan===
As you have already probably guessed we will need to create a function to make the changes to the CSS that we want. We will then set the theme config option '''$THEME->csspostprocess''' to the name of our function.

By doing this when Moodle builds the CSS file it will call our function afterwards with the CSS and the theme object that contains our setting.

Now we know that we will use the ''csspostprocess'' function but how are we going to change the CSS, we could get the function to add CSS, or we could get the function to replace something within the CSS. My personal preference is to replace something within the CSS, just like what is happening with images. If you want to use an image within CSS you would write <nowiki>[[pix:theme|imagename]]</nowiki>.

For settings I am going to use <nowiki>[[setting:settingname]]</nowiki>, this way it looks a bit like something you are already familiar with.

What we need to decide upon next is the best way in which to replace our settings tag with the settings that the user has set.

There are two immediate options available to us:
# Make the ''csspostprocess'' function do all the work.
# Make the ''csspostprocess'' function call a separate function for each setting.
Solution 1 might sound like the simplest however it is going to result in a '''VERY''' complex function. Remember the user might have left settings blank or entered something that wouldn't be valid so we would need to make the sure there is some validation and a good default.
Because of this I think that solution 2 is the better solution.

So we are going to need a ''csspostprocess'' function and then a function for each of the three settings we have that will do the replacements.
<code php>
// This is our css post process function
function demystified_process_css($css, $theme) {};
// This replaces [[setting:backgroundcolor]] with the background colour
function demystified_set_backgroundcolor($css, $backgroundcolor) {};
// This replaces [[setting:regionwidth]] with the correct region width
function demystified_set_regionwidth() {$css, $regionwidth};
// This replaces [[setting:customcss]] with the custom css
function demystified_set_customcss() {$css, $customcss};
</code>

What you should note about the above functions is that they all start with the theme's name. This is required to ensure that the functions are named uniquely as it is VERY unlikely that someone has already created these functions.

So with our plan set out lets start writing the code.

===Writing the code===
The very first thing that we need to do is create a lib.php for our theme into which our css processing functions are going to go. So please at this point create '''theme/demystified/lib.php''' and open it in your editor ready to go.

The first bit of code we have to write is the function that will be called by Moodle to do the processing '''demystified_process_css'''.

Before we start out please remember that the wonderful thing about coding is that there is any number of solutions to a problem. The solutions that you are seeing here in this tutorial are solutions that I have come up with to meet fulfil the needs of the tutorial without being so complex that they are hard to understand. This probably isn't how I would go about it normally but this is a little easier to understand for those who aren't overly familiar with PHP and object orientation.

====The function: demystified_process_css====

<code php>
function demystified_process_css($css, $theme) {

if (!empty($theme->settings->backgroundcolor)) {
$backgroundcolor = $theme->settings->backgroundcolor;
} else {
$backgroundcolor = null;
}
$css = demystified_set_backgroundcolor($css, $backgroundcolor);

if (!empty($theme->settings->regionwidth)) {
$regionwidth = $theme->settings->regionwidth;
} else {
$regionwidth = null;
}
$css = demystified_set_regionwidth($css, $regionwidth);

if (!empty($theme->settings->customcss)) {
$customcss = $theme->settings->customcss;
} else {
$customcss = null;
}
$css = demystified_set_customcss($css, $customcss);

return $css;
}
</code>

So lets look at the things that make up this function:

<code php>
function demystified_process_css($css, $theme) {
//.....
return $css
}
</code>

This of course is the function declaration.

The function gets given two variables, the first '''$css''' is a pile of CSS as one big string, and the second is the theme object '''$theme''' that contains all of the configuration, options, and settings for our theme.

It then returns the ''$css'' variable, essentially returning the modified CSS.

<code php>
//...
if (!empty($theme->settings->backgroundcolor)) {
$backgroundcolor = $theme->settings->backgroundcolor;
} else {
$backgroundcolor = null;
}
$css = demystified_set_backgroundcolor($css, $backgroundcolor);
//...
</code>

Here we are processing our first setting ''backgroundcolor''.

The first thing that we need to do is check whether it has been set and whether it has a value. If it has then we store that value in '''$backgroundcolor'''. It is doesn't have a value then we set ''$backgroundcolor'' to null. This ensures that ''$backgroundcolor'' is set because if it isn't then you are going to get a notice (if you have debugging on).

The final line of this block calls the function '''demystified_set_backgroundcolor'''. We haven't written this function yet but we will shortly. When we call it we give it the ''$css'' variable that contains all of the CSS and we give it the background colour variable ''$backgroundcolor''. Once this function is finished it returns the ''$css'' variable with all of the changes made much like how our css processing function works.

What you should also note about this code is this:
<code php>
$theme->settings->backgroundcolor
</code>
As mentioned earlier ''$theme'' is an object that contains all of the configuration and settings for our theme. The ''$theme'' object has a $settings property which contains all of the settings for our theme, and finally the settings property contains a variable backgroundcolor that is the value the user entered for that setting. That is how we get a settings value.

<code php>
if (!empty($theme->settings->regionwidth)) {
$regionwidth = $theme->settings->regionwidth;
} else {
$regionwidth = null;
}
$css = demystified_set_regionwidth($css, $regionwidth);

if (!empty($theme->settings->customcss)) {
$customcss = $theme->settings->customcss;
} else {
$customcss = null;
}
$css = demystified_set_customcss($css, $customcss);
</code>

These two routines are nearly identical to the routine above. For both the regionwidth and the customcss we make sure it has a value and then store it in a variable. We then call the relevant function to make the changes for that setting.

Now that we have the general processing function it is time to write the three functions we have used but not written, ''demystified_set_backgroundcolor'', ''demystified_set_regionwidth'', ''demystified_set_customcss''.

====The function: demystified_set_backgroundcolor====

First up demystified_set_backgroundcolor.

<code php>
/**
* Sets the background colour variable in CSS
*
* @param string $css
* @param mixed $backgroundcolor
* @return string
*/
function demystified_set_backgroundcolor($css, $backgroundcolor) {
$tag = '[[setting:backgroundcolor]]';
$replacement = $backgroundcolor;
if (is_null($replacement)) {
$replacement = '#DDDDDD';
}
$css = str_replace($tag, $replacement, $css);
return $css;
}
</code>

Ok so what is happening here?

First we need a variable '''$tag''' that contains the tag we are going to replace. As mentioned earlier we are going to use tags that look like the image tags you are already familiar with ''<nowiki>[[setting:settingname]]</nowiki>'', in this case ''<nowiki>[[setting:backgroundcolor]]</nowiki>''.

Next I am going to create a variable called '''$replacement''' into which I put '''$backgroundcolor'''.

The '''IF''' statement that comes next checks ''$replacement'' to make sure it is not null. If it is then we need to set it to a default value. In this case I have used ''#DDD'' as that was the default for the settings.

The line after the IF statement puts it all together. The ''str_replace'' function that we are calling takes three arguments in this order:
# The text to search for.
# The text to replace it with.
# The text to do the replacement in.
It then returns the text with all of the replacements made. So in this case we are replacing the tag with the background colour and it is returning the changed CSS.

The final thing is to return the ''$css'' variable which now contains the correct background colour.

====The function: demystified_set_regionwidth====

Next we have the demystified_set_regionwidth function.
<code php>
/**
* Sets the region width variable in CSS
*
* @param string $css
* @param mixed $regionwidth
* @return string
*/
function demystified_set_regionwidth($css, $regionwidth) {
$tag = '[[setting:regionwidth]]';
$doubletag = '[[setting:regionwidthdouble]]';
$replacement = $regionwidth;
if (is_null($replacement)) {
$replacement = 200;
}
$css = str_replace($tag, $replacement.'px', $css);
$css = str_replace($doubletag, ($replacement*2).'px', $css);
return $css;
}
</code>

This function is very similar to the above function however there is one key thing we are doing different. We are doing two replacements.

# The first replacement is for the width that the user selected. In this case I am replacing the tag ''<nowiki>[[setting:regionwidth]]</nowiki>'' with the width.
# The second replacement is for the width x 2. This is because the page layout requires that the width be doubled for some of the CSS. Here I will replace ''<nowiki>[[setting:regionwidthdouble]]</nowiki>'' with the doubled width.

Remember because it is still just a number we need to add '''px''' to the end of each before we do the replacement.

So the overall process of this function is:
# Define the two tags as '''$tag''' and '''$doubletag'''.
# Make '''$replacement''' the region width ''$regionwidth''.
# Set ''$replacement'' to a default value of 200 is it is null.
# Replace '''<nowiki>[[setting:regionwidth]]</nowiki>''' with the width.
# Replace '''<nowiki>[[setting:regionwidthdouble]]</nowiki>''' with the width x 2.
# Return the changed CSS.

====The function: demystified_set_customcss====

The final function that we need to write is the demystified_set_customcss function.
<code php>
/**
* Sets the custom css variable in CSS
*
* @param string $css
* @param mixed $customcss
* @return string
*/
function demystified_set_customcss($css, $customcss) {
$tag = '[[setting:customcss]]';
$replacement = $customcss;
if (is_null($replacement)) {
$replacement = '';
}
$css = str_replace($tag, $replacement, $css);
return $css;
}
</code>

This function is just like the first function. I'm going to let you work it out on your own.

And that is it no more PHP... Hallelujah I can hear you yelling. The final thing we need to do is tell our theme about the functions we have written and put the settings tags into the CSS.

===Finishing it all off===

So there are two things we have to do in order to complete this section and have our the settings page implemented and our settings being used.

First we need to tell our theme that we want to use the function ''demystified_process_css'' as the ''csspostprocess'' function. This is done very simply by adding the following line of PHP to the bottom of our theme's config.php file '''theme/demystified/config.php'''.

<code php>
$THEME->csspostprocess = 'demystified_process_css';
</code>

With that done the only thing left is to add the settings tag into the CSS. Remember those settings tags are:

; <nowiki>[[setting:backgroundcolor]]</nowiki> : We need to add this where ever we want the background colour setting to be used.
; <nowiki>[[setting:regionwidth]]</nowiki> : We need to add this where ever we want to set the width of the block regions.
; <nowiki>[[setting:regionwidthdouble]]</nowiki> : We need to add this where ever we want to set the doubled width of the block regions.
; <nowiki>[[setting:customcss]]</nowiki> : We need to add this to the bottom of the CSS file that we want the custom CSS added to.

So lets make those changes in CSS now, open up your ''core.css'' file and replace the CSS with the CSS below:
<code css>
/** Background color is a setting **/
html {background-color:[[setting:backgroundcolor]];}
body {margin:30px;padding:0;border:1px solid #333;border-width:0 10px 0 10px;background-color:#333;}
body #page {background-color:#FFF;position:relative;top:-10px;}
.block .header {background-image:none;background-color:#0C5CAC;border:1px solid #0C5CAC;color:#FFF;}
.block {border-color:#4BA7FF;background-color:#DDEEFF;}
.block .content {background-color:#F1F8FF;}
a:link,
a:visited {color:#0C5CAC;}
a:hover {color:#C77500;}
#page #page-header {background-color:#0C5CAC;margin:0;padding:0;width:100%;color:#fff;}
#page #page-header a:link, #page #page-header a:visited {color:#FFAC02}
#page #page-header .navbar, #page #page-header .navbar a:link, #page #page-header .navbar a:visited {color:#0C5CAC;}
/** Override the region width **/
#page-content #region-main-box {left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidthdouble]];}
#page-content #region-main-box #region-post-box #region-pre {width:[[setting:regionwidth]];left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-post {width:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidthdouble]];}
.side-pre-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-pre-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
/** Custom CSS **/
[[setting:customcss]]
</code>

You will notice that <nowiki>[[setting:backgroundcolor]]</nowiki> has been used for the html tags background colour:
<code css>
html {background-color:[[setting:backgroundcolor]];}
</code>

We have also set the width of the block regions by adding <nowiki>[[setting:regionwidth]]</nowiki> as the width for region-pre and region-post as shown below:
<code css>
#page-content #region-main-box {left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidthdouble]];}
#page-content #region-main-box #region-post-box #region-pre {width:[[setting:regionwidth]];left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-post {width:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidthdouble]];}
.side-pre-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-pre-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
</code>
You'll notice here that we have to set several different widths and margins using the regionwidth setting and make use of the special regionwidthdouble setting that we added.

The final thing that we did was add the <nowiki>[[setting:customcss]]</nowiki> to the bottom of the file to ensure that the custom CSS comes last (and therefore can override all other CSS).

And with that we are finished. The screenshot below shows how this now looks in the browser if I set the background colour setting to '''<span style='color:#FFA800;'>#FFA800</span>''' and made the column width 240px;

[[Image:Theme.settings.page.04.png|715px|thumb|left|Our settings in action]]<br style="clear:both;" />

==Using the settings within our layout files==
Now that we have utilised the first three settings within our theme's CSS file it is time to implement the other two settings within the layout files so that they are written directly into the page.

You'll be glad to know this is no where near as difficult as utilising settings within a CSS file although it still does require a little bit of PHP.

First up is the logo setting. Into this setting the user is able to enter the URL to an image to use as the logo for the site. In my case I want this to be just a background logo on top of which I want to position the page header.

Before I start there is one thing I need to do however and that is create a default logo background that gets shown if the user hasn't set a specific logo file. To do this I simply created an image '''logo.jpg''' and put it into a pix directory within the demystified theme. You should end up with '''theme/demystified/pix/logo.jpg'''.

Next open up the front-page layout file ''theme/demystified/layout/frontpage.php''. At the top of the file is the PHP that checks what blocks regions the page has and a bit of other stuff. Well right below the existing bit of PHP we want to add the following code:
<code php>
if (!empty($PAGE->theme->settings->logo)) {
$logourl = $PAGE->theme->settings->logo;
} else {
$logourl = $OUTPUT->pix_url('logo', 'theme');
}
</code>
What we are doing here is creating a variable called $logourl that will contain the URL to a logo file that was either entered by the user or if they left it blank is that of our default logo file.

There are two things that you should notice about this. First the logo setting can be retrieved through '''$PAGE->theme->settings->logo''' and second we get the default logo url by calling '''$OUTPUT->pix_url('logo', 'theme')'''.

Now that we have the logo URL we are going to use we need to add an image to the header section of the page as shown below:
<code php>
<div id="page-header" class="clearfix">
<img class="sitelogo" src="<?php echo $logourl;?>" alt="Custom logo here" />
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
....
</code>

If you save that and browse to your sites front page you will notice that the logo file is now being shown. Hooray. However it is probably not styled too nicely so lets quickly fix that. Open up the core.css file and add the following lines of CSS to the bottom of the file.
<code css>
#page-header {position:relative;min-height:100px;}
#page-header .sitelogo {float:left;}
#page-header .headermain {position:absolute;left:0.5em;top:50px;margin:0;float:none;font-size:40px;}
</code>
These three lines position the image correctly and if you now refresh everything should appear perfectly.

With the logo done the last setting we need to deal with is the footnote setting. The idea with this setting was that the administrator could enter some text into the editor and it would be displayed in the footer of the page.

This is probably the easiest setting to implement.

Within the front page layout file that we edited above add the following lines below those we added previously.

<code php>
if (!empty($PAGE->theme->settings->footnote)) {
$footnote = $PAGE->theme->settings->footnote;
} else {
$footnote = '';
}
</code>

Here we are just collecting the footnote into a variable '''$footnote''' and setting a default footnote comment if the user hasn't entered one.

We can now echo the $footnote variable within the page footer. This can be done as shown below.

<code php>

<div id="page-footer">
<div class="footnote"><?php echo $footnote; ?></div>
<p class="helplink">
<?php echo page_doc_link(get_string('moodledocslink')) ?>
</p>
</code>

And with that done we are finished! Congratulations if you got this far.

The screenshot below shows the demystified theme we have just created that is styled by the settings page.

[[Image:Theme.settings.page.05.png|715px|thumb|left|My finished demystified theme]]<br style="clear:both" />

==Testing our creation==
Congratulations to you! If you've made it this far you have done very well. Now it is time to have a look at what we have created and give it a quick test run.

So in this tutorial we have achieved the following:

* We created a theme called demystified that is based on the standard theme.
* We added a settings page to our new theme.
* We added the following settings to our settings page:
** We can set a background colour through the admin interface.
** We can change the logo of the site.
** We can change the block region width.
** We can add a footnote to the page footer
** We can add some custom CSS to seal the deal.
* Those settings were then used in the CSS files for our theme.
* They were also used in the layout files for our theme.
* And here we are testing it all.

The screenshots below show my testing process and I change each setting and view the outcome. The great thing about this is that with theme designer mode on you see the changes as soon as the form refreshes.

[[Image:Theme.settings.page.06.png|300px|thumb|left|Default settings]]
[[Image:Theme.settings.page.07.png|300px|thumb|left|Changed the background colour setting]]
[[Image:Theme.settings.page.08.png|300px|thumb|left|Changed the logo and region width]]
[[Image:Theme.settings.page.09.png|300px|thumb|left|Added a footnote]]
[[Image:Theme.settings.page.10.png|300px|thumb|left|Added some custom CSS]]
<br style="clear:both" />

==The different settings you can use==
During this tutorial we use four different kinds of settings, a text box, text area, a select (dropdown) and the editor however as I'm sure you have all guessed there is many more some of which will certainly be useful for theme settings.

The following are examples of some of the different settings. I should add that these build upon what we have already done within the tutorial but are not included in the download.

===Colour picker===
[[Image:Theme.settings.page.11.png|400px|thumb|The colour picker]]
I can hear you all asking now 'Why didn't you mention this one earlier?' well the answer is simple it didn't exist when I first wrote the tutorial. It is an admin setting that I wrote several days after because of the fantastic effort people were putting into trying out settings pages.

A bit about the colour picker. First up it is a text box that when the page loads turns into a colour picker that can be used to select a colour and can even preview the selected colour in the page (by clicking the preview button). It is designed to be very easy to use and the code is just about as simple as creating a normal text box setting.

In the image to the left I have replaced the background colour setting we created during the tutorial with the colour picker. Lets have a look at the code involved for that.
<code php>
// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$previewconfig = array('selector'=>'html', 'style'=>'backgroundColor');
$setting = new admin_setting_configcolourpicker($name, $title, $description, $default, $previewconfig);
$temp->add($setting);
</code>
So first thing you should notice is that the first four lines of code have not changed at all!

The first change we have is to create a variable '''$previewconfig'''.
This variable is used to tell the colour picker what to do when the user clicks the preview button. It should be an array that contains two things, first a selector, and second a style.
# The selector is a CSS selector like ''.page .header h2''.
# The style is a what should change, there are two immediate values it can be, either '''backgroundColor''' or '''color'''.
In my case the selector is '''html''' to target the html tag and the style is backgroundColor to change the background colour.

The second change is to use '''admin_setting_configcolourpicker''' instead of ''admin_setting_configtext''. The arguments are nearly identical as well except that there is an extra argument to which we give the '''$previewconfig''' variable.

And that is it! it is all you need to get the colour picker up and running.

'''Extra note:''' The $previewconfig variable is optional. If you don't want a preview button the simply set ''$previewconfig = null''

==Common pitfalls and useful notes==

This section is really just a collection of pointers, tips, notes, and other short useful stuff that may be of use to those attempting this tutorial.

# First up and most importantly there are very few limitations to what you achieve in this fashion.
# If you get stuck or need a hand ask in the forums, there's always someone round who can help.
# If you do something really cool let us know, I know everyone in the community loves finding our what others are achieving.
# You don't have to use ''admin_settingpage'' you can also use '''admin_externalpage''' if you prefer. It should be noted however that it is not the preferred way to do it as admin_externalpage's were only left in Moodle 2.0 for backwards compatibility (although they are more flexible one day they will be deprecated or removed). Thank you to Darryl for raising this.
# If you find that your language strings aren't being used (you are getting language string notices) and you have double checked that you have turned '''langstringcache''' off then you may need to delete the language cache directory. This is located in the moodledata directory for you installation: moodledata/cache/lang/*. You should delete the directory for your chosen language by default ''en''.

==See also==

* [[Adding theme upgrade code]]
* [[Styling and customising the dock]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=152053 Theme 2.0: Adding a settings page to your theme] forum discussion

Creating a theme settings page

2014-09-24T22:31:03Z

Tqr: /* Finishing settings.php */ finalising updates.

Creating a theme settings page

2014-09-24T22:22:44Z

Tqr: /* Finishing settings.php */ - update

{{Template:Themes}}This document looks at how to create a settings page for your Moodle 2.x.x theme and how to make use of those settings within the CSS and layout files for your theme.

This is a pretty advanced topic and will require that you have at least an intermediate knowledge of PHP, CSS, and development in general.

==Before we begin==
[[Image:Theme.settings.page.03.png|350px|thumb|Our end goal. The settings page.]]
[[Image:Theme.settings.page.10.png|350px|thumb|And what it can do.]]
There is a huge body of knowledge that we must cover in following through this document and as such I think the best way to write this is as a tutorial.

My intentions for this tutorial are to replicate the standard theme but with a settings page that allows the administrator to set a background colour, set a logo to use with the page, and probably several other minor settings to change the way in which the theme is displayed.

I will start this tutorial by creating a new theme which will be largely a copy/paste of the current standard theme. I expect that anyone working through this tutorial has previously read the tutorial I wrote on [[Themes 2.0 creating your first theme|creating your first theme]]. If you haven't go read it now because I'm not going to go into much detail until we get to the actual process of customising the theme and introducing the settings page.

So before we finally get this started please ensure you can check off everything on the following requirements list.
* Have a Moodle installation that has already been installed and configured and is ready to use.
* Have full read/write access to that installation.
* Be prepared to delete that installation at the end of this... we will destroy it!
* Have a development environment prepared and ready to use. This includes:
** Your favourite editor installed, running, and pointed at the themes directory of your installation.
** Your browser open and your site visible.
** A bottomless coffee pot... decaf won't help you with this one.
* Have set the following settings:
** '''themedesignermode''' if you don't know what this is please read the [[Themes 2.0 creating your first theme|creating your first theme]] tutorial.
** '''allowthemechangeonurl''' turn this on, it allows you to change themes on the URL and is very handy when developing themes. ''Site Administration > Appearance > Themes > Theme settings''
** '''langstringcache''' if you don't turn this off you won't see your strings when they are added. ''Site Administration > Language > Language settings''
* And finally an insane ambition to create a customisable theme.

For those interested the theme that I create throughout this tutorial can be downloaded from the forum post in which I announce this document: http://moodle.org/mod/forum/discuss.php?d=152053
<br style="clear:right;" />

==Our goals for this tutorial==
The following is just a list goals that I hope to achieve during this tutorial. They are laid out here so that I can easily refer back to them and so that you can easily find them.
# Create a new theme called '''demystified''' based upon the standard theme within Moodle 2.0.
# Make some minor changes to that theme to allow us to more easily see what is going on.
# Create a settings page for the demystified theme.
# Add several settings to our settings page.
# Use some of those settings to alter our CSS.
# Use the rest of those settings within our layout file..
# Discuss the good, the bad, and limits of what we have just created.

So I can see you are all very excited about this point and that you would love to know what settings we are going to create; So here they are:

A setting to ...
* change the background colour (CSS).
* set the path to an image that we will use as a logo on all pages (Layout files).
* override the width of the block regions (CSS).
* allow a note to be added to the footer of all pages (Layout files).
* allow custom CSS to be written to do anything the user wants. (CSS)

==Creating the demystified theme==
Before we start here I want to remind you that I am going to look at this only briefly as I am making the assumption that you have read the [[Themes 2.0 creating your first theme|creating your first theme]] tutorial.

Well lets get into it....

The first thing we need to do is create a directory for our theme which we will call demystified.

So within your Moodle directory create the following folder '''moodle/theme/demystified'''. At the same time you can also create the following files and folders which we will get to soon.
* The file '''moodle/theme/demystified/config.php''' for our config information.
* The directory '''moodle/theme/demystified/layout''' for our layout files.
* The directory '''moodle/theme/demystified/style''' for our css files.
* The file '''moodle/theme/demystified/style/core.css''' which will contain our special CSS.

Next we will copy the layout files from the base theme to our new theme demystified. We are basing the demystified theme on the standard theme however that doesn't use it's own layout files it uses the base theme's layout files so those are the ones we want.

The reason that we are coping these layout files is that later on in this tutorial we will be modifying them to make use of our new settings... so copy all of the layout files from '''moodle/theme/base/layout''' to '''moodle/theme/demystified/layout'''.

There should be three files that you just copied:
# embedded.php
# frontpage.php
# general.php

Now we need to populate demystified/config.php with the settings for our new theme. They are as follows:
<code php>
$THEME->name = 'demystified';
</code>
Simply sets the name of our theme.

<code php>
$THEME->parents = array('standard','base');
</code>
This theme is extending both the standard theme and the base theme. Remember when extending a theme you also need to extend its parents or things might not work correctly.

<code php>
$THEME->sheets = array('core');
</code>
This tells our theme that we want to use the file '''demystified/style/core.css''' with this theme.

<div style="height:300px;overflow-y:scroll;">
<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-post',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'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),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>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),
),
// 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),
),
);
</code>
</div>
Now that all looks very complicated however its really not too bad as it is just copied from the base theme's config.php file. We can do this because we copied the layout files from the base theme to begin with and for the time being there are no changes that we wish to make. Simply open up '''theme/base/config.php''' and copy the layouts from there.

And that is it. The config.php file for our demystified theme is complete. The full source is shown below:
<div style="height:300px;overflow-y:scroll;">
<code php>
<?php

// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* The demystified theme config file
*
* This theme was created to document the process of adding a settings page to a theme
*
* @copyright 2010 Sam Hemelryk
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

// The name of our theme
$THEME->name = 'demystified';

// The other themes this theme extends
$THEME->parents = array('standard','base');

// The CSS files this theme uses (located in the style directory)
$THEME->sheets = array('core');

// The layout definitions for this theme
$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-post',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'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),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>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),
),
// 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),
),
);
</code>
</div>

The screenshot below shows both the directory structure we have now created and the theme presently.

[[Image:Theme.settings.page.01.png]]

To view the theme so far open you browser and enter the URL of your site followed by '''?theme=demystified'''. You should see the theme that we just created which will look exactly like the base standard theme.

The final thing that we want to do is add a little bit of CSS to the demystified theme that will both visually set this theme apart from the standard theme and second build a the base which our settings can later extend.

I added the following snippet of CSS to the file '''demystified/style/core.css'''.
<code css>
html {background-color:#DDD;}
body {margin:30px;padding:0;border:1px solid #333;border-width:0 10px 0 10px;background-color:#333;}
body #page {background-color:#FFF;position:relative;top:-10px;}
.block .header {background-image:none;background-color:#0C5CAC;border:1px solid #0C5CAC;color:#FFF;}
.block {border-color:#4BA7FF;background-color:#DDEEFF;}
.block .content {background-color:#F1F8FF;}
a:link,
a:visited {color:#0C5CAC;}
a:hover {color:#C77500;}
#page #page-header {background-color:#0C5CAC;margin:0;padding:0;width:100%;color:#fff;}
#page #page-header a:link, #page #page-header a:visited {color:#FFAC02}
#page #page-header .navbar, #page #page-header .navbar a:link, #page #page-header .navbar a:visited {color:#0C5CAC;}
</code>

The CSS that we have just added to our theme sets a couple of colours on the front page. Presently this is the only CSS I will add, I know it isn't complete by any means but it achieves it's purpose as the screenshot below illustrates.

[[Image:Theme.settings.page.02.png|715px|thumb|left|The newly styles demystified theme]]<br style="clear:both;" />

And with that I will move on to the real purpose of this tutorial, creating the settings page

==Setting up the settings page==
With the demystified theme set up it is time to create the settings page. This is where the real PHP fun begins.

For those of you who happen to be familiar with development of modules, blocks or other plugin types you have probably encountered settings pages before and this is not going to be any different.

However for those who haven't which I imagine is most of you this is going to be quite a challenge. I will try to walk through this step by step however if at any point you get stuck don't hesitate to ask in the forums as I imagine you will get a speedy response.

===How settings pages work in Moodle===
Settings pages can be used by nearly every plugin type, of which themes is of course one. The way in which it all works isn't too tricky to understand.

All of the settings for Moodle can be configured through the administrator interfaces when logged in. I am sure that everyone here has seen those pages and has changed a setting or two before so you will all know what I am talking about. Well the settings page for a theme is no different. It will be shown in the administration pages tree under '''Appearance > Themes''' and all we have to do is tell Moodle what settings there are.

This is done by creating a settings.php file within our theme into which we will add code that tells Moodle about the settings we want to add/use.

When telling Moodle about each setting we are simply creating a new ''admin_setting'' instance of the type we want and the properties we want and then adding it to our settings page.

There is really not much more too it at this level. Things can get very complex very fast so the best thing we can do now is start creating our settings.php file for the demystified theme and see where it leads us.

===Creating the settings page===
So as mentioned before we need a settings.php file which we will create now. To begin with create the file '''theme/demystified/settings.php''' and open it in your favourite editor so its ready to go.

Before we start adding code however lets just remember the settings that we want to create:
* change the background colour (CSS).
* set the path to an image that we will use as a logo on all pages (Layout files).
* override the width of the block regions (CSS).
* allow a note to be added to the footer of all pages (Layout files).
* allow custom CSS to be written to do anything the user wants. (CSS)

Alright.

Now thinking about this the first setting is as basic as it gets, all we need is a text box that the user can type a colour into.

The second is to allow a logo to be used in the header of each page. What we want here is a path but should it be a physical path e.g. C:/path/to/image.png or should it be a web path e.g. <nowiki>http://mysite.com/path/to/image.png</nowiki>?
For the purpose of this tutorial I am going to go with a web path because it is going to be easier to code and will hopefully be a little easier to understand to begin with.

The third setting is a little more complex. For this I want a drop down box with some specific widths that the administrator can select.

The forth and the fifth settings are both pretty straight forward, there we want a textarea into which the user can enter what ever they want and we will do something useful with it.

Now that we have an understanding about the settings we wish to define pull up your editor and lets start coding....

<code php>
<?php

/**
* Settings for the demystified theme
*/
defined('MOODLE_INTERNAL') || die;

if ($ADMIN->fulltree) {
</code>
This is the first bit of code we must enter, the first line is of course just the opening php tag, secondly we have a comment that describes this file, and then we get create a new '''admin_settingspage object'''.

This admin_settingspage object that we have just created is a representation of our settings page and is the what we add our new settings to. When creating it we give it two arguments, first the name of the page which is in this case '''theme_''themename''''' and the title for the page which we get with the get_string method.

At the moment I'm not going to worry about adding the string, we will get to that later once we have defined all of our settings.

====Background colour====

With the page now created lets add our first setting: Background colour.

<code php>
// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$setting = new admin_setting_configtext($name, $title, $description, $default, PARAM_CLEAN, 12);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
Thankfully this isn't as difficult as it initially looks.

The first line of code is creating a variable for the name of the background colour setting. In this case it is '''theme_demystified/backgroundcolor'''.

The name is very important, for the setting to be usable we have to follow a strict naming convention. '''theme_''themename''/''settingname''''' where '''''themename''''' is the name of the theme the setting belongs to and '''''settingname''''' is the name for the setting by which we will use it.

The second line of code creates a variable that contains the title of the setting. This is what the user sees to the right of the setting on the settings page and should be a short description of the setting. Here we are again using the ''get_string'' method so we will need to remember to add that string later on.

The third line of code sets the description. This should describe what the setting does or how it works and again we will use the get_string method.

The fourth line creates a variable that will be used as the default value for the setting. Because this setting is a colour we want an HTML colour to be the default value.

The fifth line is where we put it all together. Here we create a new '''admin_setting_configtext''' object. This object will represent the background colour setting.

When we create it we need to give it 6 different things.
# The name of the setting. In this case we have a variable '''$name'''.
# The title for this setting. We used the variable '''$title'''.
# The description of the setting '''$description'''.
# The default value for the setting. '''$default''' is the variable this.
# The type of value we want the user to enter. For this we have used PARAM_CLEAN which tells Moodle to get rid of any nasties from what the user enters.
# The size of the field. In our case 12 characters will be plenty.

The sixth and final line of code adds our newly created setting to the administration page we created earlier.

That is it we have successfully created and added our first setting, however there are several more to settings to do, and there are a couple of important things that you need to be aware of before we move on.

First: There are several different types of settings that you can create and add to a page, and each one may differ in what they need you to give them. In this case it was name, title, description, default, type, and size. However other settings will likely require different things. Smart editors like Netbeans or Eclipse can tell you what is required, otherwise you will need to research it.

Second: Normally settings are declared on one line as follows:
<code php>
$setting->add(new admin_setting_configtext('theme_demystified/backgroundcolor', get_string('backgroundcolor','theme_demystified'), get_string('backgroundcolordesc', 'theme_demystified'), '#DDD', PARAM_CLEAN, 12));
</code>
While this is structurally identical as all we have done is move everything onto one line and do away with the variables it is a little harder to read when you are learning all of this.

====The logo file====
Time to create the second setting that will allow the user to enter a URL to an image they wish to use as the logo on their site.
<code php>
// Logo file setting
$name = 'theme_demystified/logo';
$title = get_string('logo','theme_demystified');
$description = get_string('logodesc', 'theme_demystified');
$setting = new admin_setting_configtext($name, $title, $description, '', PARAM_URL);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
The first thing that you will notice about this setting that it is very similar to the first setting, in fact all we have changed is the name, title, description, and default value. We have however changed the value type from PARAM_CLEAN to PARAM_URL, this makes sure the user enters a URL. You will also notice that for this one we don't set a size for the field as we have no idea how long the URL will be.

====Block region width====
The third setting should allow the user to set a width for the block regions that will be used as columns.

For this setting I want to do something a little different from the previous two, here I want to use a select box so that the user selects a width for the column from a list I provide.
<code php>
// Block region width
$name = 'theme_demystified/regionwidth';
$title = get_string('regionwidth','theme_demystified');
$description = get_string('regionwidthdesc', 'theme_demystified');
$default = 200;
$choices = array(150=>'150px', 170=>'170px', 200=>'200px', 240=>'240px', 290=>'290px', 350=>'350px', 420=>'420px');
$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
So looking at the code: The first four lines you will recognise. $name, $title, $description, and $default are all being set.

The fifth line of code however introduces something new. Of course in order to have a select box we have to have options, in this case we have an array of options stored in the variable $choices.

The array of options is constructed of a collection of '''''value''' => '''label''''' pairs. Notice how we don't add '''px''' to the value. This is is very intentional as later on I need to do a little bit of math with that value so we need it to be a number.

The lines after should look familiar again, the only difference being that instead of a ''admin_setting_configtext'' setting we have created a ''admin_setting_configselect'' for which we must give the choices for the select box as the fifth argument.

Woohoo, we've just created our first select box setting.

====Foot note====
Now to create the foot note setting. Here we want the user to be able to enter some arbitrary text that will be used in the footer of the page. For this I want the user to be able to enter some HTML so I will create an editor setting.
<code php>
// Foot note setting
$name = 'theme_demystified/footnote';
$title = get_string('footnote','theme_demystified');
$description = get_string('footnotedesc', 'theme_demystified');
$setting = new admin_setting_confightmleditor($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
How simple is that!

It is just about identical to the first two settings except that for this we have created a ''admin_setting_confightmleditor'' setting rather than a text setting.

Note: You can also set the columns and rows for the editor setting using the fifth and sixth arguments.

====Custom CSS====
The final setting is to allow the user to add some custom CSS to the theme that will be used on every page. I want this to be a plain textarea into which the user can enter CSS.
<code php>
// Custom CSS file
$name = 'theme_demystified/customcss';
$title = get_string('customcss','theme_demystified');
$description = get_string('customcssdesc', 'theme_demystified');
$setting = new admin_setting_configtextarea($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
Just like the editor or text settings. It's getting very easy now!

====Finishing settings.php====
With all of our settings defined and added to our page that we created right at the beginning it is time to finish it all off.
<code php>
} // This is the closing brace that encloses all the above settings.
</code>
The above line is the final line for the page. It is adding the page that we have created '''$setting''' to the admin tree structure. In this case it is adding it to the themes branch.

The following is the completed source for our settings.php ..... for your copy/paste pleasure.
<div style='height:300px;overflow:auto;'>
<code php>
<?php
/**
* Settings for the demystified theme
*/
defined('MOODLE_INTERNAL') || die;

if ($ADMIN->fulltree) {

// Background colour setting
name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$setting = new admin_setting_configtext($name, $title, $description, $default, PARAM_CLEAN, 12);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);

// Logo file setting.
$name = 'theme_demystified/logo';
$title = get_string('logo','theme_demystified');
$description = get_string('logodesc', 'theme_demystified');
$setting = new admin_setting_configtext($name, $title, $description, '', PARAM_URL);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);

// Block region width.
$name = 'theme_demystified/regionwidth';
$title = get_string('regionwidth','theme_demystified');
$description = get_string('regionwidthdesc', 'theme_demystified');
$default = 200;
$choices = array(150=>'150px', 170=>'170px', 200=>'200px', 240=>'240px', 290=>'290px', 350=>'350px', 420=>'420px');
$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);

// Foot note setting.
$name = 'theme_demystified/footnote';
$title = get_string('footnote','theme_demystified');
$description = get_string('footnotedesc', 'theme_demystified');
$setting = new admin_setting_confightmleditor($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);

// Custom CSS file.
$name = 'theme_demystified/customcss';
$title = get_string('customcss','theme_demystified');
$description = get_string('customcssdesc', 'theme_demystified');
$setting = new admin_setting_configtextarea($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
}
</code>
</div>

===Creating a language file and adding our strings===
As I'm sure none of you have forgotten, throughout the creation of the our settings.php page, we used a lot of strings that I mentioned we would set later on. Well now is the time to set those strings.

First up create the following directories and file for our language strings:
* Directory '''theme/demystified/lang'''
* Directory '''theme/demystified/lang/en'''
* File '''theme/demystified/lang/theme_demystified.php'''

What we have created here is the required structure for Moodle to start looking for language strings.

First Moodle locates the lang directory, once found it looks within that directory for another directory that uses the character code for the language the user has selected, by default this is '''en''' for English. Once that is found it looks for the appropriate language file, in this case '''theme_demystified.php''' from which it will load all language strings for our theme.

If English isn't your chosen language simply replace the ''en'' directory with one that uses your chosen languages character code (two letters).

We can now add our language strings to '''theme/demystified/lang/theme_demystified.php'''. Copy and paste the following lines of PHP into this file.
<code php>
<?php

/**
* This file contains the strings used by the demystified theme
*/

$string['backgroundcolor'] = 'Background colour';
$string['backgroundcolordesc'] = 'This sets the background colour for the theme.';
$string['configtitle'] = 'Demystified theme';
$string['customcss'] = 'Custom CSS';
$string['customcssdesc'] = 'Any CSS you enter here will be added to every page allowing your to easily customise this theme.';
$string['footnote'] = 'Footnote';
$string['footnotedesc'] = 'The content from this textarea will be displayed in the footer of every page.';
$string['logo'] = 'Logo';
$string['logodesc'] = 'Enter the URL to an image to use as the logo for this site. Should be http://www.yoursite.com/path/to/logo.png';
$string['pluginname'] = 'Demystified';
$string['regionwidth'] = 'Column width';
$string['regionwidthdesc'] = 'This sets the width of the two block regions that form the left and right columns.';
</code>

In the above lines of code I have added an entry for each language string we used within ''settings.php''. When adding language strings like this make sure you use single quotes and try to keep things alphabetical - it helps greatly when managing strings.

Now when we view the settings page there will not be any errors or strings missing.

===Having a look at what we have created===
Now that we have created our settings page (settings.php) and added all of the language strings it is time to have a look at things in your browser.

Open your browser and enter the URL to your site. When you arrive at your site login as an administrator.

If you are not redirected to view the new settings change your URL to <nowiki>http://www.yoursite.com/admin/</nowiki> and your will see a screen to set the new theme settings we have just created. This lets us know that everything has worked correctly.

At any point now you are able to log in as administrator and within the settings block browse to '''Site administration > Appearance > Themes > Demystified theme''' to change those settings.

The screenshot below shows you what you should see at this point:

[[Image:Theme.settings.page.03.png|715px|thumb|left|The settings page we just created]]
<br style="clear:both;" />

==Using the settings in CSS==
With the settings page now created and operational it is time to make use of our new settings. The settings that we want to use within our CSS is as follows:

; backgroundcolor : Will be used to set the background colour in CSS.
; regionwidth : Will be the width of the column for CSS.
; customcss : Will be some custom CSS to add to our stylesheet.

At this point those names are the names we used for our setting with the slash and everything before it having been removed.

Before we start tearing into some code it is important that we have a look at what we are going to do and how we are going to go about it.

===How it all works within Moodle===
The first thing to understand is that while Moodle allows you to create a settings page and automates it inclusion and management right into the administration interfaces there is no smart equivalent for using the settings. This is simply because there is no way to predict how people will want to use the settings.

However don't think of this as a disadvantage, in fact it is quite the contrary. Although we can't just ''use'' our settings we can take full control over how and where we use them. It means it will take a little more code but in the end that will work to our advantage as we can do anything we want.

Moodle does help us out a little but not in an obvious way. The first thing that Moodle does is look for a config variable '''csspostprocess''' that should be the name of a function which we want called to make any changes to the CSS after it has been prepared.

The second thing Moodle does is include a lib.php from the theme's directory if one exists (also for the themes the current theme extends.) which ensures that as long as we write our code within '''theme/demystified/lib.php''' it will be included and ready to be used.

The third and final thing Moodle does that will help us out here is ensure that by the time any of code is ready to execute the settings have been prepared and are ready to be used within a theme config object which is passed into our ''csspostprocess'' function.

===Our plan===
As you have already probably guessed we will need to create a function to make the changes to the CSS that we want. We will then set the theme config option '''$THEME->csspostprocess''' to the name of our function.

By doing this when Moodle builds the CSS file it will call our function afterwards with the CSS and the theme object that contains our setting.

Now we know that we will use the ''csspostprocess'' function but how are we going to change the CSS, we could get the function to add CSS, or we could get the function to replace something within the CSS. My personal preference is to replace something within the CSS, just like what is happening with images. If you want to use an image within CSS you would write <nowiki>[[pix:theme|imagename]]</nowiki>.

For settings I am going to use <nowiki>[[setting:settingname]]</nowiki>, this way it looks a bit like something you are already familiar with.

What we need to decide upon next is the best way in which to replace our settings tag with the settings that the user has set.

There are two immediate options available to us:
# Make the ''csspostprocess'' function do all the work.
# Make the ''csspostprocess'' function call a separate function for each setting.
Solution 1 might sound like the simplest however it is going to result in a '''VERY''' complex function. Remember the user might have left settings blank or entered something that wouldn't be valid so we would need to make the sure there is some validation and a good default.
Because of this I think that solution 2 is the better solution.

So we are going to need a ''csspostprocess'' function and then a function for each of the three settings we have that will do the replacements.
<code php>
// This is our css post process function
function demystified_process_css($css, $theme) {};
// This replaces [[setting:backgroundcolor]] with the background colour
function demystified_set_backgroundcolor($css, $backgroundcolor) {};
// This replaces [[setting:regionwidth]] with the correct region width
function demystified_set_regionwidth() {$css, $regionwidth};
// This replaces [[setting:customcss]] with the custom css
function demystified_set_customcss() {$css, $customcss};
</code>

What you should note about the above functions is that they all start with the theme's name. This is required to ensure that the functions are named uniquely as it is VERY unlikely that someone has already created these functions.

So with our plan set out lets start writing the code.

===Writing the code===
The very first thing that we need to do is create a lib.php for our theme into which our css processing functions are going to go. So please at this point create '''theme/demystified/lib.php''' and open it in your editor ready to go.

The first bit of code we have to write is the function that will be called by Moodle to do the processing '''demystified_process_css'''.

Before we start out please remember that the wonderful thing about coding is that there is any number of solutions to a problem. The solutions that you are seeing here in this tutorial are solutions that I have come up with to meet fulfil the needs of the tutorial without being so complex that they are hard to understand. This probably isn't how I would go about it normally but this is a little easier to understand for those who aren't overly familiar with PHP and object orientation.

====The function: demystified_process_css====

<code php>
function demystified_process_css($css, $theme) {

if (!empty($theme->settings->backgroundcolor)) {
$backgroundcolor = $theme->settings->backgroundcolor;
} else {
$backgroundcolor = null;
}
$css = demystified_set_backgroundcolor($css, $backgroundcolor);

if (!empty($theme->settings->regionwidth)) {
$regionwidth = $theme->settings->regionwidth;
} else {
$regionwidth = null;
}
$css = demystified_set_regionwidth($css, $regionwidth);

if (!empty($theme->settings->customcss)) {
$customcss = $theme->settings->customcss;
} else {
$customcss = null;
}
$css = demystified_set_customcss($css, $customcss);

return $css;
}
</code>

So lets look at the things that make up this function:

<code php>
function demystified_process_css($css, $theme) {
//.....
return $css
}
</code>

This of course is the function declaration.

The function gets given two variables, the first '''$css''' is a pile of CSS as one big string, and the second is the theme object '''$theme''' that contains all of the configuration, options, and settings for our theme.

It then returns the ''$css'' variable, essentially returning the modified CSS.

<code php>
//...
if (!empty($theme->settings->backgroundcolor)) {
$backgroundcolor = $theme->settings->backgroundcolor;
} else {
$backgroundcolor = null;
}
$css = demystified_set_backgroundcolor($css, $backgroundcolor);
//...
</code>

Here we are processing our first setting ''backgroundcolor''.

The first thing that we need to do is check whether it has been set and whether it has a value. If it has then we store that value in '''$backgroundcolor'''. It is doesn't have a value then we set ''$backgroundcolor'' to null. This ensures that ''$backgroundcolor'' is set because if it isn't then you are going to get a notice (if you have debugging on).

The final line of this block calls the function '''demystified_set_backgroundcolor'''. We haven't written this function yet but we will shortly. When we call it we give it the ''$css'' variable that contains all of the CSS and we give it the background colour variable ''$backgroundcolor''. Once this function is finished it returns the ''$css'' variable with all of the changes made much like how our css processing function works.

What you should also note about this code is this:
<code php>
$theme->settings->backgroundcolor
</code>
As mentioned earlier ''$theme'' is an object that contains all of the configuration and settings for our theme. The ''$theme'' object has a $settings property which contains all of the settings for our theme, and finally the settings property contains a variable backgroundcolor that is the value the user entered for that setting. That is how we get a settings value.

<code php>
if (!empty($theme->settings->regionwidth)) {
$regionwidth = $theme->settings->regionwidth;
} else {
$regionwidth = null;
}
$css = demystified_set_regionwidth($css, $regionwidth);

if (!empty($theme->settings->customcss)) {
$customcss = $theme->settings->customcss;
} else {
$customcss = null;
}
$css = demystified_set_customcss($css, $customcss);
</code>

These two routines are nearly identical to the routine above. For both the regionwidth and the customcss we make sure it has a value and then store it in a variable. We then call the relevant function to make the changes for that setting.

Now that we have the general processing function it is time to write the three functions we have used but not written, ''demystified_set_backgroundcolor'', ''demystified_set_regionwidth'', ''demystified_set_customcss''.

====The function: demystified_set_backgroundcolor====

First up demystified_set_backgroundcolor.

<code php>
/**
* Sets the background colour variable in CSS
*
* @param string $css
* @param mixed $backgroundcolor
* @return string
*/
function demystified_set_backgroundcolor($css, $backgroundcolor) {
$tag = '[[setting:backgroundcolor]]';
$replacement = $backgroundcolor;
if (is_null($replacement)) {
$replacement = '#DDDDDD';
}
$css = str_replace($tag, $replacement, $css);
return $css;
}
</code>

Ok so what is happening here?

First we need a variable '''$tag''' that contains the tag we are going to replace. As mentioned earlier we are going to use tags that look like the image tags you are already familiar with ''<nowiki>[[setting:settingname]]</nowiki>'', in this case ''<nowiki>[[setting:backgroundcolor]]</nowiki>''.

Next I am going to create a variable called '''$replacement''' into which I put '''$backgroundcolor'''.

The '''IF''' statement that comes next checks ''$replacement'' to make sure it is not null. If it is then we need to set it to a default value. In this case I have used ''#DDD'' as that was the default for the settings.

The line after the IF statement puts it all together. The ''str_replace'' function that we are calling takes three arguments in this order:
# The text to search for.
# The text to replace it with.
# The text to do the replacement in.
It then returns the text with all of the replacements made. So in this case we are replacing the tag with the background colour and it is returning the changed CSS.

The final thing is to return the ''$css'' variable which now contains the correct background colour.

====The function: demystified_set_regionwidth====

Next we have the demystified_set_regionwidth function.
<code php>
/**
* Sets the region width variable in CSS
*
* @param string $css
* @param mixed $regionwidth
* @return string
*/
function demystified_set_regionwidth($css, $regionwidth) {
$tag = '[[setting:regionwidth]]';
$doubletag = '[[setting:regionwidthdouble]]';
$replacement = $regionwidth;
if (is_null($replacement)) {
$replacement = 200;
}
$css = str_replace($tag, $replacement.'px', $css);
$css = str_replace($doubletag, ($replacement*2).'px', $css);
return $css;
}
</code>

This function is very similar to the above function however there is one key thing we are doing different. We are doing two replacements.

# The first replacement is for the width that the user selected. In this case I am replacing the tag ''<nowiki>[[setting:regionwidth]]</nowiki>'' with the width.
# The second replacement is for the width x 2. This is because the page layout requires that the width be doubled for some of the CSS. Here I will replace ''<nowiki>[[setting:regionwidthdouble]]</nowiki>'' with the doubled width.

Remember because it is still just a number we need to add '''px''' to the end of each before we do the replacement.

So the overall process of this function is:
# Define the two tags as '''$tag''' and '''$doubletag'''.
# Make '''$replacement''' the region width ''$regionwidth''.
# Set ''$replacement'' to a default value of 200 is it is null.
# Replace '''<nowiki>[[setting:regionwidth]]</nowiki>''' with the width.
# Replace '''<nowiki>[[setting:regionwidthdouble]]</nowiki>''' with the width x 2.
# Return the changed CSS.

====The function: demystified_set_customcss====

The final function that we need to write is the demystified_set_customcss function.
<code php>
/**
* Sets the custom css variable in CSS
*
* @param string $css
* @param mixed $customcss
* @return string
*/
function demystified_set_customcss($css, $customcss) {
$tag = '[[setting:customcss]]';
$replacement = $customcss;
if (is_null($replacement)) {
$replacement = '';
}
$css = str_replace($tag, $replacement, $css);
return $css;
}
</code>

This function is just like the first function. I'm going to let you work it out on your own.

And that is it no more PHP... Hallelujah I can hear you yelling. The final thing we need to do is tell our theme about the functions we have written and put the settings tags into the CSS.

===Finishing it all off===

So there are two things we have to do in order to complete this section and have our the settings page implemented and our settings being used.

First we need to tell our theme that we want to use the function ''demystified_process_css'' as the ''csspostprocess'' function. This is done very simply by adding the following line of PHP to the bottom of our theme's config.php file '''theme/demystified/config.php'''.

<code php>
$THEME->csspostprocess = 'demystified_process_css';
</code>

With that done the only thing left is to add the settings tag into the CSS. Remember those settings tags are:

; <nowiki>[[setting:backgroundcolor]]</nowiki> : We need to add this where ever we want the background colour setting to be used.
; <nowiki>[[setting:regionwidth]]</nowiki> : We need to add this where ever we want to set the width of the block regions.
; <nowiki>[[setting:regionwidthdouble]]</nowiki> : We need to add this where ever we want to set the doubled width of the block regions.
; <nowiki>[[setting:customcss]]</nowiki> : We need to add this to the bottom of the CSS file that we want the custom CSS added to.

So lets make those changes in CSS now, open up your ''core.css'' file and replace the CSS with the CSS below:
<code css>
/** Background color is a setting **/
html {background-color:[[setting:backgroundcolor]];}
body {margin:30px;padding:0;border:1px solid #333;border-width:0 10px 0 10px;background-color:#333;}
body #page {background-color:#FFF;position:relative;top:-10px;}
.block .header {background-image:none;background-color:#0C5CAC;border:1px solid #0C5CAC;color:#FFF;}
.block {border-color:#4BA7FF;background-color:#DDEEFF;}
.block .content {background-color:#F1F8FF;}
a:link,
a:visited {color:#0C5CAC;}
a:hover {color:#C77500;}
#page #page-header {background-color:#0C5CAC;margin:0;padding:0;width:100%;color:#fff;}
#page #page-header a:link, #page #page-header a:visited {color:#FFAC02}
#page #page-header .navbar, #page #page-header .navbar a:link, #page #page-header .navbar a:visited {color:#0C5CAC;}
/** Override the region width **/
#page-content #region-main-box {left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidthdouble]];}
#page-content #region-main-box #region-post-box #region-pre {width:[[setting:regionwidth]];left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-post {width:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidthdouble]];}
.side-pre-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-pre-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
/** Custom CSS **/
[[setting:customcss]]
</code>

You will notice that <nowiki>[[setting:backgroundcolor]]</nowiki> has been used for the html tags background colour:
<code css>
html {background-color:[[setting:backgroundcolor]];}
</code>

We have also set the width of the block regions by adding <nowiki>[[setting:regionwidth]]</nowiki> as the width for region-pre and region-post as shown below:
<code css>
#page-content #region-main-box {left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidthdouble]];}
#page-content #region-main-box #region-post-box #region-pre {width:[[setting:regionwidth]];left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-post {width:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidthdouble]];}
.side-pre-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-pre-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
</code>
You'll notice here that we have to set several different widths and margins using the regionwidth setting and make use of the special regionwidthdouble setting that we added.

The final thing that we did was add the <nowiki>[[setting:customcss]]</nowiki> to the bottom of the file to ensure that the custom CSS comes last (and therefore can override all other CSS).

And with that we are finished. The screenshot below shows how this now looks in the browser if I set the background colour setting to '''<span style='color:#FFA800;'>#FFA800</span>''' and made the column width 240px;

[[Image:Theme.settings.page.04.png|715px|thumb|left|Our settings in action]]<br style="clear:both;" />

==Using the settings within our layout files==
Now that we have utilised the first three settings within our theme's CSS file it is time to implement the other two settings within the layout files so that they are written directly into the page.

You'll be glad to know this is no where near as difficult as utilising settings within a CSS file although it still does require a little bit of PHP.

First up is the logo setting. Into this setting the user is able to enter the URL to an image to use as the logo for the site. In my case I want this to be just a background logo on top of which I want to position the page header.

Before I start there is one thing I need to do however and that is create a default logo background that gets shown if the user hasn't set a specific logo file. To do this I simply created an image '''logo.jpg''' and put it into a pix directory within the demystified theme. You should end up with '''theme/demystified/pix/logo.jpg'''.

Next open up the front-page layout file ''theme/demystified/layout/frontpage.php''. At the top of the file is the PHP that checks what blocks regions the page has and a bit of other stuff. Well right below the existing bit of PHP we want to add the following code:
<code php>
if (!empty($PAGE->theme->settings->logo)) {
$logourl = $PAGE->theme->settings->logo;
} else {
$logourl = $OUTPUT->pix_url('logo', 'theme');
}
</code>
What we are doing here is creating a variable called $logourl that will contain the URL to a logo file that was either entered by the user or if they left it blank is that of our default logo file.

There are two things that you should notice about this. First the logo setting can be retrieved through '''$PAGE->theme->settings->logo''' and second we get the default logo url by calling '''$OUTPUT->pix_url('logo', 'theme')'''.

Now that we have the logo URL we are going to use we need to add an image to the header section of the page as shown below:
<code php>
<div id="page-header" class="clearfix">
<img class="sitelogo" src="<?php echo $logourl;?>" alt="Custom logo here" />
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
....
</code>

If you save that and browse to your sites front page you will notice that the logo file is now being shown. Hooray. However it is probably not styled too nicely so lets quickly fix that. Open up the core.css file and add the following lines of CSS to the bottom of the file.
<code css>
#page-header {position:relative;min-height:100px;}
#page-header .sitelogo {float:left;}
#page-header .headermain {position:absolute;left:0.5em;top:50px;margin:0;float:none;font-size:40px;}
</code>
These three lines position the image correctly and if you now refresh everything should appear perfectly.

With the logo done the last setting we need to deal with is the footnote setting. The idea with this setting was that the administrator could enter some text into the editor and it would be displayed in the footer of the page.

This is probably the easiest setting to implement.

Within the front page layout file that we edited above add the following lines below those we added previously.

<code php>
if (!empty($PAGE->theme->settings->footnote)) {
$footnote = $PAGE->theme->settings->footnote;
} else {
$footnote = '';
}
</code>

Here we are just collecting the footnote into a variable '''$footnote''' and setting a default footnote comment if the user hasn't entered one.

We can now echo the $footnote variable within the page footer. This can be done as shown below.

<code php>

<div id="page-footer">
<div class="footnote"><?php echo $footnote; ?></div>
<p class="helplink">
<?php echo page_doc_link(get_string('moodledocslink')) ?>
</p>
</code>

And with that done we are finished! Congratulations if you got this far.

The screenshot below shows the demystified theme we have just created that is styled by the settings page.

[[Image:Theme.settings.page.05.png|715px|thumb|left|My finished demystified theme]]<br style="clear:both" />

==Testing our creation==
Congratulations to you! If you've made it this far you have done very well. Now it is time to have a look at what we have created and give it a quick test run.

So in this tutorial we have achieved the following:

* We created a theme called demystified that is based on the standard theme.
* We added a settings page to our new theme.
* We added the following settings to our settings page:
** We can set a background colour through the admin interface.
** We can change the logo of the site.
** We can change the block region width.
** We can add a footnote to the page footer
** We can add some custom CSS to seal the deal.
* Those settings were then used in the CSS files for our theme.
* They were also used in the layout files for our theme.
* And here we are testing it all.

The screenshots below show my testing process and I change each setting and view the outcome. The great thing about this is that with theme designer mode on you see the changes as soon as the form refreshes.

[[Image:Theme.settings.page.06.png|300px|thumb|left|Default settings]]
[[Image:Theme.settings.page.07.png|300px|thumb|left|Changed the background colour setting]]
[[Image:Theme.settings.page.08.png|300px|thumb|left|Changed the logo and region width]]
[[Image:Theme.settings.page.09.png|300px|thumb|left|Added a footnote]]
[[Image:Theme.settings.page.10.png|300px|thumb|left|Added some custom CSS]]
<br style="clear:both" />

==The different settings you can use==
During this tutorial we use four different kinds of settings, a text box, text area, a select (dropdown) and the editor however as I'm sure you have all guessed there is many more some of which will certainly be useful for theme settings.

The following are examples of some of the different settings. I should add that these build upon what we have already done within the tutorial but are not included in the download.

===Colour picker===
[[Image:Theme.settings.page.11.png|400px|thumb|The colour picker]]
I can hear you all asking now 'Why didn't you mention this one earlier?' well the answer is simple it didn't exist when I first wrote the tutorial. It is an admin setting that I wrote several days after because of the fantastic effort people were putting into trying out settings pages.

A bit about the colour picker. First up it is a text box that when the page loads turns into a colour picker that can be used to select a colour and can even preview the selected colour in the page (by clicking the preview button). It is designed to be very easy to use and the code is just about as simple as creating a normal text box setting.

In the image to the left I have replaced the background colour setting we created during the tutorial with the colour picker. Lets have a look at the code involved for that.
<code php>
// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$previewconfig = array('selector'=>'html', 'style'=>'backgroundColor');
$setting = new admin_setting_configcolourpicker($name, $title, $description, $default, $previewconfig);
$temp->add($setting);
</code>
So first thing you should notice is that the first four lines of code have not changed at all!

The first change we have is to create a variable '''$previewconfig'''.
This variable is used to tell the colour picker what to do when the user clicks the preview button. It should be an array that contains two things, first a selector, and second a style.
# The selector is a CSS selector like ''.page .header h2''.
# The style is a what should change, there are two immediate values it can be, either '''backgroundColor''' or '''color'''.
In my case the selector is '''html''' to target the html tag and the style is backgroundColor to change the background colour.

The second change is to use '''admin_setting_configcolourpicker''' instead of ''admin_setting_configtext''. The arguments are nearly identical as well except that there is an extra argument to which we give the '''$previewconfig''' variable.

And that is it! it is all you need to get the colour picker up and running.

'''Extra note:''' The $previewconfig variable is optional. If you don't want a preview button the simply set ''$previewconfig = null''

==Common pitfalls and useful notes==

This section is really just a collection of pointers, tips, notes, and other short useful stuff that may be of use to those attempting this tutorial.

# First up and most importantly there are very few limitations to what you achieve in this fashion.
# If you get stuck or need a hand ask in the forums, there's always someone round who can help.
# If you do something really cool let us know, I know everyone in the community loves finding our what others are achieving.
# You don't have to use ''admin_settingpage'' you can also use '''admin_externalpage''' if you prefer. It should be noted however that it is not the preferred way to do it as admin_externalpage's were only left in Moodle 2.0 for backwards compatibility (although they are more flexible one day they will be deprecated or removed). Thank you to Darryl for raising this.
# If you find that your language strings aren't being used (you are getting language string notices) and you have double checked that you have turned '''langstringcache''' off then you may need to delete the language cache directory. This is located in the moodledata directory for you installation: moodledata/cache/lang/*. You should delete the directory for your chosen language by default ''en''.

==See also==

* [[Adding theme upgrade code]]
* [[Styling and customising the dock]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=152053 Theme 2.0: Adding a settings page to your theme] forum discussion

Creating a theme settings page

2014-09-24T22:05:31Z

Tqr: /* Finishing settings.php */ -updating

{{Template:Themes}}This document looks at how to create a settings page for your Moodle 2.x.x theme and how to make use of those settings within the CSS and layout files for your theme.

This is a pretty advanced topic and will require that you have at least an intermediate knowledge of PHP, CSS, and development in general.

==Before we begin==
[[Image:Theme.settings.page.03.png|350px|thumb|Our end goal. The settings page.]]
[[Image:Theme.settings.page.10.png|350px|thumb|And what it can do.]]
There is a huge body of knowledge that we must cover in following through this document and as such I think the best way to write this is as a tutorial.

My intentions for this tutorial are to replicate the standard theme but with a settings page that allows the administrator to set a background colour, set a logo to use with the page, and probably several other minor settings to change the way in which the theme is displayed.

I will start this tutorial by creating a new theme which will be largely a copy/paste of the current standard theme. I expect that anyone working through this tutorial has previously read the tutorial I wrote on [[Themes 2.0 creating your first theme|creating your first theme]]. If you haven't go read it now because I'm not going to go into much detail until we get to the actual process of customising the theme and introducing the settings page.

So before we finally get this started please ensure you can check off everything on the following requirements list.
* Have a Moodle installation that has already been installed and configured and is ready to use.
* Have full read/write access to that installation.
* Be prepared to delete that installation at the end of this... we will destroy it!
* Have a development environment prepared and ready to use. This includes:
** Your favourite editor installed, running, and pointed at the themes directory of your installation.
** Your browser open and your site visible.
** A bottomless coffee pot... decaf won't help you with this one.
* Have set the following settings:
** '''themedesignermode''' if you don't know what this is please read the [[Themes 2.0 creating your first theme|creating your first theme]] tutorial.
** '''allowthemechangeonurl''' turn this on, it allows you to change themes on the URL and is very handy when developing themes. ''Site Administration > Appearance > Themes > Theme settings''
** '''langstringcache''' if you don't turn this off you won't see your strings when they are added. ''Site Administration > Language > Language settings''
* And finally an insane ambition to create a customisable theme.

For those interested the theme that I create throughout this tutorial can be downloaded from the forum post in which I announce this document: http://moodle.org/mod/forum/discuss.php?d=152053
<br style="clear:right;" />

==Our goals for this tutorial==
The following is just a list goals that I hope to achieve during this tutorial. They are laid out here so that I can easily refer back to them and so that you can easily find them.
# Create a new theme called '''demystified''' based upon the standard theme within Moodle 2.0.
# Make some minor changes to that theme to allow us to more easily see what is going on.
# Create a settings page for the demystified theme.
# Add several settings to our settings page.
# Use some of those settings to alter our CSS.
# Use the rest of those settings within our layout file..
# Discuss the good, the bad, and limits of what we have just created.

So I can see you are all very excited about this point and that you would love to know what settings we are going to create; So here they are:

A setting to ...
* change the background colour (CSS).
* set the path to an image that we will use as a logo on all pages (Layout files).
* override the width of the block regions (CSS).
* allow a note to be added to the footer of all pages (Layout files).
* allow custom CSS to be written to do anything the user wants. (CSS)

==Creating the demystified theme==
Before we start here I want to remind you that I am going to look at this only briefly as I am making the assumption that you have read the [[Themes 2.0 creating your first theme|creating your first theme]] tutorial.

Well lets get into it....

The first thing we need to do is create a directory for our theme which we will call demystified.

So within your Moodle directory create the following folder '''moodle/theme/demystified'''. At the same time you can also create the following files and folders which we will get to soon.
* The file '''moodle/theme/demystified/config.php''' for our config information.
* The directory '''moodle/theme/demystified/layout''' for our layout files.
* The directory '''moodle/theme/demystified/style''' for our css files.
* The file '''moodle/theme/demystified/style/core.css''' which will contain our special CSS.

Next we will copy the layout files from the base theme to our new theme demystified. We are basing the demystified theme on the standard theme however that doesn't use it's own layout files it uses the base theme's layout files so those are the ones we want.

The reason that we are coping these layout files is that later on in this tutorial we will be modifying them to make use of our new settings... so copy all of the layout files from '''moodle/theme/base/layout''' to '''moodle/theme/demystified/layout'''.

There should be three files that you just copied:
# embedded.php
# frontpage.php
# general.php

Now we need to populate demystified/config.php with the settings for our new theme. They are as follows:
<code php>
$THEME->name = 'demystified';
</code>
Simply sets the name of our theme.

<code php>
$THEME->parents = array('standard','base');
</code>
This theme is extending both the standard theme and the base theme. Remember when extending a theme you also need to extend its parents or things might not work correctly.

<code php>
$THEME->sheets = array('core');
</code>
This tells our theme that we want to use the file '''demystified/style/core.css''' with this theme.

<div style="height:300px;overflow-y:scroll;">
<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-post',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'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),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>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),
),
// 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),
),
);
</code>
</div>
Now that all looks very complicated however its really not too bad as it is just copied from the base theme's config.php file. We can do this because we copied the layout files from the base theme to begin with and for the time being there are no changes that we wish to make. Simply open up '''theme/base/config.php''' and copy the layouts from there.

And that is it. The config.php file for our demystified theme is complete. The full source is shown below:
<div style="height:300px;overflow-y:scroll;">
<code php>
<?php

// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* The demystified theme config file
*
* This theme was created to document the process of adding a settings page to a theme
*
* @copyright 2010 Sam Hemelryk
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

// The name of our theme
$THEME->name = 'demystified';

// The other themes this theme extends
$THEME->parents = array('standard','base');

// The CSS files this theme uses (located in the style directory)
$THEME->sheets = array('core');

// The layout definitions for this theme
$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-post',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'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),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>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),
),
// 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),
),
);
</code>
</div>

The screenshot below shows both the directory structure we have now created and the theme presently.

[[Image:Theme.settings.page.01.png]]

To view the theme so far open you browser and enter the URL of your site followed by '''?theme=demystified'''. You should see the theme that we just created which will look exactly like the base standard theme.

The final thing that we want to do is add a little bit of CSS to the demystified theme that will both visually set this theme apart from the standard theme and second build a the base which our settings can later extend.

I added the following snippet of CSS to the file '''demystified/style/core.css'''.
<code css>
html {background-color:#DDD;}
body {margin:30px;padding:0;border:1px solid #333;border-width:0 10px 0 10px;background-color:#333;}
body #page {background-color:#FFF;position:relative;top:-10px;}
.block .header {background-image:none;background-color:#0C5CAC;border:1px solid #0C5CAC;color:#FFF;}
.block {border-color:#4BA7FF;background-color:#DDEEFF;}
.block .content {background-color:#F1F8FF;}
a:link,
a:visited {color:#0C5CAC;}
a:hover {color:#C77500;}
#page #page-header {background-color:#0C5CAC;margin:0;padding:0;width:100%;color:#fff;}
#page #page-header a:link, #page #page-header a:visited {color:#FFAC02}
#page #page-header .navbar, #page #page-header .navbar a:link, #page #page-header .navbar a:visited {color:#0C5CAC;}
</code>

The CSS that we have just added to our theme sets a couple of colours on the front page. Presently this is the only CSS I will add, I know it isn't complete by any means but it achieves it's purpose as the screenshot below illustrates.

[[Image:Theme.settings.page.02.png|715px|thumb|left|The newly styles demystified theme]]<br style="clear:both;" />

And with that I will move on to the real purpose of this tutorial, creating the settings page

==Setting up the settings page==
With the demystified theme set up it is time to create the settings page. This is where the real PHP fun begins.

For those of you who happen to be familiar with development of modules, blocks or other plugin types you have probably encountered settings pages before and this is not going to be any different.

However for those who haven't which I imagine is most of you this is going to be quite a challenge. I will try to walk through this step by step however if at any point you get stuck don't hesitate to ask in the forums as I imagine you will get a speedy response.

===How settings pages work in Moodle===
Settings pages can be used by nearly every plugin type, of which themes is of course one. The way in which it all works isn't too tricky to understand.

All of the settings for Moodle can be configured through the administrator interfaces when logged in. I am sure that everyone here has seen those pages and has changed a setting or two before so you will all know what I am talking about. Well the settings page for a theme is no different. It will be shown in the administration pages tree under '''Appearance > Themes''' and all we have to do is tell Moodle what settings there are.

This is done by creating a settings.php file within our theme into which we will add code that tells Moodle about the settings we want to add/use.

When telling Moodle about each setting we are simply creating a new ''admin_setting'' instance of the type we want and the properties we want and then adding it to our settings page.

There is really not much more too it at this level. Things can get very complex very fast so the best thing we can do now is start creating our settings.php file for the demystified theme and see where it leads us.

===Creating the settings page===
So as mentioned before we need a settings.php file which we will create now. To begin with create the file '''theme/demystified/settings.php''' and open it in your favourite editor so its ready to go.

Before we start adding code however lets just remember the settings that we want to create:
* change the background colour (CSS).
* set the path to an image that we will use as a logo on all pages (Layout files).
* override the width of the block regions (CSS).
* allow a note to be added to the footer of all pages (Layout files).
* allow custom CSS to be written to do anything the user wants. (CSS)

Alright.

Now thinking about this the first setting is as basic as it gets, all we need is a text box that the user can type a colour into.

The second is to allow a logo to be used in the header of each page. What we want here is a path but should it be a physical path e.g. C:/path/to/image.png or should it be a web path e.g. <nowiki>http://mysite.com/path/to/image.png</nowiki>?
For the purpose of this tutorial I am going to go with a web path because it is going to be easier to code and will hopefully be a little easier to understand to begin with.

The third setting is a little more complex. For this I want a drop down box with some specific widths that the administrator can select.

The forth and the fifth settings are both pretty straight forward, there we want a textarea into which the user can enter what ever they want and we will do something useful with it.

Now that we have an understanding about the settings we wish to define pull up your editor and lets start coding....

<code php>
<?php

/**
* Settings for the demystified theme
*/
defined('MOODLE_INTERNAL') || die;

if ($ADMIN->fulltree) {
</code>
This is the first bit of code we must enter, the first line is of course just the opening php tag, secondly we have a comment that describes this file, and then we get create a new '''admin_settingspage object'''.

This admin_settingspage object that we have just created is a representation of our settings page and is the what we add our new settings to. When creating it we give it two arguments, first the name of the page which is in this case '''theme_''themename''''' and the title for the page which we get with the get_string method.

At the moment I'm not going to worry about adding the string, we will get to that later once we have defined all of our settings.

====Background colour====

With the page now created lets add our first setting: Background colour.

<code php>
// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$setting = new admin_setting_configtext($name, $title, $description, $default, PARAM_CLEAN, 12);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
Thankfully this isn't as difficult as it initially looks.

The first line of code is creating a variable for the name of the background colour setting. In this case it is '''theme_demystified/backgroundcolor'''.

The name is very important, for the setting to be usable we have to follow a strict naming convention. '''theme_''themename''/''settingname''''' where '''''themename''''' is the name of the theme the setting belongs to and '''''settingname''''' is the name for the setting by which we will use it.

The second line of code creates a variable that contains the title of the setting. This is what the user sees to the right of the setting on the settings page and should be a short description of the setting. Here we are again using the ''get_string'' method so we will need to remember to add that string later on.

The third line of code sets the description. This should describe what the setting does or how it works and again we will use the get_string method.

The fourth line creates a variable that will be used as the default value for the setting. Because this setting is a colour we want an HTML colour to be the default value.

The fifth line is where we put it all together. Here we create a new '''admin_setting_configtext''' object. This object will represent the background colour setting.

When we create it we need to give it 6 different things.
# The name of the setting. In this case we have a variable '''$name'''.
# The title for this setting. We used the variable '''$title'''.
# The description of the setting '''$description'''.
# The default value for the setting. '''$default''' is the variable this.
# The type of value we want the user to enter. For this we have used PARAM_CLEAN which tells Moodle to get rid of any nasties from what the user enters.
# The size of the field. In our case 12 characters will be plenty.

The sixth and final line of code adds our newly created setting to the administration page we created earlier.

That is it we have successfully created and added our first setting, however there are several more to settings to do, and there are a couple of important things that you need to be aware of before we move on.

First: There are several different types of settings that you can create and add to a page, and each one may differ in what they need you to give them. In this case it was name, title, description, default, type, and size. However other settings will likely require different things. Smart editors like Netbeans or Eclipse can tell you what is required, otherwise you will need to research it.

Second: Normally settings are declared on one line as follows:
<code php>
$setting->add(new admin_setting_configtext('theme_demystified/backgroundcolor', get_string('backgroundcolor','theme_demystified'), get_string('backgroundcolordesc', 'theme_demystified'), '#DDD', PARAM_CLEAN, 12));
</code>
While this is structurally identical as all we have done is move everything onto one line and do away with the variables it is a little harder to read when you are learning all of this.

====The logo file====
Time to create the second setting that will allow the user to enter a URL to an image they wish to use as the logo on their site.
<code php>
// Logo file setting
$name = 'theme_demystified/logo';
$title = get_string('logo','theme_demystified');
$description = get_string('logodesc', 'theme_demystified');
$setting = new admin_setting_configtext($name, $title, $description, '', PARAM_URL);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
The first thing that you will notice about this setting that it is very similar to the first setting, in fact all we have changed is the name, title, description, and default value. We have however changed the value type from PARAM_CLEAN to PARAM_URL, this makes sure the user enters a URL. You will also notice that for this one we don't set a size for the field as we have no idea how long the URL will be.

====Block region width====
The third setting should allow the user to set a width for the block regions that will be used as columns.

For this setting I want to do something a little different from the previous two, here I want to use a select box so that the user selects a width for the column from a list I provide.
<code php>
// Block region width
$name = 'theme_demystified/regionwidth';
$title = get_string('regionwidth','theme_demystified');
$description = get_string('regionwidthdesc', 'theme_demystified');
$default = 200;
$choices = array(150=>'150px', 170=>'170px', 200=>'200px', 240=>'240px', 290=>'290px', 350=>'350px', 420=>'420px');
$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
So looking at the code: The first four lines you will recognise. $name, $title, $description, and $default are all being set.

The fifth line of code however introduces something new. Of course in order to have a select box we have to have options, in this case we have an array of options stored in the variable $choices.

The array of options is constructed of a collection of '''''value''' => '''label''''' pairs. Notice how we don't add '''px''' to the value. This is is very intentional as later on I need to do a little bit of math with that value so we need it to be a number.

The lines after should look familiar again, the only difference being that instead of a ''admin_setting_configtext'' setting we have created a ''admin_setting_configselect'' for which we must give the choices for the select box as the fifth argument.

Woohoo, we've just created our first select box setting.

====Foot note====
Now to create the foot note setting. Here we want the user to be able to enter some arbitrary text that will be used in the footer of the page. For this I want the user to be able to enter some HTML so I will create an editor setting.
<code php>
// Foot note setting
$name = 'theme_demystified/footnote';
$title = get_string('footnote','theme_demystified');
$description = get_string('footnotedesc', 'theme_demystified');
$setting = new admin_setting_confightmleditor($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
How simple is that!

It is just about identical to the first two settings except that for this we have created a ''admin_setting_confightmleditor'' setting rather than a text setting.

Note: You can also set the columns and rows for the editor setting using the fifth and sixth arguments.

====Custom CSS====
The final setting is to allow the user to add some custom CSS to the theme that will be used on every page. I want this to be a plain textarea into which the user can enter CSS.
<code php>
// Custom CSS file
$name = 'theme_demystified/customcss';
$title = get_string('customcss','theme_demystified');
$description = get_string('customcssdesc', 'theme_demystified');
$setting = new admin_setting_configtextarea($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
Just like the editor or text settings. It's getting very easy now!

====Finishing settings.php====
With all of our settings defined and added to our page that we created right at the beginning it is time to finish it all off.
<code php>
// Add our page to the structure of the admin tree
$ADMIN->add('themes', $temp);
</code>
The above line of code is the final line for the page. It is adding the page that we have created '''$temp''' to the admin tree structure. In this case it is adding it to the themes branch.

The following is the completed source for our settings.php ..... for your copy/paste pleasure.
<div style='height:300px;overflow:auto;'>
<code php>
<?php
/**
* Settings for the demystified theme
*/
defined('MOODLE_INTERNAL') || die;

if ($ADMIN->fulltree) {

// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$setting = new admin_setting_configtext($name, $title, $description, $default, PARAM_CLEAN, 12);
$temp->add($setting);

// Logo file setting
$name = 'theme_demystified/logo';
$title = get_string('logo','theme_demystified');
$description = get_string('logodesc', 'theme_demystified');
$setting = new admin_setting_configtext($name, $title, $description, '', PARAM_URL);
$temp->add($setting);

// Block region width
$name = 'theme_demystified/regionwidth';
$title = get_string('regionwidth','theme_demystified');
$description = get_string('regionwidthdesc', 'theme_demystified');
$default = 200;
$choices = array(150=>'150px', 170=>'170px', 200=>'200px', 240=>'240px', 290=>'290px', 350=>'350px', 420=>'420px');
$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$temp->add($setting);

// Foot note setting
$name = 'theme_demystified/footnote';
$title = get_string('footnote','theme_demystified');
$description = get_string('footnotedesc', 'theme_demystified');
$setting = new admin_setting_confightmleditor($name, $title, $description, '');
$temp->add($setting);

// Custom CSS file
$name = 'theme_demystified/customcss';
$title = get_string('customcss','theme_demystified');
$description = get_string('customcssdesc', 'theme_demystified');
$setting = new admin_setting_configtextarea($name, $title, $description, '');
$temp->add($setting);

// Add our page to the structure of the admin tree
$ADMIN->add('themes', $temp);
</code>
</div>

===Creating a language file and adding our strings===
As I'm sure none of you have forgotten, throughout the creation of the our settings.php page, we used a lot of strings that I mentioned we would set later on. Well now is the time to set those strings.

First up create the following directories and file for our language strings:
* Directory '''theme/demystified/lang'''
* Directory '''theme/demystified/lang/en'''
* File '''theme/demystified/lang/theme_demystified.php'''

What we have created here is the required structure for Moodle to start looking for language strings.

First Moodle locates the lang directory, once found it looks within that directory for another directory that uses the character code for the language the user has selected, by default this is '''en''' for English. Once that is found it looks for the appropriate language file, in this case '''theme_demystified.php''' from which it will load all language strings for our theme.

If English isn't your chosen language simply replace the ''en'' directory with one that uses your chosen languages character code (two letters).

We can now add our language strings to '''theme/demystified/lang/theme_demystified.php'''. Copy and paste the following lines of PHP into this file.
<code php>
<?php

/**
* This file contains the strings used by the demystified theme
*/

$string['backgroundcolor'] = 'Background colour';
$string['backgroundcolordesc'] = 'This sets the background colour for the theme.';
$string['configtitle'] = 'Demystified theme';
$string['customcss'] = 'Custom CSS';
$string['customcssdesc'] = 'Any CSS you enter here will be added to every page allowing your to easily customise this theme.';
$string['footnote'] = 'Footnote';
$string['footnotedesc'] = 'The content from this textarea will be displayed in the footer of every page.';
$string['logo'] = 'Logo';
$string['logodesc'] = 'Enter the URL to an image to use as the logo for this site. Should be http://www.yoursite.com/path/to/logo.png';
$string['pluginname'] = 'Demystified';
$string['regionwidth'] = 'Column width';
$string['regionwidthdesc'] = 'This sets the width of the two block regions that form the left and right columns.';
</code>

In the above lines of code I have added an entry for each language string we used within ''settings.php''. When adding language strings like this make sure you use single quotes and try to keep things alphabetical - it helps greatly when managing strings.

Now when we view the settings page there will not be any errors or strings missing.

===Having a look at what we have created===
Now that we have created our settings page (settings.php) and added all of the language strings it is time to have a look at things in your browser.

Open your browser and enter the URL to your site. When you arrive at your site login as an administrator.

If you are not redirected to view the new settings change your URL to <nowiki>http://www.yoursite.com/admin/</nowiki> and your will see a screen to set the new theme settings we have just created. This lets us know that everything has worked correctly.

At any point now you are able to log in as administrator and within the settings block browse to '''Site administration > Appearance > Themes > Demystified theme''' to change those settings.

The screenshot below shows you what you should see at this point:

[[Image:Theme.settings.page.03.png|715px|thumb|left|The settings page we just created]]
<br style="clear:both;" />

==Using the settings in CSS==
With the settings page now created and operational it is time to make use of our new settings. The settings that we want to use within our CSS is as follows:

; backgroundcolor : Will be used to set the background colour in CSS.
; regionwidth : Will be the width of the column for CSS.
; customcss : Will be some custom CSS to add to our stylesheet.

At this point those names are the names we used for our setting with the slash and everything before it having been removed.

Before we start tearing into some code it is important that we have a look at what we are going to do and how we are going to go about it.

===How it all works within Moodle===
The first thing to understand is that while Moodle allows you to create a settings page and automates it inclusion and management right into the administration interfaces there is no smart equivalent for using the settings. This is simply because there is no way to predict how people will want to use the settings.

However don't think of this as a disadvantage, in fact it is quite the contrary. Although we can't just ''use'' our settings we can take full control over how and where we use them. It means it will take a little more code but in the end that will work to our advantage as we can do anything we want.

Moodle does help us out a little but not in an obvious way. The first thing that Moodle does is look for a config variable '''csspostprocess''' that should be the name of a function which we want called to make any changes to the CSS after it has been prepared.

The second thing Moodle does is include a lib.php from the theme's directory if one exists (also for the themes the current theme extends.) which ensures that as long as we write our code within '''theme/demystified/lib.php''' it will be included and ready to be used.

The third and final thing Moodle does that will help us out here is ensure that by the time any of code is ready to execute the settings have been prepared and are ready to be used within a theme config object which is passed into our ''csspostprocess'' function.

===Our plan===
As you have already probably guessed we will need to create a function to make the changes to the CSS that we want. We will then set the theme config option '''$THEME->csspostprocess''' to the name of our function.

By doing this when Moodle builds the CSS file it will call our function afterwards with the CSS and the theme object that contains our setting.

Now we know that we will use the ''csspostprocess'' function but how are we going to change the CSS, we could get the function to add CSS, or we could get the function to replace something within the CSS. My personal preference is to replace something within the CSS, just like what is happening with images. If you want to use an image within CSS you would write <nowiki>[[pix:theme|imagename]]</nowiki>.

For settings I am going to use <nowiki>[[setting:settingname]]</nowiki>, this way it looks a bit like something you are already familiar with.

What we need to decide upon next is the best way in which to replace our settings tag with the settings that the user has set.

There are two immediate options available to us:
# Make the ''csspostprocess'' function do all the work.
# Make the ''csspostprocess'' function call a separate function for each setting.
Solution 1 might sound like the simplest however it is going to result in a '''VERY''' complex function. Remember the user might have left settings blank or entered something that wouldn't be valid so we would need to make the sure there is some validation and a good default.
Because of this I think that solution 2 is the better solution.

So we are going to need a ''csspostprocess'' function and then a function for each of the three settings we have that will do the replacements.
<code php>
// This is our css post process function
function demystified_process_css($css, $theme) {};
// This replaces [[setting:backgroundcolor]] with the background colour
function demystified_set_backgroundcolor($css, $backgroundcolor) {};
// This replaces [[setting:regionwidth]] with the correct region width
function demystified_set_regionwidth() {$css, $regionwidth};
// This replaces [[setting:customcss]] with the custom css
function demystified_set_customcss() {$css, $customcss};
</code>

What you should note about the above functions is that they all start with the theme's name. This is required to ensure that the functions are named uniquely as it is VERY unlikely that someone has already created these functions.

So with our plan set out lets start writing the code.

===Writing the code===
The very first thing that we need to do is create a lib.php for our theme into which our css processing functions are going to go. So please at this point create '''theme/demystified/lib.php''' and open it in your editor ready to go.

The first bit of code we have to write is the function that will be called by Moodle to do the processing '''demystified_process_css'''.

Before we start out please remember that the wonderful thing about coding is that there is any number of solutions to a problem. The solutions that you are seeing here in this tutorial are solutions that I have come up with to meet fulfil the needs of the tutorial without being so complex that they are hard to understand. This probably isn't how I would go about it normally but this is a little easier to understand for those who aren't overly familiar with PHP and object orientation.

====The function: demystified_process_css====

<code php>
function demystified_process_css($css, $theme) {

if (!empty($theme->settings->backgroundcolor)) {
$backgroundcolor = $theme->settings->backgroundcolor;
} else {
$backgroundcolor = null;
}
$css = demystified_set_backgroundcolor($css, $backgroundcolor);

if (!empty($theme->settings->regionwidth)) {
$regionwidth = $theme->settings->regionwidth;
} else {
$regionwidth = null;
}
$css = demystified_set_regionwidth($css, $regionwidth);

if (!empty($theme->settings->customcss)) {
$customcss = $theme->settings->customcss;
} else {
$customcss = null;
}
$css = demystified_set_customcss($css, $customcss);

return $css;
}
</code>

So lets look at the things that make up this function:

<code php>
function demystified_process_css($css, $theme) {
//.....
return $css
}
</code>

This of course is the function declaration.

The function gets given two variables, the first '''$css''' is a pile of CSS as one big string, and the second is the theme object '''$theme''' that contains all of the configuration, options, and settings for our theme.

It then returns the ''$css'' variable, essentially returning the modified CSS.

<code php>
//...
if (!empty($theme->settings->backgroundcolor)) {
$backgroundcolor = $theme->settings->backgroundcolor;
} else {
$backgroundcolor = null;
}
$css = demystified_set_backgroundcolor($css, $backgroundcolor);
//...
</code>

Here we are processing our first setting ''backgroundcolor''.

The first thing that we need to do is check whether it has been set and whether it has a value. If it has then we store that value in '''$backgroundcolor'''. It is doesn't have a value then we set ''$backgroundcolor'' to null. This ensures that ''$backgroundcolor'' is set because if it isn't then you are going to get a notice (if you have debugging on).

The final line of this block calls the function '''demystified_set_backgroundcolor'''. We haven't written this function yet but we will shortly. When we call it we give it the ''$css'' variable that contains all of the CSS and we give it the background colour variable ''$backgroundcolor''. Once this function is finished it returns the ''$css'' variable with all of the changes made much like how our css processing function works.

What you should also note about this code is this:
<code php>
$theme->settings->backgroundcolor
</code>
As mentioned earlier ''$theme'' is an object that contains all of the configuration and settings for our theme. The ''$theme'' object has a $settings property which contains all of the settings for our theme, and finally the settings property contains a variable backgroundcolor that is the value the user entered for that setting. That is how we get a settings value.

<code php>
if (!empty($theme->settings->regionwidth)) {
$regionwidth = $theme->settings->regionwidth;
} else {
$regionwidth = null;
}
$css = demystified_set_regionwidth($css, $regionwidth);

if (!empty($theme->settings->customcss)) {
$customcss = $theme->settings->customcss;
} else {
$customcss = null;
}
$css = demystified_set_customcss($css, $customcss);
</code>

These two routines are nearly identical to the routine above. For both the regionwidth and the customcss we make sure it has a value and then store it in a variable. We then call the relevant function to make the changes for that setting.

Now that we have the general processing function it is time to write the three functions we have used but not written, ''demystified_set_backgroundcolor'', ''demystified_set_regionwidth'', ''demystified_set_customcss''.

====The function: demystified_set_backgroundcolor====

First up demystified_set_backgroundcolor.

<code php>
/**
* Sets the background colour variable in CSS
*
* @param string $css
* @param mixed $backgroundcolor
* @return string
*/
function demystified_set_backgroundcolor($css, $backgroundcolor) {
$tag = '[[setting:backgroundcolor]]';
$replacement = $backgroundcolor;
if (is_null($replacement)) {
$replacement = '#DDDDDD';
}
$css = str_replace($tag, $replacement, $css);
return $css;
}
</code>

Ok so what is happening here?

First we need a variable '''$tag''' that contains the tag we are going to replace. As mentioned earlier we are going to use tags that look like the image tags you are already familiar with ''<nowiki>[[setting:settingname]]</nowiki>'', in this case ''<nowiki>[[setting:backgroundcolor]]</nowiki>''.

Next I am going to create a variable called '''$replacement''' into which I put '''$backgroundcolor'''.

The '''IF''' statement that comes next checks ''$replacement'' to make sure it is not null. If it is then we need to set it to a default value. In this case I have used ''#DDD'' as that was the default for the settings.

The line after the IF statement puts it all together. The ''str_replace'' function that we are calling takes three arguments in this order:
# The text to search for.
# The text to replace it with.
# The text to do the replacement in.
It then returns the text with all of the replacements made. So in this case we are replacing the tag with the background colour and it is returning the changed CSS.

The final thing is to return the ''$css'' variable which now contains the correct background colour.

====The function: demystified_set_regionwidth====

Next we have the demystified_set_regionwidth function.
<code php>
/**
* Sets the region width variable in CSS
*
* @param string $css
* @param mixed $regionwidth
* @return string
*/
function demystified_set_regionwidth($css, $regionwidth) {
$tag = '[[setting:regionwidth]]';
$doubletag = '[[setting:regionwidthdouble]]';
$replacement = $regionwidth;
if (is_null($replacement)) {
$replacement = 200;
}
$css = str_replace($tag, $replacement.'px', $css);
$css = str_replace($doubletag, ($replacement*2).'px', $css);
return $css;
}
</code>

This function is very similar to the above function however there is one key thing we are doing different. We are doing two replacements.

# The first replacement is for the width that the user selected. In this case I am replacing the tag ''<nowiki>[[setting:regionwidth]]</nowiki>'' with the width.
# The second replacement is for the width x 2. This is because the page layout requires that the width be doubled for some of the CSS. Here I will replace ''<nowiki>[[setting:regionwidthdouble]]</nowiki>'' with the doubled width.

Remember because it is still just a number we need to add '''px''' to the end of each before we do the replacement.

So the overall process of this function is:
# Define the two tags as '''$tag''' and '''$doubletag'''.
# Make '''$replacement''' the region width ''$regionwidth''.
# Set ''$replacement'' to a default value of 200 is it is null.
# Replace '''<nowiki>[[setting:regionwidth]]</nowiki>''' with the width.
# Replace '''<nowiki>[[setting:regionwidthdouble]]</nowiki>''' with the width x 2.
# Return the changed CSS.

====The function: demystified_set_customcss====

The final function that we need to write is the demystified_set_customcss function.
<code php>
/**
* Sets the custom css variable in CSS
*
* @param string $css
* @param mixed $customcss
* @return string
*/
function demystified_set_customcss($css, $customcss) {
$tag = '[[setting:customcss]]';
$replacement = $customcss;
if (is_null($replacement)) {
$replacement = '';
}
$css = str_replace($tag, $replacement, $css);
return $css;
}
</code>

This function is just like the first function. I'm going to let you work it out on your own.

And that is it no more PHP... Hallelujah I can hear you yelling. The final thing we need to do is tell our theme about the functions we have written and put the settings tags into the CSS.

===Finishing it all off===

So there are two things we have to do in order to complete this section and have our the settings page implemented and our settings being used.

First we need to tell our theme that we want to use the function ''demystified_process_css'' as the ''csspostprocess'' function. This is done very simply by adding the following line of PHP to the bottom of our theme's config.php file '''theme/demystified/config.php'''.

<code php>
$THEME->csspostprocess = 'demystified_process_css';
</code>

With that done the only thing left is to add the settings tag into the CSS. Remember those settings tags are:

; <nowiki>[[setting:backgroundcolor]]</nowiki> : We need to add this where ever we want the background colour setting to be used.
; <nowiki>[[setting:regionwidth]]</nowiki> : We need to add this where ever we want to set the width of the block regions.
; <nowiki>[[setting:regionwidthdouble]]</nowiki> : We need to add this where ever we want to set the doubled width of the block regions.
; <nowiki>[[setting:customcss]]</nowiki> : We need to add this to the bottom of the CSS file that we want the custom CSS added to.

So lets make those changes in CSS now, open up your ''core.css'' file and replace the CSS with the CSS below:
<code css>
/** Background color is a setting **/
html {background-color:[[setting:backgroundcolor]];}
body {margin:30px;padding:0;border:1px solid #333;border-width:0 10px 0 10px;background-color:#333;}
body #page {background-color:#FFF;position:relative;top:-10px;}
.block .header {background-image:none;background-color:#0C5CAC;border:1px solid #0C5CAC;color:#FFF;}
.block {border-color:#4BA7FF;background-color:#DDEEFF;}
.block .content {background-color:#F1F8FF;}
a:link,
a:visited {color:#0C5CAC;}
a:hover {color:#C77500;}
#page #page-header {background-color:#0C5CAC;margin:0;padding:0;width:100%;color:#fff;}
#page #page-header a:link, #page #page-header a:visited {color:#FFAC02}
#page #page-header .navbar, #page #page-header .navbar a:link, #page #page-header .navbar a:visited {color:#0C5CAC;}
/** Override the region width **/
#page-content #region-main-box {left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidthdouble]];}
#page-content #region-main-box #region-post-box #region-pre {width:[[setting:regionwidth]];left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-post {width:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidthdouble]];}
.side-pre-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-pre-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
/** Custom CSS **/
[[setting:customcss]]
</code>

You will notice that <nowiki>[[setting:backgroundcolor]]</nowiki> has been used for the html tags background colour:
<code css>
html {background-color:[[setting:backgroundcolor]];}
</code>

We have also set the width of the block regions by adding <nowiki>[[setting:regionwidth]]</nowiki> as the width for region-pre and region-post as shown below:
<code css>
#page-content #region-main-box {left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidthdouble]];}
#page-content #region-main-box #region-post-box #region-pre {width:[[setting:regionwidth]];left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-post {width:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidthdouble]];}
.side-pre-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-pre-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
</code>
You'll notice here that we have to set several different widths and margins using the regionwidth setting and make use of the special regionwidthdouble setting that we added.

The final thing that we did was add the <nowiki>[[setting:customcss]]</nowiki> to the bottom of the file to ensure that the custom CSS comes last (and therefore can override all other CSS).

And with that we are finished. The screenshot below shows how this now looks in the browser if I set the background colour setting to '''<span style='color:#FFA800;'>#FFA800</span>''' and made the column width 240px;

[[Image:Theme.settings.page.04.png|715px|thumb|left|Our settings in action]]<br style="clear:both;" />

==Using the settings within our layout files==
Now that we have utilised the first three settings within our theme's CSS file it is time to implement the other two settings within the layout files so that they are written directly into the page.

You'll be glad to know this is no where near as difficult as utilising settings within a CSS file although it still does require a little bit of PHP.

First up is the logo setting. Into this setting the user is able to enter the URL to an image to use as the logo for the site. In my case I want this to be just a background logo on top of which I want to position the page header.

Before I start there is one thing I need to do however and that is create a default logo background that gets shown if the user hasn't set a specific logo file. To do this I simply created an image '''logo.jpg''' and put it into a pix directory within the demystified theme. You should end up with '''theme/demystified/pix/logo.jpg'''.

Next open up the front-page layout file ''theme/demystified/layout/frontpage.php''. At the top of the file is the PHP that checks what blocks regions the page has and a bit of other stuff. Well right below the existing bit of PHP we want to add the following code:
<code php>
if (!empty($PAGE->theme->settings->logo)) {
$logourl = $PAGE->theme->settings->logo;
} else {
$logourl = $OUTPUT->pix_url('logo', 'theme');
}
</code>
What we are doing here is creating a variable called $logourl that will contain the URL to a logo file that was either entered by the user or if they left it blank is that of our default logo file.

There are two things that you should notice about this. First the logo setting can be retrieved through '''$PAGE->theme->settings->logo''' and second we get the default logo url by calling '''$OUTPUT->pix_url('logo', 'theme')'''.

Now that we have the logo URL we are going to use we need to add an image to the header section of the page as shown below:
<code php>
<div id="page-header" class="clearfix">
<img class="sitelogo" src="<?php echo $logourl;?>" alt="Custom logo here" />
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
....
</code>

If you save that and browse to your sites front page you will notice that the logo file is now being shown. Hooray. However it is probably not styled too nicely so lets quickly fix that. Open up the core.css file and add the following lines of CSS to the bottom of the file.
<code css>
#page-header {position:relative;min-height:100px;}
#page-header .sitelogo {float:left;}
#page-header .headermain {position:absolute;left:0.5em;top:50px;margin:0;float:none;font-size:40px;}
</code>
These three lines position the image correctly and if you now refresh everything should appear perfectly.

With the logo done the last setting we need to deal with is the footnote setting. The idea with this setting was that the administrator could enter some text into the editor and it would be displayed in the footer of the page.

This is probably the easiest setting to implement.

Within the front page layout file that we edited above add the following lines below those we added previously.

<code php>
if (!empty($PAGE->theme->settings->footnote)) {
$footnote = $PAGE->theme->settings->footnote;
} else {
$footnote = '';
}
</code>

Here we are just collecting the footnote into a variable '''$footnote''' and setting a default footnote comment if the user hasn't entered one.

We can now echo the $footnote variable within the page footer. This can be done as shown below.

<code php>

<div id="page-footer">
<div class="footnote"><?php echo $footnote; ?></div>
<p class="helplink">
<?php echo page_doc_link(get_string('moodledocslink')) ?>
</p>
</code>

And with that done we are finished! Congratulations if you got this far.

The screenshot below shows the demystified theme we have just created that is styled by the settings page.

[[Image:Theme.settings.page.05.png|715px|thumb|left|My finished demystified theme]]<br style="clear:both" />

==Testing our creation==
Congratulations to you! If you've made it this far you have done very well. Now it is time to have a look at what we have created and give it a quick test run.

So in this tutorial we have achieved the following:

* We created a theme called demystified that is based on the standard theme.
* We added a settings page to our new theme.
* We added the following settings to our settings page:
** We can set a background colour through the admin interface.
** We can change the logo of the site.
** We can change the block region width.
** We can add a footnote to the page footer
** We can add some custom CSS to seal the deal.
* Those settings were then used in the CSS files for our theme.
* They were also used in the layout files for our theme.
* And here we are testing it all.

The screenshots below show my testing process and I change each setting and view the outcome. The great thing about this is that with theme designer mode on you see the changes as soon as the form refreshes.

[[Image:Theme.settings.page.06.png|300px|thumb|left|Default settings]]
[[Image:Theme.settings.page.07.png|300px|thumb|left|Changed the background colour setting]]
[[Image:Theme.settings.page.08.png|300px|thumb|left|Changed the logo and region width]]
[[Image:Theme.settings.page.09.png|300px|thumb|left|Added a footnote]]
[[Image:Theme.settings.page.10.png|300px|thumb|left|Added some custom CSS]]
<br style="clear:both" />

==The different settings you can use==
During this tutorial we use four different kinds of settings, a text box, text area, a select (dropdown) and the editor however as I'm sure you have all guessed there is many more some of which will certainly be useful for theme settings.

The following are examples of some of the different settings. I should add that these build upon what we have already done within the tutorial but are not included in the download.

===Colour picker===
[[Image:Theme.settings.page.11.png|400px|thumb|The colour picker]]
I can hear you all asking now 'Why didn't you mention this one earlier?' well the answer is simple it didn't exist when I first wrote the tutorial. It is an admin setting that I wrote several days after because of the fantastic effort people were putting into trying out settings pages.

A bit about the colour picker. First up it is a text box that when the page loads turns into a colour picker that can be used to select a colour and can even preview the selected colour in the page (by clicking the preview button). It is designed to be very easy to use and the code is just about as simple as creating a normal text box setting.

In the image to the left I have replaced the background colour setting we created during the tutorial with the colour picker. Lets have a look at the code involved for that.
<code php>
// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$previewconfig = array('selector'=>'html', 'style'=>'backgroundColor');
$setting = new admin_setting_configcolourpicker($name, $title, $description, $default, $previewconfig);
$temp->add($setting);
</code>
So first thing you should notice is that the first four lines of code have not changed at all!

The first change we have is to create a variable '''$previewconfig'''.
This variable is used to tell the colour picker what to do when the user clicks the preview button. It should be an array that contains two things, first a selector, and second a style.
# The selector is a CSS selector like ''.page .header h2''.
# The style is a what should change, there are two immediate values it can be, either '''backgroundColor''' or '''color'''.
In my case the selector is '''html''' to target the html tag and the style is backgroundColor to change the background colour.

The second change is to use '''admin_setting_configcolourpicker''' instead of ''admin_setting_configtext''. The arguments are nearly identical as well except that there is an extra argument to which we give the '''$previewconfig''' variable.

And that is it! it is all you need to get the colour picker up and running.

'''Extra note:''' The $previewconfig variable is optional. If you don't want a preview button the simply set ''$previewconfig = null''

==Common pitfalls and useful notes==

This section is really just a collection of pointers, tips, notes, and other short useful stuff that may be of use to those attempting this tutorial.

# First up and most importantly there are very few limitations to what you achieve in this fashion.
# If you get stuck or need a hand ask in the forums, there's always someone round who can help.
# If you do something really cool let us know, I know everyone in the community loves finding our what others are achieving.
# You don't have to use ''admin_settingpage'' you can also use '''admin_externalpage''' if you prefer. It should be noted however that it is not the preferred way to do it as admin_externalpage's were only left in Moodle 2.0 for backwards compatibility (although they are more flexible one day they will be deprecated or removed). Thank you to Darryl for raising this.
# If you find that your language strings aren't being used (you are getting language string notices) and you have double checked that you have turned '''langstringcache''' off then you may need to delete the language cache directory. This is located in the moodledata directory for you installation: moodledata/cache/lang/*. You should delete the directory for your chosen language by default ''en''.

==See also==

* [[Adding theme upgrade code]]
* [[Styling and customising the dock]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=152053 Theme 2.0: Adding a settings page to your theme] forum discussion

Creating a theme settings page

2014-09-24T21:59:49Z

Tqr: /* Custom CSS */ - updating

{{Template:Themes}}This document looks at how to create a settings page for your Moodle 2.x.x theme and how to make use of those settings within the CSS and layout files for your theme.

This is a pretty advanced topic and will require that you have at least an intermediate knowledge of PHP, CSS, and development in general.

==Before we begin==
[[Image:Theme.settings.page.03.png|350px|thumb|Our end goal. The settings page.]]
[[Image:Theme.settings.page.10.png|350px|thumb|And what it can do.]]
There is a huge body of knowledge that we must cover in following through this document and as such I think the best way to write this is as a tutorial.

My intentions for this tutorial are to replicate the standard theme but with a settings page that allows the administrator to set a background colour, set a logo to use with the page, and probably several other minor settings to change the way in which the theme is displayed.

I will start this tutorial by creating a new theme which will be largely a copy/paste of the current standard theme. I expect that anyone working through this tutorial has previously read the tutorial I wrote on [[Themes 2.0 creating your first theme|creating your first theme]]. If you haven't go read it now because I'm not going to go into much detail until we get to the actual process of customising the theme and introducing the settings page.

So before we finally get this started please ensure you can check off everything on the following requirements list.
* Have a Moodle installation that has already been installed and configured and is ready to use.
* Have full read/write access to that installation.
* Be prepared to delete that installation at the end of this... we will destroy it!
* Have a development environment prepared and ready to use. This includes:
** Your favourite editor installed, running, and pointed at the themes directory of your installation.
** Your browser open and your site visible.
** A bottomless coffee pot... decaf won't help you with this one.
* Have set the following settings:
** '''themedesignermode''' if you don't know what this is please read the [[Themes 2.0 creating your first theme|creating your first theme]] tutorial.
** '''allowthemechangeonurl''' turn this on, it allows you to change themes on the URL and is very handy when developing themes. ''Site Administration > Appearance > Themes > Theme settings''
** '''langstringcache''' if you don't turn this off you won't see your strings when they are added. ''Site Administration > Language > Language settings''
* And finally an insane ambition to create a customisable theme.

For those interested the theme that I create throughout this tutorial can be downloaded from the forum post in which I announce this document: http://moodle.org/mod/forum/discuss.php?d=152053
<br style="clear:right;" />

==Our goals for this tutorial==
The following is just a list goals that I hope to achieve during this tutorial. They are laid out here so that I can easily refer back to them and so that you can easily find them.
# Create a new theme called '''demystified''' based upon the standard theme within Moodle 2.0.
# Make some minor changes to that theme to allow us to more easily see what is going on.
# Create a settings page for the demystified theme.
# Add several settings to our settings page.
# Use some of those settings to alter our CSS.
# Use the rest of those settings within our layout file..
# Discuss the good, the bad, and limits of what we have just created.

So I can see you are all very excited about this point and that you would love to know what settings we are going to create; So here they are:

A setting to ...
* change the background colour (CSS).
* set the path to an image that we will use as a logo on all pages (Layout files).
* override the width of the block regions (CSS).
* allow a note to be added to the footer of all pages (Layout files).
* allow custom CSS to be written to do anything the user wants. (CSS)

==Creating the demystified theme==
Before we start here I want to remind you that I am going to look at this only briefly as I am making the assumption that you have read the [[Themes 2.0 creating your first theme|creating your first theme]] tutorial.

Well lets get into it....

The first thing we need to do is create a directory for our theme which we will call demystified.

So within your Moodle directory create the following folder '''moodle/theme/demystified'''. At the same time you can also create the following files and folders which we will get to soon.
* The file '''moodle/theme/demystified/config.php''' for our config information.
* The directory '''moodle/theme/demystified/layout''' for our layout files.
* The directory '''moodle/theme/demystified/style''' for our css files.
* The file '''moodle/theme/demystified/style/core.css''' which will contain our special CSS.

Next we will copy the layout files from the base theme to our new theme demystified. We are basing the demystified theme on the standard theme however that doesn't use it's own layout files it uses the base theme's layout files so those are the ones we want.

The reason that we are coping these layout files is that later on in this tutorial we will be modifying them to make use of our new settings... so copy all of the layout files from '''moodle/theme/base/layout''' to '''moodle/theme/demystified/layout'''.

There should be three files that you just copied:
# embedded.php
# frontpage.php
# general.php

Now we need to populate demystified/config.php with the settings for our new theme. They are as follows:
<code php>
$THEME->name = 'demystified';
</code>
Simply sets the name of our theme.

<code php>
$THEME->parents = array('standard','base');
</code>
This theme is extending both the standard theme and the base theme. Remember when extending a theme you also need to extend its parents or things might not work correctly.

<code php>
$THEME->sheets = array('core');
</code>
This tells our theme that we want to use the file '''demystified/style/core.css''' with this theme.

<div style="height:300px;overflow-y:scroll;">
<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-post',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'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),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>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),
),
// 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),
),
);
</code>
</div>
Now that all looks very complicated however its really not too bad as it is just copied from the base theme's config.php file. We can do this because we copied the layout files from the base theme to begin with and for the time being there are no changes that we wish to make. Simply open up '''theme/base/config.php''' and copy the layouts from there.

And that is it. The config.php file for our demystified theme is complete. The full source is shown below:
<div style="height:300px;overflow-y:scroll;">
<code php>
<?php

// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* The demystified theme config file
*
* This theme was created to document the process of adding a settings page to a theme
*
* @copyright 2010 Sam Hemelryk
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

// The name of our theme
$THEME->name = 'demystified';

// The other themes this theme extends
$THEME->parents = array('standard','base');

// The CSS files this theme uses (located in the style directory)
$THEME->sheets = array('core');

// The layout definitions for this theme
$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-post',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'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),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>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),
),
// 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),
),
);
</code>
</div>

The screenshot below shows both the directory structure we have now created and the theme presently.

[[Image:Theme.settings.page.01.png]]

To view the theme so far open you browser and enter the URL of your site followed by '''?theme=demystified'''. You should see the theme that we just created which will look exactly like the base standard theme.

The final thing that we want to do is add a little bit of CSS to the demystified theme that will both visually set this theme apart from the standard theme and second build a the base which our settings can later extend.

I added the following snippet of CSS to the file '''demystified/style/core.css'''.
<code css>
html {background-color:#DDD;}
body {margin:30px;padding:0;border:1px solid #333;border-width:0 10px 0 10px;background-color:#333;}
body #page {background-color:#FFF;position:relative;top:-10px;}
.block .header {background-image:none;background-color:#0C5CAC;border:1px solid #0C5CAC;color:#FFF;}
.block {border-color:#4BA7FF;background-color:#DDEEFF;}
.block .content {background-color:#F1F8FF;}
a:link,
a:visited {color:#0C5CAC;}
a:hover {color:#C77500;}
#page #page-header {background-color:#0C5CAC;margin:0;padding:0;width:100%;color:#fff;}
#page #page-header a:link, #page #page-header a:visited {color:#FFAC02}
#page #page-header .navbar, #page #page-header .navbar a:link, #page #page-header .navbar a:visited {color:#0C5CAC;}
</code>

The CSS that we have just added to our theme sets a couple of colours on the front page. Presently this is the only CSS I will add, I know it isn't complete by any means but it achieves it's purpose as the screenshot below illustrates.

[[Image:Theme.settings.page.02.png|715px|thumb|left|The newly styles demystified theme]]<br style="clear:both;" />

And with that I will move on to the real purpose of this tutorial, creating the settings page

==Setting up the settings page==
With the demystified theme set up it is time to create the settings page. This is where the real PHP fun begins.

For those of you who happen to be familiar with development of modules, blocks or other plugin types you have probably encountered settings pages before and this is not going to be any different.

However for those who haven't which I imagine is most of you this is going to be quite a challenge. I will try to walk through this step by step however if at any point you get stuck don't hesitate to ask in the forums as I imagine you will get a speedy response.

===How settings pages work in Moodle===
Settings pages can be used by nearly every plugin type, of which themes is of course one. The way in which it all works isn't too tricky to understand.

All of the settings for Moodle can be configured through the administrator interfaces when logged in. I am sure that everyone here has seen those pages and has changed a setting or two before so you will all know what I am talking about. Well the settings page for a theme is no different. It will be shown in the administration pages tree under '''Appearance > Themes''' and all we have to do is tell Moodle what settings there are.

This is done by creating a settings.php file within our theme into which we will add code that tells Moodle about the settings we want to add/use.

When telling Moodle about each setting we are simply creating a new ''admin_setting'' instance of the type we want and the properties we want and then adding it to our settings page.

There is really not much more too it at this level. Things can get very complex very fast so the best thing we can do now is start creating our settings.php file for the demystified theme and see where it leads us.

===Creating the settings page===
So as mentioned before we need a settings.php file which we will create now. To begin with create the file '''theme/demystified/settings.php''' and open it in your favourite editor so its ready to go.

Before we start adding code however lets just remember the settings that we want to create:
* change the background colour (CSS).
* set the path to an image that we will use as a logo on all pages (Layout files).
* override the width of the block regions (CSS).
* allow a note to be added to the footer of all pages (Layout files).
* allow custom CSS to be written to do anything the user wants. (CSS)

Alright.

Now thinking about this the first setting is as basic as it gets, all we need is a text box that the user can type a colour into.

The second is to allow a logo to be used in the header of each page. What we want here is a path but should it be a physical path e.g. C:/path/to/image.png or should it be a web path e.g. <nowiki>http://mysite.com/path/to/image.png</nowiki>?
For the purpose of this tutorial I am going to go with a web path because it is going to be easier to code and will hopefully be a little easier to understand to begin with.

The third setting is a little more complex. For this I want a drop down box with some specific widths that the administrator can select.

The forth and the fifth settings are both pretty straight forward, there we want a textarea into which the user can enter what ever they want and we will do something useful with it.

Now that we have an understanding about the settings we wish to define pull up your editor and lets start coding....

<code php>
<?php

/**
* Settings for the demystified theme
*/
defined('MOODLE_INTERNAL') || die;

if ($ADMIN->fulltree) {
</code>
This is the first bit of code we must enter, the first line is of course just the opening php tag, secondly we have a comment that describes this file, and then we get create a new '''admin_settingspage object'''.

This admin_settingspage object that we have just created is a representation of our settings page and is the what we add our new settings to. When creating it we give it two arguments, first the name of the page which is in this case '''theme_''themename''''' and the title for the page which we get with the get_string method.

At the moment I'm not going to worry about adding the string, we will get to that later once we have defined all of our settings.

====Background colour====

With the page now created lets add our first setting: Background colour.

<code php>
// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$setting = new admin_setting_configtext($name, $title, $description, $default, PARAM_CLEAN, 12);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
Thankfully this isn't as difficult as it initially looks.

The first line of code is creating a variable for the name of the background colour setting. In this case it is '''theme_demystified/backgroundcolor'''.

The name is very important, for the setting to be usable we have to follow a strict naming convention. '''theme_''themename''/''settingname''''' where '''''themename''''' is the name of the theme the setting belongs to and '''''settingname''''' is the name for the setting by which we will use it.

The second line of code creates a variable that contains the title of the setting. This is what the user sees to the right of the setting on the settings page and should be a short description of the setting. Here we are again using the ''get_string'' method so we will need to remember to add that string later on.

The third line of code sets the description. This should describe what the setting does or how it works and again we will use the get_string method.

The fourth line creates a variable that will be used as the default value for the setting. Because this setting is a colour we want an HTML colour to be the default value.

The fifth line is where we put it all together. Here we create a new '''admin_setting_configtext''' object. This object will represent the background colour setting.

When we create it we need to give it 6 different things.
# The name of the setting. In this case we have a variable '''$name'''.
# The title for this setting. We used the variable '''$title'''.
# The description of the setting '''$description'''.
# The default value for the setting. '''$default''' is the variable this.
# The type of value we want the user to enter. For this we have used PARAM_CLEAN which tells Moodle to get rid of any nasties from what the user enters.
# The size of the field. In our case 12 characters will be plenty.

The sixth and final line of code adds our newly created setting to the administration page we created earlier.

That is it we have successfully created and added our first setting, however there are several more to settings to do, and there are a couple of important things that you need to be aware of before we move on.

First: There are several different types of settings that you can create and add to a page, and each one may differ in what they need you to give them. In this case it was name, title, description, default, type, and size. However other settings will likely require different things. Smart editors like Netbeans or Eclipse can tell you what is required, otherwise you will need to research it.

Second: Normally settings are declared on one line as follows:
<code php>
$setting->add(new admin_setting_configtext('theme_demystified/backgroundcolor', get_string('backgroundcolor','theme_demystified'), get_string('backgroundcolordesc', 'theme_demystified'), '#DDD', PARAM_CLEAN, 12));
</code>
While this is structurally identical as all we have done is move everything onto one line and do away with the variables it is a little harder to read when you are learning all of this.

====The logo file====
Time to create the second setting that will allow the user to enter a URL to an image they wish to use as the logo on their site.
<code php>
// Logo file setting
$name = 'theme_demystified/logo';
$title = get_string('logo','theme_demystified');
$description = get_string('logodesc', 'theme_demystified');
$setting = new admin_setting_configtext($name, $title, $description, '', PARAM_URL);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
The first thing that you will notice about this setting that it is very similar to the first setting, in fact all we have changed is the name, title, description, and default value. We have however changed the value type from PARAM_CLEAN to PARAM_URL, this makes sure the user enters a URL. You will also notice that for this one we don't set a size for the field as we have no idea how long the URL will be.

====Block region width====
The third setting should allow the user to set a width for the block regions that will be used as columns.

For this setting I want to do something a little different from the previous two, here I want to use a select box so that the user selects a width for the column from a list I provide.
<code php>
// Block region width
$name = 'theme_demystified/regionwidth';
$title = get_string('regionwidth','theme_demystified');
$description = get_string('regionwidthdesc', 'theme_demystified');
$default = 200;
$choices = array(150=>'150px', 170=>'170px', 200=>'200px', 240=>'240px', 290=>'290px', 350=>'350px', 420=>'420px');
$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
So looking at the code: The first four lines you will recognise. $name, $title, $description, and $default are all being set.

The fifth line of code however introduces something new. Of course in order to have a select box we have to have options, in this case we have an array of options stored in the variable $choices.

The array of options is constructed of a collection of '''''value''' => '''label''''' pairs. Notice how we don't add '''px''' to the value. This is is very intentional as later on I need to do a little bit of math with that value so we need it to be a number.

The lines after should look familiar again, the only difference being that instead of a ''admin_setting_configtext'' setting we have created a ''admin_setting_configselect'' for which we must give the choices for the select box as the fifth argument.

Woohoo, we've just created our first select box setting.

====Foot note====
Now to create the foot note setting. Here we want the user to be able to enter some arbitrary text that will be used in the footer of the page. For this I want the user to be able to enter some HTML so I will create an editor setting.
<code php>
// Foot note setting
$name = 'theme_demystified/footnote';
$title = get_string('footnote','theme_demystified');
$description = get_string('footnotedesc', 'theme_demystified');
$setting = new admin_setting_confightmleditor($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
How simple is that!

It is just about identical to the first two settings except that for this we have created a ''admin_setting_confightmleditor'' setting rather than a text setting.

Note: You can also set the columns and rows for the editor setting using the fifth and sixth arguments.

====Custom CSS====
The final setting is to allow the user to add some custom CSS to the theme that will be used on every page. I want this to be a plain textarea into which the user can enter CSS.
<code php>
// Custom CSS file
$name = 'theme_demystified/customcss';
$title = get_string('customcss','theme_demystified');
$description = get_string('customcssdesc', 'theme_demystified');
$setting = new admin_setting_configtextarea($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
Just like the editor or text settings. It's getting very easy now!

====Finishing settings.php====
With all of our settings defined and added to our page that we created right at the beginning it is time to finish it all off.
<code php>
// Add our page to the structure of the admin tree
$ADMIN->add('themes', $temp);
</code>
The above line of code is the final line for the page. It is adding the page that we have created '''$temp''' to the admin tree structure. In this case it is adding it to the themes branch.

The following is the completed source for our settings.php ..... for your copy/paste pleasure.
<div style='height:300px;overflow:auto;'>
<code php>
<?php

/**
* Settings for the demystified theme
*/

// Create our admin page
$temp = new admin_settingpage('theme_demystified', get_string('configtitle','theme_demystified'));

// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$setting = new admin_setting_configtext($name, $title, $description, $default, PARAM_CLEAN, 12);
$temp->add($setting);

// Logo file setting
$name = 'theme_demystified/logo';
$title = get_string('logo','theme_demystified');
$description = get_string('logodesc', 'theme_demystified');
$setting = new admin_setting_configtext($name, $title, $description, '', PARAM_URL);
$temp->add($setting);

// Block region width
$name = 'theme_demystified/regionwidth';
$title = get_string('regionwidth','theme_demystified');
$description = get_string('regionwidthdesc', 'theme_demystified');
$default = 200;
$choices = array(150=>'150px', 170=>'170px', 200=>'200px', 240=>'240px', 290=>'290px', 350=>'350px', 420=>'420px');
$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$temp->add($setting);

// Foot note setting
$name = 'theme_demystified/footnote';
$title = get_string('footnote','theme_demystified');
$description = get_string('footnotedesc', 'theme_demystified');
$setting = new admin_setting_confightmleditor($name, $title, $description, '');
$temp->add($setting);

// Custom CSS file
$name = 'theme_demystified/customcss';
$title = get_string('customcss','theme_demystified');
$description = get_string('customcssdesc', 'theme_demystified');
$setting = new admin_setting_configtextarea($name, $title, $description, '');
$temp->add($setting);

// Add our page to the structure of the admin tree
$ADMIN->add('themes', $temp);
</code>
</div>

===Creating a language file and adding our strings===
As I'm sure none of you have forgotten, throughout the creation of the our settings.php page, we used a lot of strings that I mentioned we would set later on. Well now is the time to set those strings.

First up create the following directories and file for our language strings:
* Directory '''theme/demystified/lang'''
* Directory '''theme/demystified/lang/en'''
* File '''theme/demystified/lang/theme_demystified.php'''

What we have created here is the required structure for Moodle to start looking for language strings.

First Moodle locates the lang directory, once found it looks within that directory for another directory that uses the character code for the language the user has selected, by default this is '''en''' for English. Once that is found it looks for the appropriate language file, in this case '''theme_demystified.php''' from which it will load all language strings for our theme.

If English isn't your chosen language simply replace the ''en'' directory with one that uses your chosen languages character code (two letters).

We can now add our language strings to '''theme/demystified/lang/theme_demystified.php'''. Copy and paste the following lines of PHP into this file.
<code php>
<?php

/**
* This file contains the strings used by the demystified theme
*/

$string['backgroundcolor'] = 'Background colour';
$string['backgroundcolordesc'] = 'This sets the background colour for the theme.';
$string['configtitle'] = 'Demystified theme';
$string['customcss'] = 'Custom CSS';
$string['customcssdesc'] = 'Any CSS you enter here will be added to every page allowing your to easily customise this theme.';
$string['footnote'] = 'Footnote';
$string['footnotedesc'] = 'The content from this textarea will be displayed in the footer of every page.';
$string['logo'] = 'Logo';
$string['logodesc'] = 'Enter the URL to an image to use as the logo for this site. Should be http://www.yoursite.com/path/to/logo.png';
$string['pluginname'] = 'Demystified';
$string['regionwidth'] = 'Column width';
$string['regionwidthdesc'] = 'This sets the width of the two block regions that form the left and right columns.';
</code>

In the above lines of code I have added an entry for each language string we used within ''settings.php''. When adding language strings like this make sure you use single quotes and try to keep things alphabetical - it helps greatly when managing strings.

Now when we view the settings page there will not be any errors or strings missing.

===Having a look at what we have created===
Now that we have created our settings page (settings.php) and added all of the language strings it is time to have a look at things in your browser.

Open your browser and enter the URL to your site. When you arrive at your site login as an administrator.

If you are not redirected to view the new settings change your URL to <nowiki>http://www.yoursite.com/admin/</nowiki> and your will see a screen to set the new theme settings we have just created. This lets us know that everything has worked correctly.

At any point now you are able to log in as administrator and within the settings block browse to '''Site administration > Appearance > Themes > Demystified theme''' to change those settings.

The screenshot below shows you what you should see at this point:

[[Image:Theme.settings.page.03.png|715px|thumb|left|The settings page we just created]]
<br style="clear:both;" />

==Using the settings in CSS==
With the settings page now created and operational it is time to make use of our new settings. The settings that we want to use within our CSS is as follows:

; backgroundcolor : Will be used to set the background colour in CSS.
; regionwidth : Will be the width of the column for CSS.
; customcss : Will be some custom CSS to add to our stylesheet.

At this point those names are the names we used for our setting with the slash and everything before it having been removed.

Before we start tearing into some code it is important that we have a look at what we are going to do and how we are going to go about it.

===How it all works within Moodle===
The first thing to understand is that while Moodle allows you to create a settings page and automates it inclusion and management right into the administration interfaces there is no smart equivalent for using the settings. This is simply because there is no way to predict how people will want to use the settings.

However don't think of this as a disadvantage, in fact it is quite the contrary. Although we can't just ''use'' our settings we can take full control over how and where we use them. It means it will take a little more code but in the end that will work to our advantage as we can do anything we want.

Moodle does help us out a little but not in an obvious way. The first thing that Moodle does is look for a config variable '''csspostprocess''' that should be the name of a function which we want called to make any changes to the CSS after it has been prepared.

The second thing Moodle does is include a lib.php from the theme's directory if one exists (also for the themes the current theme extends.) which ensures that as long as we write our code within '''theme/demystified/lib.php''' it will be included and ready to be used.

The third and final thing Moodle does that will help us out here is ensure that by the time any of code is ready to execute the settings have been prepared and are ready to be used within a theme config object which is passed into our ''csspostprocess'' function.

===Our plan===
As you have already probably guessed we will need to create a function to make the changes to the CSS that we want. We will then set the theme config option '''$THEME->csspostprocess''' to the name of our function.

By doing this when Moodle builds the CSS file it will call our function afterwards with the CSS and the theme object that contains our setting.

Now we know that we will use the ''csspostprocess'' function but how are we going to change the CSS, we could get the function to add CSS, or we could get the function to replace something within the CSS. My personal preference is to replace something within the CSS, just like what is happening with images. If you want to use an image within CSS you would write <nowiki>[[pix:theme|imagename]]</nowiki>.

For settings I am going to use <nowiki>[[setting:settingname]]</nowiki>, this way it looks a bit like something you are already familiar with.

What we need to decide upon next is the best way in which to replace our settings tag with the settings that the user has set.

There are two immediate options available to us:
# Make the ''csspostprocess'' function do all the work.
# Make the ''csspostprocess'' function call a separate function for each setting.
Solution 1 might sound like the simplest however it is going to result in a '''VERY''' complex function. Remember the user might have left settings blank or entered something that wouldn't be valid so we would need to make the sure there is some validation and a good default.
Because of this I think that solution 2 is the better solution.

So we are going to need a ''csspostprocess'' function and then a function for each of the three settings we have that will do the replacements.
<code php>
// This is our css post process function
function demystified_process_css($css, $theme) {};
// This replaces [[setting:backgroundcolor]] with the background colour
function demystified_set_backgroundcolor($css, $backgroundcolor) {};
// This replaces [[setting:regionwidth]] with the correct region width
function demystified_set_regionwidth() {$css, $regionwidth};
// This replaces [[setting:customcss]] with the custom css
function demystified_set_customcss() {$css, $customcss};
</code>

What you should note about the above functions is that they all start with the theme's name. This is required to ensure that the functions are named uniquely as it is VERY unlikely that someone has already created these functions.

So with our plan set out lets start writing the code.

===Writing the code===
The very first thing that we need to do is create a lib.php for our theme into which our css processing functions are going to go. So please at this point create '''theme/demystified/lib.php''' and open it in your editor ready to go.

The first bit of code we have to write is the function that will be called by Moodle to do the processing '''demystified_process_css'''.

Before we start out please remember that the wonderful thing about coding is that there is any number of solutions to a problem. The solutions that you are seeing here in this tutorial are solutions that I have come up with to meet fulfil the needs of the tutorial without being so complex that they are hard to understand. This probably isn't how I would go about it normally but this is a little easier to understand for those who aren't overly familiar with PHP and object orientation.

====The function: demystified_process_css====

<code php>
function demystified_process_css($css, $theme) {

if (!empty($theme->settings->backgroundcolor)) {
$backgroundcolor = $theme->settings->backgroundcolor;
} else {
$backgroundcolor = null;
}
$css = demystified_set_backgroundcolor($css, $backgroundcolor);

if (!empty($theme->settings->regionwidth)) {
$regionwidth = $theme->settings->regionwidth;
} else {
$regionwidth = null;
}
$css = demystified_set_regionwidth($css, $regionwidth);

if (!empty($theme->settings->customcss)) {
$customcss = $theme->settings->customcss;
} else {
$customcss = null;
}
$css = demystified_set_customcss($css, $customcss);

return $css;
}
</code>

So lets look at the things that make up this function:

<code php>
function demystified_process_css($css, $theme) {
//.....
return $css
}
</code>

This of course is the function declaration.

The function gets given two variables, the first '''$css''' is a pile of CSS as one big string, and the second is the theme object '''$theme''' that contains all of the configuration, options, and settings for our theme.

It then returns the ''$css'' variable, essentially returning the modified CSS.

<code php>
//...
if (!empty($theme->settings->backgroundcolor)) {
$backgroundcolor = $theme->settings->backgroundcolor;
} else {
$backgroundcolor = null;
}
$css = demystified_set_backgroundcolor($css, $backgroundcolor);
//...
</code>

Here we are processing our first setting ''backgroundcolor''.

The first thing that we need to do is check whether it has been set and whether it has a value. If it has then we store that value in '''$backgroundcolor'''. It is doesn't have a value then we set ''$backgroundcolor'' to null. This ensures that ''$backgroundcolor'' is set because if it isn't then you are going to get a notice (if you have debugging on).

The final line of this block calls the function '''demystified_set_backgroundcolor'''. We haven't written this function yet but we will shortly. When we call it we give it the ''$css'' variable that contains all of the CSS and we give it the background colour variable ''$backgroundcolor''. Once this function is finished it returns the ''$css'' variable with all of the changes made much like how our css processing function works.

What you should also note about this code is this:
<code php>
$theme->settings->backgroundcolor
</code>
As mentioned earlier ''$theme'' is an object that contains all of the configuration and settings for our theme. The ''$theme'' object has a $settings property which contains all of the settings for our theme, and finally the settings property contains a variable backgroundcolor that is the value the user entered for that setting. That is how we get a settings value.

<code php>
if (!empty($theme->settings->regionwidth)) {
$regionwidth = $theme->settings->regionwidth;
} else {
$regionwidth = null;
}
$css = demystified_set_regionwidth($css, $regionwidth);

if (!empty($theme->settings->customcss)) {
$customcss = $theme->settings->customcss;
} else {
$customcss = null;
}
$css = demystified_set_customcss($css, $customcss);
</code>

These two routines are nearly identical to the routine above. For both the regionwidth and the customcss we make sure it has a value and then store it in a variable. We then call the relevant function to make the changes for that setting.

Now that we have the general processing function it is time to write the three functions we have used but not written, ''demystified_set_backgroundcolor'', ''demystified_set_regionwidth'', ''demystified_set_customcss''.

====The function: demystified_set_backgroundcolor====

First up demystified_set_backgroundcolor.

<code php>
/**
* Sets the background colour variable in CSS
*
* @param string $css
* @param mixed $backgroundcolor
* @return string
*/
function demystified_set_backgroundcolor($css, $backgroundcolor) {
$tag = '[[setting:backgroundcolor]]';
$replacement = $backgroundcolor;
if (is_null($replacement)) {
$replacement = '#DDDDDD';
}
$css = str_replace($tag, $replacement, $css);
return $css;
}
</code>

Ok so what is happening here?

First we need a variable '''$tag''' that contains the tag we are going to replace. As mentioned earlier we are going to use tags that look like the image tags you are already familiar with ''<nowiki>[[setting:settingname]]</nowiki>'', in this case ''<nowiki>[[setting:backgroundcolor]]</nowiki>''.

Next I am going to create a variable called '''$replacement''' into which I put '''$backgroundcolor'''.

The '''IF''' statement that comes next checks ''$replacement'' to make sure it is not null. If it is then we need to set it to a default value. In this case I have used ''#DDD'' as that was the default for the settings.

The line after the IF statement puts it all together. The ''str_replace'' function that we are calling takes three arguments in this order:
# The text to search for.
# The text to replace it with.
# The text to do the replacement in.
It then returns the text with all of the replacements made. So in this case we are replacing the tag with the background colour and it is returning the changed CSS.

The final thing is to return the ''$css'' variable which now contains the correct background colour.

====The function: demystified_set_regionwidth====

Next we have the demystified_set_regionwidth function.
<code php>
/**
* Sets the region width variable in CSS
*
* @param string $css
* @param mixed $regionwidth
* @return string
*/
function demystified_set_regionwidth($css, $regionwidth) {
$tag = '[[setting:regionwidth]]';
$doubletag = '[[setting:regionwidthdouble]]';
$replacement = $regionwidth;
if (is_null($replacement)) {
$replacement = 200;
}
$css = str_replace($tag, $replacement.'px', $css);
$css = str_replace($doubletag, ($replacement*2).'px', $css);
return $css;
}
</code>

This function is very similar to the above function however there is one key thing we are doing different. We are doing two replacements.

# The first replacement is for the width that the user selected. In this case I am replacing the tag ''<nowiki>[[setting:regionwidth]]</nowiki>'' with the width.
# The second replacement is for the width x 2. This is because the page layout requires that the width be doubled for some of the CSS. Here I will replace ''<nowiki>[[setting:regionwidthdouble]]</nowiki>'' with the doubled width.

Remember because it is still just a number we need to add '''px''' to the end of each before we do the replacement.

So the overall process of this function is:
# Define the two tags as '''$tag''' and '''$doubletag'''.
# Make '''$replacement''' the region width ''$regionwidth''.
# Set ''$replacement'' to a default value of 200 is it is null.
# Replace '''<nowiki>[[setting:regionwidth]]</nowiki>''' with the width.
# Replace '''<nowiki>[[setting:regionwidthdouble]]</nowiki>''' with the width x 2.
# Return the changed CSS.

====The function: demystified_set_customcss====

The final function that we need to write is the demystified_set_customcss function.
<code php>
/**
* Sets the custom css variable in CSS
*
* @param string $css
* @param mixed $customcss
* @return string
*/
function demystified_set_customcss($css, $customcss) {
$tag = '[[setting:customcss]]';
$replacement = $customcss;
if (is_null($replacement)) {
$replacement = '';
}
$css = str_replace($tag, $replacement, $css);
return $css;
}
</code>

This function is just like the first function. I'm going to let you work it out on your own.

And that is it no more PHP... Hallelujah I can hear you yelling. The final thing we need to do is tell our theme about the functions we have written and put the settings tags into the CSS.

===Finishing it all off===

So there are two things we have to do in order to complete this section and have our the settings page implemented and our settings being used.

First we need to tell our theme that we want to use the function ''demystified_process_css'' as the ''csspostprocess'' function. This is done very simply by adding the following line of PHP to the bottom of our theme's config.php file '''theme/demystified/config.php'''.

<code php>
$THEME->csspostprocess = 'demystified_process_css';
</code>

With that done the only thing left is to add the settings tag into the CSS. Remember those settings tags are:

; <nowiki>[[setting:backgroundcolor]]</nowiki> : We need to add this where ever we want the background colour setting to be used.
; <nowiki>[[setting:regionwidth]]</nowiki> : We need to add this where ever we want to set the width of the block regions.
; <nowiki>[[setting:regionwidthdouble]]</nowiki> : We need to add this where ever we want to set the doubled width of the block regions.
; <nowiki>[[setting:customcss]]</nowiki> : We need to add this to the bottom of the CSS file that we want the custom CSS added to.

So lets make those changes in CSS now, open up your ''core.css'' file and replace the CSS with the CSS below:
<code css>
/** Background color is a setting **/
html {background-color:[[setting:backgroundcolor]];}
body {margin:30px;padding:0;border:1px solid #333;border-width:0 10px 0 10px;background-color:#333;}
body #page {background-color:#FFF;position:relative;top:-10px;}
.block .header {background-image:none;background-color:#0C5CAC;border:1px solid #0C5CAC;color:#FFF;}
.block {border-color:#4BA7FF;background-color:#DDEEFF;}
.block .content {background-color:#F1F8FF;}
a:link,
a:visited {color:#0C5CAC;}
a:hover {color:#C77500;}
#page #page-header {background-color:#0C5CAC;margin:0;padding:0;width:100%;color:#fff;}
#page #page-header a:link, #page #page-header a:visited {color:#FFAC02}
#page #page-header .navbar, #page #page-header .navbar a:link, #page #page-header .navbar a:visited {color:#0C5CAC;}
/** Override the region width **/
#page-content #region-main-box {left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidthdouble]];}
#page-content #region-main-box #region-post-box #region-pre {width:[[setting:regionwidth]];left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-post {width:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidthdouble]];}
.side-pre-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-pre-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
/** Custom CSS **/
[[setting:customcss]]
</code>

You will notice that <nowiki>[[setting:backgroundcolor]]</nowiki> has been used for the html tags background colour:
<code css>
html {background-color:[[setting:backgroundcolor]];}
</code>

We have also set the width of the block regions by adding <nowiki>[[setting:regionwidth]]</nowiki> as the width for region-pre and region-post as shown below:
<code css>
#page-content #region-main-box {left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidthdouble]];}
#page-content #region-main-box #region-post-box #region-pre {width:[[setting:regionwidth]];left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-post {width:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidthdouble]];}
.side-pre-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-pre-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
</code>
You'll notice here that we have to set several different widths and margins using the regionwidth setting and make use of the special regionwidthdouble setting that we added.

The final thing that we did was add the <nowiki>[[setting:customcss]]</nowiki> to the bottom of the file to ensure that the custom CSS comes last (and therefore can override all other CSS).

And with that we are finished. The screenshot below shows how this now looks in the browser if I set the background colour setting to '''<span style='color:#FFA800;'>#FFA800</span>''' and made the column width 240px;

[[Image:Theme.settings.page.04.png|715px|thumb|left|Our settings in action]]<br style="clear:both;" />

==Using the settings within our layout files==
Now that we have utilised the first three settings within our theme's CSS file it is time to implement the other two settings within the layout files so that they are written directly into the page.

You'll be glad to know this is no where near as difficult as utilising settings within a CSS file although it still does require a little bit of PHP.

First up is the logo setting. Into this setting the user is able to enter the URL to an image to use as the logo for the site. In my case I want this to be just a background logo on top of which I want to position the page header.

Before I start there is one thing I need to do however and that is create a default logo background that gets shown if the user hasn't set a specific logo file. To do this I simply created an image '''logo.jpg''' and put it into a pix directory within the demystified theme. You should end up with '''theme/demystified/pix/logo.jpg'''.

Next open up the front-page layout file ''theme/demystified/layout/frontpage.php''. At the top of the file is the PHP that checks what blocks regions the page has and a bit of other stuff. Well right below the existing bit of PHP we want to add the following code:
<code php>
if (!empty($PAGE->theme->settings->logo)) {
$logourl = $PAGE->theme->settings->logo;
} else {
$logourl = $OUTPUT->pix_url('logo', 'theme');
}
</code>
What we are doing here is creating a variable called $logourl that will contain the URL to a logo file that was either entered by the user or if they left it blank is that of our default logo file.

There are two things that you should notice about this. First the logo setting can be retrieved through '''$PAGE->theme->settings->logo''' and second we get the default logo url by calling '''$OUTPUT->pix_url('logo', 'theme')'''.

Now that we have the logo URL we are going to use we need to add an image to the header section of the page as shown below:
<code php>
<div id="page-header" class="clearfix">
<img class="sitelogo" src="<?php echo $logourl;?>" alt="Custom logo here" />
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
....
</code>

If you save that and browse to your sites front page you will notice that the logo file is now being shown. Hooray. However it is probably not styled too nicely so lets quickly fix that. Open up the core.css file and add the following lines of CSS to the bottom of the file.
<code css>
#page-header {position:relative;min-height:100px;}
#page-header .sitelogo {float:left;}
#page-header .headermain {position:absolute;left:0.5em;top:50px;margin:0;float:none;font-size:40px;}
</code>
These three lines position the image correctly and if you now refresh everything should appear perfectly.

With the logo done the last setting we need to deal with is the footnote setting. The idea with this setting was that the administrator could enter some text into the editor and it would be displayed in the footer of the page.

This is probably the easiest setting to implement.

Within the front page layout file that we edited above add the following lines below those we added previously.

<code php>
if (!empty($PAGE->theme->settings->footnote)) {
$footnote = $PAGE->theme->settings->footnote;
} else {
$footnote = '';
}
</code>

Here we are just collecting the footnote into a variable '''$footnote''' and setting a default footnote comment if the user hasn't entered one.

We can now echo the $footnote variable within the page footer. This can be done as shown below.

<code php>

<div id="page-footer">
<div class="footnote"><?php echo $footnote; ?></div>
<p class="helplink">
<?php echo page_doc_link(get_string('moodledocslink')) ?>
</p>
</code>

And with that done we are finished! Congratulations if you got this far.

The screenshot below shows the demystified theme we have just created that is styled by the settings page.

[[Image:Theme.settings.page.05.png|715px|thumb|left|My finished demystified theme]]<br style="clear:both" />

==Testing our creation==
Congratulations to you! If you've made it this far you have done very well. Now it is time to have a look at what we have created and give it a quick test run.

So in this tutorial we have achieved the following:

* We created a theme called demystified that is based on the standard theme.
* We added a settings page to our new theme.
* We added the following settings to our settings page:
** We can set a background colour through the admin interface.
** We can change the logo of the site.
** We can change the block region width.
** We can add a footnote to the page footer
** We can add some custom CSS to seal the deal.
* Those settings were then used in the CSS files for our theme.
* They were also used in the layout files for our theme.
* And here we are testing it all.

The screenshots below show my testing process and I change each setting and view the outcome. The great thing about this is that with theme designer mode on you see the changes as soon as the form refreshes.

[[Image:Theme.settings.page.06.png|300px|thumb|left|Default settings]]
[[Image:Theme.settings.page.07.png|300px|thumb|left|Changed the background colour setting]]
[[Image:Theme.settings.page.08.png|300px|thumb|left|Changed the logo and region width]]
[[Image:Theme.settings.page.09.png|300px|thumb|left|Added a footnote]]
[[Image:Theme.settings.page.10.png|300px|thumb|left|Added some custom CSS]]
<br style="clear:both" />

==The different settings you can use==
During this tutorial we use four different kinds of settings, a text box, text area, a select (dropdown) and the editor however as I'm sure you have all guessed there is many more some of which will certainly be useful for theme settings.

The following are examples of some of the different settings. I should add that these build upon what we have already done within the tutorial but are not included in the download.

===Colour picker===
[[Image:Theme.settings.page.11.png|400px|thumb|The colour picker]]
I can hear you all asking now 'Why didn't you mention this one earlier?' well the answer is simple it didn't exist when I first wrote the tutorial. It is an admin setting that I wrote several days after because of the fantastic effort people were putting into trying out settings pages.

A bit about the colour picker. First up it is a text box that when the page loads turns into a colour picker that can be used to select a colour and can even preview the selected colour in the page (by clicking the preview button). It is designed to be very easy to use and the code is just about as simple as creating a normal text box setting.

In the image to the left I have replaced the background colour setting we created during the tutorial with the colour picker. Lets have a look at the code involved for that.
<code php>
// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$previewconfig = array('selector'=>'html', 'style'=>'backgroundColor');
$setting = new admin_setting_configcolourpicker($name, $title, $description, $default, $previewconfig);
$temp->add($setting);
</code>
So first thing you should notice is that the first four lines of code have not changed at all!

The first change we have is to create a variable '''$previewconfig'''.
This variable is used to tell the colour picker what to do when the user clicks the preview button. It should be an array that contains two things, first a selector, and second a style.
# The selector is a CSS selector like ''.page .header h2''.
# The style is a what should change, there are two immediate values it can be, either '''backgroundColor''' or '''color'''.
In my case the selector is '''html''' to target the html tag and the style is backgroundColor to change the background colour.

The second change is to use '''admin_setting_configcolourpicker''' instead of ''admin_setting_configtext''. The arguments are nearly identical as well except that there is an extra argument to which we give the '''$previewconfig''' variable.

And that is it! it is all you need to get the colour picker up and running.

'''Extra note:''' The $previewconfig variable is optional. If you don't want a preview button the simply set ''$previewconfig = null''

==Common pitfalls and useful notes==

This section is really just a collection of pointers, tips, notes, and other short useful stuff that may be of use to those attempting this tutorial.

# First up and most importantly there are very few limitations to what you achieve in this fashion.
# If you get stuck or need a hand ask in the forums, there's always someone round who can help.
# If you do something really cool let us know, I know everyone in the community loves finding our what others are achieving.
# You don't have to use ''admin_settingpage'' you can also use '''admin_externalpage''' if you prefer. It should be noted however that it is not the preferred way to do it as admin_externalpage's were only left in Moodle 2.0 for backwards compatibility (although they are more flexible one day they will be deprecated or removed). Thank you to Darryl for raising this.
# If you find that your language strings aren't being used (you are getting language string notices) and you have double checked that you have turned '''langstringcache''' off then you may need to delete the language cache directory. This is located in the moodledata directory for you installation: moodledata/cache/lang/*. You should delete the directory for your chosen language by default ''en''.

==See also==

* [[Adding theme upgrade code]]
* [[Styling and customising the dock]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=152053 Theme 2.0: Adding a settings page to your theme] forum discussion

Creating a theme settings page

2014-09-24T21:58:44Z

Tqr: /* Foot note */ - updating

{{Template:Themes}}This document looks at how to create a settings page for your Moodle 2.x.x theme and how to make use of those settings within the CSS and layout files for your theme.

This is a pretty advanced topic and will require that you have at least an intermediate knowledge of PHP, CSS, and development in general.

==Before we begin==
[[Image:Theme.settings.page.03.png|350px|thumb|Our end goal. The settings page.]]
[[Image:Theme.settings.page.10.png|350px|thumb|And what it can do.]]
There is a huge body of knowledge that we must cover in following through this document and as such I think the best way to write this is as a tutorial.

My intentions for this tutorial are to replicate the standard theme but with a settings page that allows the administrator to set a background colour, set a logo to use with the page, and probably several other minor settings to change the way in which the theme is displayed.

I will start this tutorial by creating a new theme which will be largely a copy/paste of the current standard theme. I expect that anyone working through this tutorial has previously read the tutorial I wrote on [[Themes 2.0 creating your first theme|creating your first theme]]. If you haven't go read it now because I'm not going to go into much detail until we get to the actual process of customising the theme and introducing the settings page.

So before we finally get this started please ensure you can check off everything on the following requirements list.
* Have a Moodle installation that has already been installed and configured and is ready to use.
* Have full read/write access to that installation.
* Be prepared to delete that installation at the end of this... we will destroy it!
* Have a development environment prepared and ready to use. This includes:
** Your favourite editor installed, running, and pointed at the themes directory of your installation.
** Your browser open and your site visible.
** A bottomless coffee pot... decaf won't help you with this one.
* Have set the following settings:
** '''themedesignermode''' if you don't know what this is please read the [[Themes 2.0 creating your first theme|creating your first theme]] tutorial.
** '''allowthemechangeonurl''' turn this on, it allows you to change themes on the URL and is very handy when developing themes. ''Site Administration > Appearance > Themes > Theme settings''
** '''langstringcache''' if you don't turn this off you won't see your strings when they are added. ''Site Administration > Language > Language settings''
* And finally an insane ambition to create a customisable theme.

For those interested the theme that I create throughout this tutorial can be downloaded from the forum post in which I announce this document: http://moodle.org/mod/forum/discuss.php?d=152053
<br style="clear:right;" />

==Our goals for this tutorial==
The following is just a list goals that I hope to achieve during this tutorial. They are laid out here so that I can easily refer back to them and so that you can easily find them.
# Create a new theme called '''demystified''' based upon the standard theme within Moodle 2.0.
# Make some minor changes to that theme to allow us to more easily see what is going on.
# Create a settings page for the demystified theme.
# Add several settings to our settings page.
# Use some of those settings to alter our CSS.
# Use the rest of those settings within our layout file..
# Discuss the good, the bad, and limits of what we have just created.

So I can see you are all very excited about this point and that you would love to know what settings we are going to create; So here they are:

A setting to ...
* change the background colour (CSS).
* set the path to an image that we will use as a logo on all pages (Layout files).
* override the width of the block regions (CSS).
* allow a note to be added to the footer of all pages (Layout files).
* allow custom CSS to be written to do anything the user wants. (CSS)

==Creating the demystified theme==
Before we start here I want to remind you that I am going to look at this only briefly as I am making the assumption that you have read the [[Themes 2.0 creating your first theme|creating your first theme]] tutorial.

Well lets get into it....

The first thing we need to do is create a directory for our theme which we will call demystified.

So within your Moodle directory create the following folder '''moodle/theme/demystified'''. At the same time you can also create the following files and folders which we will get to soon.
* The file '''moodle/theme/demystified/config.php''' for our config information.
* The directory '''moodle/theme/demystified/layout''' for our layout files.
* The directory '''moodle/theme/demystified/style''' for our css files.
* The file '''moodle/theme/demystified/style/core.css''' which will contain our special CSS.

Next we will copy the layout files from the base theme to our new theme demystified. We are basing the demystified theme on the standard theme however that doesn't use it's own layout files it uses the base theme's layout files so those are the ones we want.

The reason that we are coping these layout files is that later on in this tutorial we will be modifying them to make use of our new settings... so copy all of the layout files from '''moodle/theme/base/layout''' to '''moodle/theme/demystified/layout'''.

There should be three files that you just copied:
# embedded.php
# frontpage.php
# general.php

Now we need to populate demystified/config.php with the settings for our new theme. They are as follows:
<code php>
$THEME->name = 'demystified';
</code>
Simply sets the name of our theme.

<code php>
$THEME->parents = array('standard','base');
</code>
This theme is extending both the standard theme and the base theme. Remember when extending a theme you also need to extend its parents or things might not work correctly.

<code php>
$THEME->sheets = array('core');
</code>
This tells our theme that we want to use the file '''demystified/style/core.css''' with this theme.

<div style="height:300px;overflow-y:scroll;">
<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-post',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'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),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>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),
),
// 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),
),
);
</code>
</div>
Now that all looks very complicated however its really not too bad as it is just copied from the base theme's config.php file. We can do this because we copied the layout files from the base theme to begin with and for the time being there are no changes that we wish to make. Simply open up '''theme/base/config.php''' and copy the layouts from there.

And that is it. The config.php file for our demystified theme is complete. The full source is shown below:
<div style="height:300px;overflow-y:scroll;">
<code php>
<?php

// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* The demystified theme config file
*
* This theme was created to document the process of adding a settings page to a theme
*
* @copyright 2010 Sam Hemelryk
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

// The name of our theme
$THEME->name = 'demystified';

// The other themes this theme extends
$THEME->parents = array('standard','base');

// The CSS files this theme uses (located in the style directory)
$THEME->sheets = array('core');

// The layout definitions for this theme
$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-post',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'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),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>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),
),
// 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),
),
);
</code>
</div>

The screenshot below shows both the directory structure we have now created and the theme presently.

[[Image:Theme.settings.page.01.png]]

To view the theme so far open you browser and enter the URL of your site followed by '''?theme=demystified'''. You should see the theme that we just created which will look exactly like the base standard theme.

The final thing that we want to do is add a little bit of CSS to the demystified theme that will both visually set this theme apart from the standard theme and second build a the base which our settings can later extend.

I added the following snippet of CSS to the file '''demystified/style/core.css'''.
<code css>
html {background-color:#DDD;}
body {margin:30px;padding:0;border:1px solid #333;border-width:0 10px 0 10px;background-color:#333;}
body #page {background-color:#FFF;position:relative;top:-10px;}
.block .header {background-image:none;background-color:#0C5CAC;border:1px solid #0C5CAC;color:#FFF;}
.block {border-color:#4BA7FF;background-color:#DDEEFF;}
.block .content {background-color:#F1F8FF;}
a:link,
a:visited {color:#0C5CAC;}
a:hover {color:#C77500;}
#page #page-header {background-color:#0C5CAC;margin:0;padding:0;width:100%;color:#fff;}
#page #page-header a:link, #page #page-header a:visited {color:#FFAC02}
#page #page-header .navbar, #page #page-header .navbar a:link, #page #page-header .navbar a:visited {color:#0C5CAC;}
</code>

The CSS that we have just added to our theme sets a couple of colours on the front page. Presently this is the only CSS I will add, I know it isn't complete by any means but it achieves it's purpose as the screenshot below illustrates.

[[Image:Theme.settings.page.02.png|715px|thumb|left|The newly styles demystified theme]]<br style="clear:both;" />

And with that I will move on to the real purpose of this tutorial, creating the settings page

==Setting up the settings page==
With the demystified theme set up it is time to create the settings page. This is where the real PHP fun begins.

For those of you who happen to be familiar with development of modules, blocks or other plugin types you have probably encountered settings pages before and this is not going to be any different.

However for those who haven't which I imagine is most of you this is going to be quite a challenge. I will try to walk through this step by step however if at any point you get stuck don't hesitate to ask in the forums as I imagine you will get a speedy response.

===How settings pages work in Moodle===
Settings pages can be used by nearly every plugin type, of which themes is of course one. The way in which it all works isn't too tricky to understand.

All of the settings for Moodle can be configured through the administrator interfaces when logged in. I am sure that everyone here has seen those pages and has changed a setting or two before so you will all know what I am talking about. Well the settings page for a theme is no different. It will be shown in the administration pages tree under '''Appearance > Themes''' and all we have to do is tell Moodle what settings there are.

This is done by creating a settings.php file within our theme into which we will add code that tells Moodle about the settings we want to add/use.

When telling Moodle about each setting we are simply creating a new ''admin_setting'' instance of the type we want and the properties we want and then adding it to our settings page.

There is really not much more too it at this level. Things can get very complex very fast so the best thing we can do now is start creating our settings.php file for the demystified theme and see where it leads us.

===Creating the settings page===
So as mentioned before we need a settings.php file which we will create now. To begin with create the file '''theme/demystified/settings.php''' and open it in your favourite editor so its ready to go.

Before we start adding code however lets just remember the settings that we want to create:
* change the background colour (CSS).
* set the path to an image that we will use as a logo on all pages (Layout files).
* override the width of the block regions (CSS).
* allow a note to be added to the footer of all pages (Layout files).
* allow custom CSS to be written to do anything the user wants. (CSS)

Alright.

Now thinking about this the first setting is as basic as it gets, all we need is a text box that the user can type a colour into.

The second is to allow a logo to be used in the header of each page. What we want here is a path but should it be a physical path e.g. C:/path/to/image.png or should it be a web path e.g. <nowiki>http://mysite.com/path/to/image.png</nowiki>?
For the purpose of this tutorial I am going to go with a web path because it is going to be easier to code and will hopefully be a little easier to understand to begin with.

The third setting is a little more complex. For this I want a drop down box with some specific widths that the administrator can select.

The forth and the fifth settings are both pretty straight forward, there we want a textarea into which the user can enter what ever they want and we will do something useful with it.

Now that we have an understanding about the settings we wish to define pull up your editor and lets start coding....

<code php>
<?php

/**
* Settings for the demystified theme
*/
defined('MOODLE_INTERNAL') || die;

if ($ADMIN->fulltree) {
</code>
This is the first bit of code we must enter, the first line is of course just the opening php tag, secondly we have a comment that describes this file, and then we get create a new '''admin_settingspage object'''.

This admin_settingspage object that we have just created is a representation of our settings page and is the what we add our new settings to. When creating it we give it two arguments, first the name of the page which is in this case '''theme_''themename''''' and the title for the page which we get with the get_string method.

At the moment I'm not going to worry about adding the string, we will get to that later once we have defined all of our settings.

====Background colour====

With the page now created lets add our first setting: Background colour.

<code php>
// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$setting = new admin_setting_configtext($name, $title, $description, $default, PARAM_CLEAN, 12);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
Thankfully this isn't as difficult as it initially looks.

The first line of code is creating a variable for the name of the background colour setting. In this case it is '''theme_demystified/backgroundcolor'''.

The name is very important, for the setting to be usable we have to follow a strict naming convention. '''theme_''themename''/''settingname''''' where '''''themename''''' is the name of the theme the setting belongs to and '''''settingname''''' is the name for the setting by which we will use it.

The second line of code creates a variable that contains the title of the setting. This is what the user sees to the right of the setting on the settings page and should be a short description of the setting. Here we are again using the ''get_string'' method so we will need to remember to add that string later on.

The third line of code sets the description. This should describe what the setting does or how it works and again we will use the get_string method.

The fourth line creates a variable that will be used as the default value for the setting. Because this setting is a colour we want an HTML colour to be the default value.

The fifth line is where we put it all together. Here we create a new '''admin_setting_configtext''' object. This object will represent the background colour setting.

When we create it we need to give it 6 different things.
# The name of the setting. In this case we have a variable '''$name'''.
# The title for this setting. We used the variable '''$title'''.
# The description of the setting '''$description'''.
# The default value for the setting. '''$default''' is the variable this.
# The type of value we want the user to enter. For this we have used PARAM_CLEAN which tells Moodle to get rid of any nasties from what the user enters.
# The size of the field. In our case 12 characters will be plenty.

The sixth and final line of code adds our newly created setting to the administration page we created earlier.

That is it we have successfully created and added our first setting, however there are several more to settings to do, and there are a couple of important things that you need to be aware of before we move on.

First: There are several different types of settings that you can create and add to a page, and each one may differ in what they need you to give them. In this case it was name, title, description, default, type, and size. However other settings will likely require different things. Smart editors like Netbeans or Eclipse can tell you what is required, otherwise you will need to research it.

Second: Normally settings are declared on one line as follows:
<code php>
$setting->add(new admin_setting_configtext('theme_demystified/backgroundcolor', get_string('backgroundcolor','theme_demystified'), get_string('backgroundcolordesc', 'theme_demystified'), '#DDD', PARAM_CLEAN, 12));
</code>
While this is structurally identical as all we have done is move everything onto one line and do away with the variables it is a little harder to read when you are learning all of this.

====The logo file====
Time to create the second setting that will allow the user to enter a URL to an image they wish to use as the logo on their site.
<code php>
// Logo file setting
$name = 'theme_demystified/logo';
$title = get_string('logo','theme_demystified');
$description = get_string('logodesc', 'theme_demystified');
$setting = new admin_setting_configtext($name, $title, $description, '', PARAM_URL);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
The first thing that you will notice about this setting that it is very similar to the first setting, in fact all we have changed is the name, title, description, and default value. We have however changed the value type from PARAM_CLEAN to PARAM_URL, this makes sure the user enters a URL. You will also notice that for this one we don't set a size for the field as we have no idea how long the URL will be.

====Block region width====
The third setting should allow the user to set a width for the block regions that will be used as columns.

For this setting I want to do something a little different from the previous two, here I want to use a select box so that the user selects a width for the column from a list I provide.
<code php>
// Block region width
$name = 'theme_demystified/regionwidth';
$title = get_string('regionwidth','theme_demystified');
$description = get_string('regionwidthdesc', 'theme_demystified');
$default = 200;
$choices = array(150=>'150px', 170=>'170px', 200=>'200px', 240=>'240px', 290=>'290px', 350=>'350px', 420=>'420px');
$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
So looking at the code: The first four lines you will recognise. $name, $title, $description, and $default are all being set.

The fifth line of code however introduces something new. Of course in order to have a select box we have to have options, in this case we have an array of options stored in the variable $choices.

The array of options is constructed of a collection of '''''value''' => '''label''''' pairs. Notice how we don't add '''px''' to the value. This is is very intentional as later on I need to do a little bit of math with that value so we need it to be a number.

The lines after should look familiar again, the only difference being that instead of a ''admin_setting_configtext'' setting we have created a ''admin_setting_configselect'' for which we must give the choices for the select box as the fifth argument.

Woohoo, we've just created our first select box setting.

====Foot note====
Now to create the foot note setting. Here we want the user to be able to enter some arbitrary text that will be used in the footer of the page. For this I want the user to be able to enter some HTML so I will create an editor setting.
<code php>
// Foot note setting
$name = 'theme_demystified/footnote';
$title = get_string('footnote','theme_demystified');
$description = get_string('footnotedesc', 'theme_demystified');
$setting = new admin_setting_confightmleditor($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
How simple is that!

It is just about identical to the first two settings except that for this we have created a ''admin_setting_confightmleditor'' setting rather than a text setting.

Note: You can also set the columns and rows for the editor setting using the fifth and sixth arguments.

====Custom CSS====
The final setting is to allow the user to add some custom CSS to the theme that will be used on every page. I want this to be a plain textarea into which the user can enter CSS.
<code php>
// Custom CSS file
$name = 'theme_demystified/customcss';
$title = get_string('customcss','theme_demystified');
$description = get_string('customcssdesc', 'theme_demystified');
$setting = new admin_setting_configtextarea($name, $title, $description, '');
$temp->add($setting);
</code>
Just like the editor or text settings. It's getting very easy now!

====Finishing settings.php====
With all of our settings defined and added to our page that we created right at the beginning it is time to finish it all off.
<code php>
// Add our page to the structure of the admin tree
$ADMIN->add('themes', $temp);
</code>
The above line of code is the final line for the page. It is adding the page that we have created '''$temp''' to the admin tree structure. In this case it is adding it to the themes branch.

The following is the completed source for our settings.php ..... for your copy/paste pleasure.
<div style='height:300px;overflow:auto;'>
<code php>
<?php

/**
* Settings for the demystified theme
*/

// Create our admin page
$temp = new admin_settingpage('theme_demystified', get_string('configtitle','theme_demystified'));

// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$setting = new admin_setting_configtext($name, $title, $description, $default, PARAM_CLEAN, 12);
$temp->add($setting);

// Logo file setting
$name = 'theme_demystified/logo';
$title = get_string('logo','theme_demystified');
$description = get_string('logodesc', 'theme_demystified');
$setting = new admin_setting_configtext($name, $title, $description, '', PARAM_URL);
$temp->add($setting);

// Block region width
$name = 'theme_demystified/regionwidth';
$title = get_string('regionwidth','theme_demystified');
$description = get_string('regionwidthdesc', 'theme_demystified');
$default = 200;
$choices = array(150=>'150px', 170=>'170px', 200=>'200px', 240=>'240px', 290=>'290px', 350=>'350px', 420=>'420px');
$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$temp->add($setting);

// Foot note setting
$name = 'theme_demystified/footnote';
$title = get_string('footnote','theme_demystified');
$description = get_string('footnotedesc', 'theme_demystified');
$setting = new admin_setting_confightmleditor($name, $title, $description, '');
$temp->add($setting);

// Custom CSS file
$name = 'theme_demystified/customcss';
$title = get_string('customcss','theme_demystified');
$description = get_string('customcssdesc', 'theme_demystified');
$setting = new admin_setting_configtextarea($name, $title, $description, '');
$temp->add($setting);

// Add our page to the structure of the admin tree
$ADMIN->add('themes', $temp);
</code>
</div>

===Creating a language file and adding our strings===
As I'm sure none of you have forgotten, throughout the creation of the our settings.php page, we used a lot of strings that I mentioned we would set later on. Well now is the time to set those strings.

First up create the following directories and file for our language strings:
* Directory '''theme/demystified/lang'''
* Directory '''theme/demystified/lang/en'''
* File '''theme/demystified/lang/theme_demystified.php'''

What we have created here is the required structure for Moodle to start looking for language strings.

First Moodle locates the lang directory, once found it looks within that directory for another directory that uses the character code for the language the user has selected, by default this is '''en''' for English. Once that is found it looks for the appropriate language file, in this case '''theme_demystified.php''' from which it will load all language strings for our theme.

If English isn't your chosen language simply replace the ''en'' directory with one that uses your chosen languages character code (two letters).

We can now add our language strings to '''theme/demystified/lang/theme_demystified.php'''. Copy and paste the following lines of PHP into this file.
<code php>
<?php

/**
* This file contains the strings used by the demystified theme
*/

$string['backgroundcolor'] = 'Background colour';
$string['backgroundcolordesc'] = 'This sets the background colour for the theme.';
$string['configtitle'] = 'Demystified theme';
$string['customcss'] = 'Custom CSS';
$string['customcssdesc'] = 'Any CSS you enter here will be added to every page allowing your to easily customise this theme.';
$string['footnote'] = 'Footnote';
$string['footnotedesc'] = 'The content from this textarea will be displayed in the footer of every page.';
$string['logo'] = 'Logo';
$string['logodesc'] = 'Enter the URL to an image to use as the logo for this site. Should be http://www.yoursite.com/path/to/logo.png';
$string['pluginname'] = 'Demystified';
$string['regionwidth'] = 'Column width';
$string['regionwidthdesc'] = 'This sets the width of the two block regions that form the left and right columns.';
</code>

In the above lines of code I have added an entry for each language string we used within ''settings.php''. When adding language strings like this make sure you use single quotes and try to keep things alphabetical - it helps greatly when managing strings.

Now when we view the settings page there will not be any errors or strings missing.

===Having a look at what we have created===
Now that we have created our settings page (settings.php) and added all of the language strings it is time to have a look at things in your browser.

Open your browser and enter the URL to your site. When you arrive at your site login as an administrator.

If you are not redirected to view the new settings change your URL to <nowiki>http://www.yoursite.com/admin/</nowiki> and your will see a screen to set the new theme settings we have just created. This lets us know that everything has worked correctly.

At any point now you are able to log in as administrator and within the settings block browse to '''Site administration > Appearance > Themes > Demystified theme''' to change those settings.

The screenshot below shows you what you should see at this point:

[[Image:Theme.settings.page.03.png|715px|thumb|left|The settings page we just created]]
<br style="clear:both;" />

==Using the settings in CSS==
With the settings page now created and operational it is time to make use of our new settings. The settings that we want to use within our CSS is as follows:

; backgroundcolor : Will be used to set the background colour in CSS.
; regionwidth : Will be the width of the column for CSS.
; customcss : Will be some custom CSS to add to our stylesheet.

At this point those names are the names we used for our setting with the slash and everything before it having been removed.

Before we start tearing into some code it is important that we have a look at what we are going to do and how we are going to go about it.

===How it all works within Moodle===
The first thing to understand is that while Moodle allows you to create a settings page and automates it inclusion and management right into the administration interfaces there is no smart equivalent for using the settings. This is simply because there is no way to predict how people will want to use the settings.

However don't think of this as a disadvantage, in fact it is quite the contrary. Although we can't just ''use'' our settings we can take full control over how and where we use them. It means it will take a little more code but in the end that will work to our advantage as we can do anything we want.

Moodle does help us out a little but not in an obvious way. The first thing that Moodle does is look for a config variable '''csspostprocess''' that should be the name of a function which we want called to make any changes to the CSS after it has been prepared.

The second thing Moodle does is include a lib.php from the theme's directory if one exists (also for the themes the current theme extends.) which ensures that as long as we write our code within '''theme/demystified/lib.php''' it will be included and ready to be used.

The third and final thing Moodle does that will help us out here is ensure that by the time any of code is ready to execute the settings have been prepared and are ready to be used within a theme config object which is passed into our ''csspostprocess'' function.

===Our plan===
As you have already probably guessed we will need to create a function to make the changes to the CSS that we want. We will then set the theme config option '''$THEME->csspostprocess''' to the name of our function.

By doing this when Moodle builds the CSS file it will call our function afterwards with the CSS and the theme object that contains our setting.

Now we know that we will use the ''csspostprocess'' function but how are we going to change the CSS, we could get the function to add CSS, or we could get the function to replace something within the CSS. My personal preference is to replace something within the CSS, just like what is happening with images. If you want to use an image within CSS you would write <nowiki>[[pix:theme|imagename]]</nowiki>.

For settings I am going to use <nowiki>[[setting:settingname]]</nowiki>, this way it looks a bit like something you are already familiar with.

What we need to decide upon next is the best way in which to replace our settings tag with the settings that the user has set.

There are two immediate options available to us:
# Make the ''csspostprocess'' function do all the work.
# Make the ''csspostprocess'' function call a separate function for each setting.
Solution 1 might sound like the simplest however it is going to result in a '''VERY''' complex function. Remember the user might have left settings blank or entered something that wouldn't be valid so we would need to make the sure there is some validation and a good default.
Because of this I think that solution 2 is the better solution.

So we are going to need a ''csspostprocess'' function and then a function for each of the three settings we have that will do the replacements.
<code php>
// This is our css post process function
function demystified_process_css($css, $theme) {};
// This replaces [[setting:backgroundcolor]] with the background colour
function demystified_set_backgroundcolor($css, $backgroundcolor) {};
// This replaces [[setting:regionwidth]] with the correct region width
function demystified_set_regionwidth() {$css, $regionwidth};
// This replaces [[setting:customcss]] with the custom css
function demystified_set_customcss() {$css, $customcss};
</code>

What you should note about the above functions is that they all start with the theme's name. This is required to ensure that the functions are named uniquely as it is VERY unlikely that someone has already created these functions.

So with our plan set out lets start writing the code.

===Writing the code===
The very first thing that we need to do is create a lib.php for our theme into which our css processing functions are going to go. So please at this point create '''theme/demystified/lib.php''' and open it in your editor ready to go.

The first bit of code we have to write is the function that will be called by Moodle to do the processing '''demystified_process_css'''.

Before we start out please remember that the wonderful thing about coding is that there is any number of solutions to a problem. The solutions that you are seeing here in this tutorial are solutions that I have come up with to meet fulfil the needs of the tutorial without being so complex that they are hard to understand. This probably isn't how I would go about it normally but this is a little easier to understand for those who aren't overly familiar with PHP and object orientation.

====The function: demystified_process_css====

<code php>
function demystified_process_css($css, $theme) {

if (!empty($theme->settings->backgroundcolor)) {
$backgroundcolor = $theme->settings->backgroundcolor;
} else {
$backgroundcolor = null;
}
$css = demystified_set_backgroundcolor($css, $backgroundcolor);

if (!empty($theme->settings->regionwidth)) {
$regionwidth = $theme->settings->regionwidth;
} else {
$regionwidth = null;
}
$css = demystified_set_regionwidth($css, $regionwidth);

if (!empty($theme->settings->customcss)) {
$customcss = $theme->settings->customcss;
} else {
$customcss = null;
}
$css = demystified_set_customcss($css, $customcss);

return $css;
}
</code>

So lets look at the things that make up this function:

<code php>
function demystified_process_css($css, $theme) {
//.....
return $css
}
</code>

This of course is the function declaration.

The function gets given two variables, the first '''$css''' is a pile of CSS as one big string, and the second is the theme object '''$theme''' that contains all of the configuration, options, and settings for our theme.

It then returns the ''$css'' variable, essentially returning the modified CSS.

<code php>
//...
if (!empty($theme->settings->backgroundcolor)) {
$backgroundcolor = $theme->settings->backgroundcolor;
} else {
$backgroundcolor = null;
}
$css = demystified_set_backgroundcolor($css, $backgroundcolor);
//...
</code>

Here we are processing our first setting ''backgroundcolor''.

The first thing that we need to do is check whether it has been set and whether it has a value. If it has then we store that value in '''$backgroundcolor'''. It is doesn't have a value then we set ''$backgroundcolor'' to null. This ensures that ''$backgroundcolor'' is set because if it isn't then you are going to get a notice (if you have debugging on).

The final line of this block calls the function '''demystified_set_backgroundcolor'''. We haven't written this function yet but we will shortly. When we call it we give it the ''$css'' variable that contains all of the CSS and we give it the background colour variable ''$backgroundcolor''. Once this function is finished it returns the ''$css'' variable with all of the changes made much like how our css processing function works.

What you should also note about this code is this:
<code php>
$theme->settings->backgroundcolor
</code>
As mentioned earlier ''$theme'' is an object that contains all of the configuration and settings for our theme. The ''$theme'' object has a $settings property which contains all of the settings for our theme, and finally the settings property contains a variable backgroundcolor that is the value the user entered for that setting. That is how we get a settings value.

<code php>
if (!empty($theme->settings->regionwidth)) {
$regionwidth = $theme->settings->regionwidth;
} else {
$regionwidth = null;
}
$css = demystified_set_regionwidth($css, $regionwidth);

if (!empty($theme->settings->customcss)) {
$customcss = $theme->settings->customcss;
} else {
$customcss = null;
}
$css = demystified_set_customcss($css, $customcss);
</code>

These two routines are nearly identical to the routine above. For both the regionwidth and the customcss we make sure it has a value and then store it in a variable. We then call the relevant function to make the changes for that setting.

Now that we have the general processing function it is time to write the three functions we have used but not written, ''demystified_set_backgroundcolor'', ''demystified_set_regionwidth'', ''demystified_set_customcss''.

====The function: demystified_set_backgroundcolor====

First up demystified_set_backgroundcolor.

<code php>
/**
* Sets the background colour variable in CSS
*
* @param string $css
* @param mixed $backgroundcolor
* @return string
*/
function demystified_set_backgroundcolor($css, $backgroundcolor) {
$tag = '[[setting:backgroundcolor]]';
$replacement = $backgroundcolor;
if (is_null($replacement)) {
$replacement = '#DDDDDD';
}
$css = str_replace($tag, $replacement, $css);
return $css;
}
</code>

Ok so what is happening here?

First we need a variable '''$tag''' that contains the tag we are going to replace. As mentioned earlier we are going to use tags that look like the image tags you are already familiar with ''<nowiki>[[setting:settingname]]</nowiki>'', in this case ''<nowiki>[[setting:backgroundcolor]]</nowiki>''.

Next I am going to create a variable called '''$replacement''' into which I put '''$backgroundcolor'''.

The '''IF''' statement that comes next checks ''$replacement'' to make sure it is not null. If it is then we need to set it to a default value. In this case I have used ''#DDD'' as that was the default for the settings.

The line after the IF statement puts it all together. The ''str_replace'' function that we are calling takes three arguments in this order:
# The text to search for.
# The text to replace it with.
# The text to do the replacement in.
It then returns the text with all of the replacements made. So in this case we are replacing the tag with the background colour and it is returning the changed CSS.

The final thing is to return the ''$css'' variable which now contains the correct background colour.

====The function: demystified_set_regionwidth====

Next we have the demystified_set_regionwidth function.
<code php>
/**
* Sets the region width variable in CSS
*
* @param string $css
* @param mixed $regionwidth
* @return string
*/
function demystified_set_regionwidth($css, $regionwidth) {
$tag = '[[setting:regionwidth]]';
$doubletag = '[[setting:regionwidthdouble]]';
$replacement = $regionwidth;
if (is_null($replacement)) {
$replacement = 200;
}
$css = str_replace($tag, $replacement.'px', $css);
$css = str_replace($doubletag, ($replacement*2).'px', $css);
return $css;
}
</code>

This function is very similar to the above function however there is one key thing we are doing different. We are doing two replacements.

# The first replacement is for the width that the user selected. In this case I am replacing the tag ''<nowiki>[[setting:regionwidth]]</nowiki>'' with the width.
# The second replacement is for the width x 2. This is because the page layout requires that the width be doubled for some of the CSS. Here I will replace ''<nowiki>[[setting:regionwidthdouble]]</nowiki>'' with the doubled width.

Remember because it is still just a number we need to add '''px''' to the end of each before we do the replacement.

So the overall process of this function is:
# Define the two tags as '''$tag''' and '''$doubletag'''.
# Make '''$replacement''' the region width ''$regionwidth''.
# Set ''$replacement'' to a default value of 200 is it is null.
# Replace '''<nowiki>[[setting:regionwidth]]</nowiki>''' with the width.
# Replace '''<nowiki>[[setting:regionwidthdouble]]</nowiki>''' with the width x 2.
# Return the changed CSS.

====The function: demystified_set_customcss====

The final function that we need to write is the demystified_set_customcss function.
<code php>
/**
* Sets the custom css variable in CSS
*
* @param string $css
* @param mixed $customcss
* @return string
*/
function demystified_set_customcss($css, $customcss) {
$tag = '[[setting:customcss]]';
$replacement = $customcss;
if (is_null($replacement)) {
$replacement = '';
}
$css = str_replace($tag, $replacement, $css);
return $css;
}
</code>

This function is just like the first function. I'm going to let you work it out on your own.

And that is it no more PHP... Hallelujah I can hear you yelling. The final thing we need to do is tell our theme about the functions we have written and put the settings tags into the CSS.

===Finishing it all off===

So there are two things we have to do in order to complete this section and have our the settings page implemented and our settings being used.

First we need to tell our theme that we want to use the function ''demystified_process_css'' as the ''csspostprocess'' function. This is done very simply by adding the following line of PHP to the bottom of our theme's config.php file '''theme/demystified/config.php'''.

<code php>
$THEME->csspostprocess = 'demystified_process_css';
</code>

With that done the only thing left is to add the settings tag into the CSS. Remember those settings tags are:

; <nowiki>[[setting:backgroundcolor]]</nowiki> : We need to add this where ever we want the background colour setting to be used.
; <nowiki>[[setting:regionwidth]]</nowiki> : We need to add this where ever we want to set the width of the block regions.
; <nowiki>[[setting:regionwidthdouble]]</nowiki> : We need to add this where ever we want to set the doubled width of the block regions.
; <nowiki>[[setting:customcss]]</nowiki> : We need to add this to the bottom of the CSS file that we want the custom CSS added to.

So lets make those changes in CSS now, open up your ''core.css'' file and replace the CSS with the CSS below:
<code css>
/** Background color is a setting **/
html {background-color:[[setting:backgroundcolor]];}
body {margin:30px;padding:0;border:1px solid #333;border-width:0 10px 0 10px;background-color:#333;}
body #page {background-color:#FFF;position:relative;top:-10px;}
.block .header {background-image:none;background-color:#0C5CAC;border:1px solid #0C5CAC;color:#FFF;}
.block {border-color:#4BA7FF;background-color:#DDEEFF;}
.block .content {background-color:#F1F8FF;}
a:link,
a:visited {color:#0C5CAC;}
a:hover {color:#C77500;}
#page #page-header {background-color:#0C5CAC;margin:0;padding:0;width:100%;color:#fff;}
#page #page-header a:link, #page #page-header a:visited {color:#FFAC02}
#page #page-header .navbar, #page #page-header .navbar a:link, #page #page-header .navbar a:visited {color:#0C5CAC;}
/** Override the region width **/
#page-content #region-main-box {left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidthdouble]];}
#page-content #region-main-box #region-post-box #region-pre {width:[[setting:regionwidth]];left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-post {width:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidthdouble]];}
.side-pre-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-pre-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
/** Custom CSS **/
[[setting:customcss]]
</code>

You will notice that <nowiki>[[setting:backgroundcolor]]</nowiki> has been used for the html tags background colour:
<code css>
html {background-color:[[setting:backgroundcolor]];}
</code>

We have also set the width of the block regions by adding <nowiki>[[setting:regionwidth]]</nowiki> as the width for region-pre and region-post as shown below:
<code css>
#page-content #region-main-box {left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidthdouble]];}
#page-content #region-main-box #region-post-box #region-pre {width:[[setting:regionwidth]];left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-post {width:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidthdouble]];}
.side-pre-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-pre-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
</code>
You'll notice here that we have to set several different widths and margins using the regionwidth setting and make use of the special regionwidthdouble setting that we added.

The final thing that we did was add the <nowiki>[[setting:customcss]]</nowiki> to the bottom of the file to ensure that the custom CSS comes last (and therefore can override all other CSS).

And with that we are finished. The screenshot below shows how this now looks in the browser if I set the background colour setting to '''<span style='color:#FFA800;'>#FFA800</span>''' and made the column width 240px;

[[Image:Theme.settings.page.04.png|715px|thumb|left|Our settings in action]]<br style="clear:both;" />

==Using the settings within our layout files==
Now that we have utilised the first three settings within our theme's CSS file it is time to implement the other two settings within the layout files so that they are written directly into the page.

You'll be glad to know this is no where near as difficult as utilising settings within a CSS file although it still does require a little bit of PHP.

First up is the logo setting. Into this setting the user is able to enter the URL to an image to use as the logo for the site. In my case I want this to be just a background logo on top of which I want to position the page header.

Before I start there is one thing I need to do however and that is create a default logo background that gets shown if the user hasn't set a specific logo file. To do this I simply created an image '''logo.jpg''' and put it into a pix directory within the demystified theme. You should end up with '''theme/demystified/pix/logo.jpg'''.

Next open up the front-page layout file ''theme/demystified/layout/frontpage.php''. At the top of the file is the PHP that checks what blocks regions the page has and a bit of other stuff. Well right below the existing bit of PHP we want to add the following code:
<code php>
if (!empty($PAGE->theme->settings->logo)) {
$logourl = $PAGE->theme->settings->logo;
} else {
$logourl = $OUTPUT->pix_url('logo', 'theme');
}
</code>
What we are doing here is creating a variable called $logourl that will contain the URL to a logo file that was either entered by the user or if they left it blank is that of our default logo file.

There are two things that you should notice about this. First the logo setting can be retrieved through '''$PAGE->theme->settings->logo''' and second we get the default logo url by calling '''$OUTPUT->pix_url('logo', 'theme')'''.

Now that we have the logo URL we are going to use we need to add an image to the header section of the page as shown below:
<code php>
<div id="page-header" class="clearfix">
<img class="sitelogo" src="<?php echo $logourl;?>" alt="Custom logo here" />
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
....
</code>

If you save that and browse to your sites front page you will notice that the logo file is now being shown. Hooray. However it is probably not styled too nicely so lets quickly fix that. Open up the core.css file and add the following lines of CSS to the bottom of the file.
<code css>
#page-header {position:relative;min-height:100px;}
#page-header .sitelogo {float:left;}
#page-header .headermain {position:absolute;left:0.5em;top:50px;margin:0;float:none;font-size:40px;}
</code>
These three lines position the image correctly and if you now refresh everything should appear perfectly.

With the logo done the last setting we need to deal with is the footnote setting. The idea with this setting was that the administrator could enter some text into the editor and it would be displayed in the footer of the page.

This is probably the easiest setting to implement.

Within the front page layout file that we edited above add the following lines below those we added previously.

<code php>
if (!empty($PAGE->theme->settings->footnote)) {
$footnote = $PAGE->theme->settings->footnote;
} else {
$footnote = '';
}
</code>

Here we are just collecting the footnote into a variable '''$footnote''' and setting a default footnote comment if the user hasn't entered one.

We can now echo the $footnote variable within the page footer. This can be done as shown below.

<code php>

<div id="page-footer">
<div class="footnote"><?php echo $footnote; ?></div>
<p class="helplink">
<?php echo page_doc_link(get_string('moodledocslink')) ?>
</p>
</code>

And with that done we are finished! Congratulations if you got this far.

The screenshot below shows the demystified theme we have just created that is styled by the settings page.

[[Image:Theme.settings.page.05.png|715px|thumb|left|My finished demystified theme]]<br style="clear:both" />

==Testing our creation==
Congratulations to you! If you've made it this far you have done very well. Now it is time to have a look at what we have created and give it a quick test run.

So in this tutorial we have achieved the following:

* We created a theme called demystified that is based on the standard theme.
* We added a settings page to our new theme.
* We added the following settings to our settings page:
** We can set a background colour through the admin interface.
** We can change the logo of the site.
** We can change the block region width.
** We can add a footnote to the page footer
** We can add some custom CSS to seal the deal.
* Those settings were then used in the CSS files for our theme.
* They were also used in the layout files for our theme.
* And here we are testing it all.

The screenshots below show my testing process and I change each setting and view the outcome. The great thing about this is that with theme designer mode on you see the changes as soon as the form refreshes.

[[Image:Theme.settings.page.06.png|300px|thumb|left|Default settings]]
[[Image:Theme.settings.page.07.png|300px|thumb|left|Changed the background colour setting]]
[[Image:Theme.settings.page.08.png|300px|thumb|left|Changed the logo and region width]]
[[Image:Theme.settings.page.09.png|300px|thumb|left|Added a footnote]]
[[Image:Theme.settings.page.10.png|300px|thumb|left|Added some custom CSS]]
<br style="clear:both" />

==The different settings you can use==
During this tutorial we use four different kinds of settings, a text box, text area, a select (dropdown) and the editor however as I'm sure you have all guessed there is many more some of which will certainly be useful for theme settings.

The following are examples of some of the different settings. I should add that these build upon what we have already done within the tutorial but are not included in the download.

===Colour picker===
[[Image:Theme.settings.page.11.png|400px|thumb|The colour picker]]
I can hear you all asking now 'Why didn't you mention this one earlier?' well the answer is simple it didn't exist when I first wrote the tutorial. It is an admin setting that I wrote several days after because of the fantastic effort people were putting into trying out settings pages.

A bit about the colour picker. First up it is a text box that when the page loads turns into a colour picker that can be used to select a colour and can even preview the selected colour in the page (by clicking the preview button). It is designed to be very easy to use and the code is just about as simple as creating a normal text box setting.

In the image to the left I have replaced the background colour setting we created during the tutorial with the colour picker. Lets have a look at the code involved for that.
<code php>
// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$previewconfig = array('selector'=>'html', 'style'=>'backgroundColor');
$setting = new admin_setting_configcolourpicker($name, $title, $description, $default, $previewconfig);
$temp->add($setting);
</code>
So first thing you should notice is that the first four lines of code have not changed at all!

The first change we have is to create a variable '''$previewconfig'''.
This variable is used to tell the colour picker what to do when the user clicks the preview button. It should be an array that contains two things, first a selector, and second a style.
# The selector is a CSS selector like ''.page .header h2''.
# The style is a what should change, there are two immediate values it can be, either '''backgroundColor''' or '''color'''.
In my case the selector is '''html''' to target the html tag and the style is backgroundColor to change the background colour.

The second change is to use '''admin_setting_configcolourpicker''' instead of ''admin_setting_configtext''. The arguments are nearly identical as well except that there is an extra argument to which we give the '''$previewconfig''' variable.

And that is it! it is all you need to get the colour picker up and running.

'''Extra note:''' The $previewconfig variable is optional. If you don't want a preview button the simply set ''$previewconfig = null''

==Common pitfalls and useful notes==

This section is really just a collection of pointers, tips, notes, and other short useful stuff that may be of use to those attempting this tutorial.

# First up and most importantly there are very few limitations to what you achieve in this fashion.
# If you get stuck or need a hand ask in the forums, there's always someone round who can help.
# If you do something really cool let us know, I know everyone in the community loves finding our what others are achieving.
# You don't have to use ''admin_settingpage'' you can also use '''admin_externalpage''' if you prefer. It should be noted however that it is not the preferred way to do it as admin_externalpage's were only left in Moodle 2.0 for backwards compatibility (although they are more flexible one day they will be deprecated or removed). Thank you to Darryl for raising this.
# If you find that your language strings aren't being used (you are getting language string notices) and you have double checked that you have turned '''langstringcache''' off then you may need to delete the language cache directory. This is located in the moodledata directory for you installation: moodledata/cache/lang/*. You should delete the directory for your chosen language by default ''en''.

==See also==

* [[Adding theme upgrade code]]
* [[Styling and customising the dock]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=152053 Theme 2.0: Adding a settings page to your theme] forum discussion

Creating a theme settings page

2014-09-24T21:55:29Z

Tqr: /* Creating the settings page */ - updating to current methods

{{Template:Themes}}This document looks at how to create a settings page for your Moodle 2.x.x theme and how to make use of those settings within the CSS and layout files for your theme.

This is a pretty advanced topic and will require that you have at least an intermediate knowledge of PHP, CSS, and development in general.

==Before we begin==
[[Image:Theme.settings.page.03.png|350px|thumb|Our end goal. The settings page.]]
[[Image:Theme.settings.page.10.png|350px|thumb|And what it can do.]]
There is a huge body of knowledge that we must cover in following through this document and as such I think the best way to write this is as a tutorial.

My intentions for this tutorial are to replicate the standard theme but with a settings page that allows the administrator to set a background colour, set a logo to use with the page, and probably several other minor settings to change the way in which the theme is displayed.

I will start this tutorial by creating a new theme which will be largely a copy/paste of the current standard theme. I expect that anyone working through this tutorial has previously read the tutorial I wrote on [[Themes 2.0 creating your first theme|creating your first theme]]. If you haven't go read it now because I'm not going to go into much detail until we get to the actual process of customising the theme and introducing the settings page.

So before we finally get this started please ensure you can check off everything on the following requirements list.
* Have a Moodle installation that has already been installed and configured and is ready to use.
* Have full read/write access to that installation.
* Be prepared to delete that installation at the end of this... we will destroy it!
* Have a development environment prepared and ready to use. This includes:
** Your favourite editor installed, running, and pointed at the themes directory of your installation.
** Your browser open and your site visible.
** A bottomless coffee pot... decaf won't help you with this one.
* Have set the following settings:
** '''themedesignermode''' if you don't know what this is please read the [[Themes 2.0 creating your first theme|creating your first theme]] tutorial.
** '''allowthemechangeonurl''' turn this on, it allows you to change themes on the URL and is very handy when developing themes. ''Site Administration > Appearance > Themes > Theme settings''
** '''langstringcache''' if you don't turn this off you won't see your strings when they are added. ''Site Administration > Language > Language settings''
* And finally an insane ambition to create a customisable theme.

For those interested the theme that I create throughout this tutorial can be downloaded from the forum post in which I announce this document: http://moodle.org/mod/forum/discuss.php?d=152053
<br style="clear:right;" />

==Our goals for this tutorial==
The following is just a list goals that I hope to achieve during this tutorial. They are laid out here so that I can easily refer back to them and so that you can easily find them.
# Create a new theme called '''demystified''' based upon the standard theme within Moodle 2.0.
# Make some minor changes to that theme to allow us to more easily see what is going on.
# Create a settings page for the demystified theme.
# Add several settings to our settings page.
# Use some of those settings to alter our CSS.
# Use the rest of those settings within our layout file..
# Discuss the good, the bad, and limits of what we have just created.

So I can see you are all very excited about this point and that you would love to know what settings we are going to create; So here they are:

A setting to ...
* change the background colour (CSS).
* set the path to an image that we will use as a logo on all pages (Layout files).
* override the width of the block regions (CSS).
* allow a note to be added to the footer of all pages (Layout files).
* allow custom CSS to be written to do anything the user wants. (CSS)

==Creating the demystified theme==
Before we start here I want to remind you that I am going to look at this only briefly as I am making the assumption that you have read the [[Themes 2.0 creating your first theme|creating your first theme]] tutorial.

Well lets get into it....

The first thing we need to do is create a directory for our theme which we will call demystified.

So within your Moodle directory create the following folder '''moodle/theme/demystified'''. At the same time you can also create the following files and folders which we will get to soon.
* The file '''moodle/theme/demystified/config.php''' for our config information.
* The directory '''moodle/theme/demystified/layout''' for our layout files.
* The directory '''moodle/theme/demystified/style''' for our css files.
* The file '''moodle/theme/demystified/style/core.css''' which will contain our special CSS.

Next we will copy the layout files from the base theme to our new theme demystified. We are basing the demystified theme on the standard theme however that doesn't use it's own layout files it uses the base theme's layout files so those are the ones we want.

The reason that we are coping these layout files is that later on in this tutorial we will be modifying them to make use of our new settings... so copy all of the layout files from '''moodle/theme/base/layout''' to '''moodle/theme/demystified/layout'''.

There should be three files that you just copied:
# embedded.php
# frontpage.php
# general.php

Now we need to populate demystified/config.php with the settings for our new theme. They are as follows:
<code php>
$THEME->name = 'demystified';
</code>
Simply sets the name of our theme.

<code php>
$THEME->parents = array('standard','base');
</code>
This theme is extending both the standard theme and the base theme. Remember when extending a theme you also need to extend its parents or things might not work correctly.

<code php>
$THEME->sheets = array('core');
</code>
This tells our theme that we want to use the file '''demystified/style/core.css''' with this theme.

<div style="height:300px;overflow-y:scroll;">
<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-post',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'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),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>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),
),
// 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),
),
);
</code>
</div>
Now that all looks very complicated however its really not too bad as it is just copied from the base theme's config.php file. We can do this because we copied the layout files from the base theme to begin with and for the time being there are no changes that we wish to make. Simply open up '''theme/base/config.php''' and copy the layouts from there.

And that is it. The config.php file for our demystified theme is complete. The full source is shown below:
<div style="height:300px;overflow-y:scroll;">
<code php>
<?php

// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* The demystified theme config file
*
* This theme was created to document the process of adding a settings page to a theme
*
* @copyright 2010 Sam Hemelryk
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

// The name of our theme
$THEME->name = 'demystified';

// The other themes this theme extends
$THEME->parents = array('standard','base');

// The CSS files this theme uses (located in the style directory)
$THEME->sheets = array('core');

// The layout definitions for this theme
$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-post',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// 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-post',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'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),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>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),
),
// 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),
),
);
</code>
</div>

The screenshot below shows both the directory structure we have now created and the theme presently.

[[Image:Theme.settings.page.01.png]]

To view the theme so far open you browser and enter the URL of your site followed by '''?theme=demystified'''. You should see the theme that we just created which will look exactly like the base standard theme.

The final thing that we want to do is add a little bit of CSS to the demystified theme that will both visually set this theme apart from the standard theme and second build a the base which our settings can later extend.

I added the following snippet of CSS to the file '''demystified/style/core.css'''.
<code css>
html {background-color:#DDD;}
body {margin:30px;padding:0;border:1px solid #333;border-width:0 10px 0 10px;background-color:#333;}
body #page {background-color:#FFF;position:relative;top:-10px;}
.block .header {background-image:none;background-color:#0C5CAC;border:1px solid #0C5CAC;color:#FFF;}
.block {border-color:#4BA7FF;background-color:#DDEEFF;}
.block .content {background-color:#F1F8FF;}
a:link,
a:visited {color:#0C5CAC;}
a:hover {color:#C77500;}
#page #page-header {background-color:#0C5CAC;margin:0;padding:0;width:100%;color:#fff;}
#page #page-header a:link, #page #page-header a:visited {color:#FFAC02}
#page #page-header .navbar, #page #page-header .navbar a:link, #page #page-header .navbar a:visited {color:#0C5CAC;}
</code>

The CSS that we have just added to our theme sets a couple of colours on the front page. Presently this is the only CSS I will add, I know it isn't complete by any means but it achieves it's purpose as the screenshot below illustrates.

[[Image:Theme.settings.page.02.png|715px|thumb|left|The newly styles demystified theme]]<br style="clear:both;" />

And with that I will move on to the real purpose of this tutorial, creating the settings page

==Setting up the settings page==
With the demystified theme set up it is time to create the settings page. This is where the real PHP fun begins.

For those of you who happen to be familiar with development of modules, blocks or other plugin types you have probably encountered settings pages before and this is not going to be any different.

However for those who haven't which I imagine is most of you this is going to be quite a challenge. I will try to walk through this step by step however if at any point you get stuck don't hesitate to ask in the forums as I imagine you will get a speedy response.

===How settings pages work in Moodle===
Settings pages can be used by nearly every plugin type, of which themes is of course one. The way in which it all works isn't too tricky to understand.

All of the settings for Moodle can be configured through the administrator interfaces when logged in. I am sure that everyone here has seen those pages and has changed a setting or two before so you will all know what I am talking about. Well the settings page for a theme is no different. It will be shown in the administration pages tree under '''Appearance > Themes''' and all we have to do is tell Moodle what settings there are.

This is done by creating a settings.php file within our theme into which we will add code that tells Moodle about the settings we want to add/use.

When telling Moodle about each setting we are simply creating a new ''admin_setting'' instance of the type we want and the properties we want and then adding it to our settings page.

There is really not much more too it at this level. Things can get very complex very fast so the best thing we can do now is start creating our settings.php file for the demystified theme and see where it leads us.

===Creating the settings page===
So as mentioned before we need a settings.php file which we will create now. To begin with create the file '''theme/demystified/settings.php''' and open it in your favourite editor so its ready to go.

Before we start adding code however lets just remember the settings that we want to create:
* change the background colour (CSS).
* set the path to an image that we will use as a logo on all pages (Layout files).
* override the width of the block regions (CSS).
* allow a note to be added to the footer of all pages (Layout files).
* allow custom CSS to be written to do anything the user wants. (CSS)

Alright.

Now thinking about this the first setting is as basic as it gets, all we need is a text box that the user can type a colour into.

The second is to allow a logo to be used in the header of each page. What we want here is a path but should it be a physical path e.g. C:/path/to/image.png or should it be a web path e.g. <nowiki>http://mysite.com/path/to/image.png</nowiki>?
For the purpose of this tutorial I am going to go with a web path because it is going to be easier to code and will hopefully be a little easier to understand to begin with.

The third setting is a little more complex. For this I want a drop down box with some specific widths that the administrator can select.

The forth and the fifth settings are both pretty straight forward, there we want a textarea into which the user can enter what ever they want and we will do something useful with it.

Now that we have an understanding about the settings we wish to define pull up your editor and lets start coding....

<code php>
<?php

/**
* Settings for the demystified theme
*/
defined('MOODLE_INTERNAL') || die;

if ($ADMIN->fulltree) {
</code>
This is the first bit of code we must enter, the first line is of course just the opening php tag, secondly we have a comment that describes this file, and then we get create a new '''admin_settingspage object'''.

This admin_settingspage object that we have just created is a representation of our settings page and is the what we add our new settings to. When creating it we give it two arguments, first the name of the page which is in this case '''theme_''themename''''' and the title for the page which we get with the get_string method.

At the moment I'm not going to worry about adding the string, we will get to that later once we have defined all of our settings.

====Background colour====

With the page now created lets add our first setting: Background colour.

<code php>
// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$setting = new admin_setting_configtext($name, $title, $description, $default, PARAM_CLEAN, 12);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
Thankfully this isn't as difficult as it initially looks.

The first line of code is creating a variable for the name of the background colour setting. In this case it is '''theme_demystified/backgroundcolor'''.

The name is very important, for the setting to be usable we have to follow a strict naming convention. '''theme_''themename''/''settingname''''' where '''''themename''''' is the name of the theme the setting belongs to and '''''settingname''''' is the name for the setting by which we will use it.

The second line of code creates a variable that contains the title of the setting. This is what the user sees to the right of the setting on the settings page and should be a short description of the setting. Here we are again using the ''get_string'' method so we will need to remember to add that string later on.

The third line of code sets the description. This should describe what the setting does or how it works and again we will use the get_string method.

The fourth line creates a variable that will be used as the default value for the setting. Because this setting is a colour we want an HTML colour to be the default value.

The fifth line is where we put it all together. Here we create a new '''admin_setting_configtext''' object. This object will represent the background colour setting.

When we create it we need to give it 6 different things.
# The name of the setting. In this case we have a variable '''$name'''.
# The title for this setting. We used the variable '''$title'''.
# The description of the setting '''$description'''.
# The default value for the setting. '''$default''' is the variable this.
# The type of value we want the user to enter. For this we have used PARAM_CLEAN which tells Moodle to get rid of any nasties from what the user enters.
# The size of the field. In our case 12 characters will be plenty.

The sixth and final line of code adds our newly created setting to the administration page we created earlier.

That is it we have successfully created and added our first setting, however there are several more to settings to do, and there are a couple of important things that you need to be aware of before we move on.

First: There are several different types of settings that you can create and add to a page, and each one may differ in what they need you to give them. In this case it was name, title, description, default, type, and size. However other settings will likely require different things. Smart editors like Netbeans or Eclipse can tell you what is required, otherwise you will need to research it.

Second: Normally settings are declared on one line as follows:
<code php>
$setting->add(new admin_setting_configtext('theme_demystified/backgroundcolor', get_string('backgroundcolor','theme_demystified'), get_string('backgroundcolordesc', 'theme_demystified'), '#DDD', PARAM_CLEAN, 12));
</code>
While this is structurally identical as all we have done is move everything onto one line and do away with the variables it is a little harder to read when you are learning all of this.

====The logo file====
Time to create the second setting that will allow the user to enter a URL to an image they wish to use as the logo on their site.
<code php>
// Logo file setting
$name = 'theme_demystified/logo';
$title = get_string('logo','theme_demystified');
$description = get_string('logodesc', 'theme_demystified');
$setting = new admin_setting_configtext($name, $title, $description, '', PARAM_URL);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
The first thing that you will notice about this setting that it is very similar to the first setting, in fact all we have changed is the name, title, description, and default value. We have however changed the value type from PARAM_CLEAN to PARAM_URL, this makes sure the user enters a URL. You will also notice that for this one we don't set a size for the field as we have no idea how long the URL will be.

====Block region width====
The third setting should allow the user to set a width for the block regions that will be used as columns.

For this setting I want to do something a little different from the previous two, here I want to use a select box so that the user selects a width for the column from a list I provide.
<code php>
// Block region width
$name = 'theme_demystified/regionwidth';
$title = get_string('regionwidth','theme_demystified');
$description = get_string('regionwidthdesc', 'theme_demystified');
$default = 200;
$choices = array(150=>'150px', 170=>'170px', 200=>'200px', 240=>'240px', 290=>'290px', 350=>'350px', 420=>'420px');
$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$setting->set_updatedcallback('theme_reset_all_caches');
$settings->add($setting);
</code>
So looking at the code: The first four lines you will recognise. $name, $title, $description, and $default are all being set.

The fifth line of code however introduces something new. Of course in order to have a select box we have to have options, in this case we have an array of options stored in the variable $choices.

The array of options is constructed of a collection of '''''value''' => '''label''''' pairs. Notice how we don't add '''px''' to the value. This is is very intentional as later on I need to do a little bit of math with that value so we need it to be a number.

The lines after should look familiar again, the only difference being that instead of a ''admin_setting_configtext'' setting we have created a ''admin_setting_configselect'' for which we must give the choices for the select box as the fifth argument.

Woohoo, we've just created our first select box setting.

====Foot note====
Now to create the foot note setting. Here we want the user to be able to enter some arbitrary text that will be used in the footer of the page. For this I want the user to be able to enter some HTML so I will create an editor setting.
<code php>
// Foot note setting
$name = 'theme_demystified/footnote';
$title = get_string('footnote','theme_demystified');
$description = get_string('footnotedesc', 'theme_demystified');
$setting = new admin_setting_confightmleditor($name, $title, $description, '');
$temp->add($setting);
</code>
How simple is that!

It is just about identical to the first two settings except that for this we have created a ''admin_setting_confightmleditor'' setting rather than a text setting.

Note: You can also set the columns and rows for the editor setting using the fifth and sixth arguments.

====Custom CSS====
The final setting is to allow the user to add some custom CSS to the theme that will be used on every page. I want this to be a plain textarea into which the user can enter CSS.
<code php>
// Custom CSS file
$name = 'theme_demystified/customcss';
$title = get_string('customcss','theme_demystified');
$description = get_string('customcssdesc', 'theme_demystified');
$setting = new admin_setting_configtextarea($name, $title, $description, '');
$temp->add($setting);
</code>
Just like the editor or text settings. It's getting very easy now!

====Finishing settings.php====
With all of our settings defined and added to our page that we created right at the beginning it is time to finish it all off.
<code php>
// Add our page to the structure of the admin tree
$ADMIN->add('themes', $temp);
</code>
The above line of code is the final line for the page. It is adding the page that we have created '''$temp''' to the admin tree structure. In this case it is adding it to the themes branch.

The following is the completed source for our settings.php ..... for your copy/paste pleasure.
<div style='height:300px;overflow:auto;'>
<code php>
<?php

/**
* Settings for the demystified theme
*/

// Create our admin page
$temp = new admin_settingpage('theme_demystified', get_string('configtitle','theme_demystified'));

// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$setting = new admin_setting_configtext($name, $title, $description, $default, PARAM_CLEAN, 12);
$temp->add($setting);

// Logo file setting
$name = 'theme_demystified/logo';
$title = get_string('logo','theme_demystified');
$description = get_string('logodesc', 'theme_demystified');
$setting = new admin_setting_configtext($name, $title, $description, '', PARAM_URL);
$temp->add($setting);

// Block region width
$name = 'theme_demystified/regionwidth';
$title = get_string('regionwidth','theme_demystified');
$description = get_string('regionwidthdesc', 'theme_demystified');
$default = 200;
$choices = array(150=>'150px', 170=>'170px', 200=>'200px', 240=>'240px', 290=>'290px', 350=>'350px', 420=>'420px');
$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$temp->add($setting);

// Foot note setting
$name = 'theme_demystified/footnote';
$title = get_string('footnote','theme_demystified');
$description = get_string('footnotedesc', 'theme_demystified');
$setting = new admin_setting_confightmleditor($name, $title, $description, '');
$temp->add($setting);

// Custom CSS file
$name = 'theme_demystified/customcss';
$title = get_string('customcss','theme_demystified');
$description = get_string('customcssdesc', 'theme_demystified');
$setting = new admin_setting_configtextarea($name, $title, $description, '');
$temp->add($setting);

// Add our page to the structure of the admin tree
$ADMIN->add('themes', $temp);
</code>
</div>

===Creating a language file and adding our strings===
As I'm sure none of you have forgotten, throughout the creation of the our settings.php page, we used a lot of strings that I mentioned we would set later on. Well now is the time to set those strings.

First up create the following directories and file for our language strings:
* Directory '''theme/demystified/lang'''
* Directory '''theme/demystified/lang/en'''
* File '''theme/demystified/lang/theme_demystified.php'''

What we have created here is the required structure for Moodle to start looking for language strings.

First Moodle locates the lang directory, once found it looks within that directory for another directory that uses the character code for the language the user has selected, by default this is '''en''' for English. Once that is found it looks for the appropriate language file, in this case '''theme_demystified.php''' from which it will load all language strings for our theme.

If English isn't your chosen language simply replace the ''en'' directory with one that uses your chosen languages character code (two letters).

We can now add our language strings to '''theme/demystified/lang/theme_demystified.php'''. Copy and paste the following lines of PHP into this file.
<code php>
<?php

/**
* This file contains the strings used by the demystified theme
*/

$string['backgroundcolor'] = 'Background colour';
$string['backgroundcolordesc'] = 'This sets the background colour for the theme.';
$string['configtitle'] = 'Demystified theme';
$string['customcss'] = 'Custom CSS';
$string['customcssdesc'] = 'Any CSS you enter here will be added to every page allowing your to easily customise this theme.';
$string['footnote'] = 'Footnote';
$string['footnotedesc'] = 'The content from this textarea will be displayed in the footer of every page.';
$string['logo'] = 'Logo';
$string['logodesc'] = 'Enter the URL to an image to use as the logo for this site. Should be http://www.yoursite.com/path/to/logo.png';
$string['pluginname'] = 'Demystified';
$string['regionwidth'] = 'Column width';
$string['regionwidthdesc'] = 'This sets the width of the two block regions that form the left and right columns.';
</code>

In the above lines of code I have added an entry for each language string we used within ''settings.php''. When adding language strings like this make sure you use single quotes and try to keep things alphabetical - it helps greatly when managing strings.

Now when we view the settings page there will not be any errors or strings missing.

===Having a look at what we have created===
Now that we have created our settings page (settings.php) and added all of the language strings it is time to have a look at things in your browser.

Open your browser and enter the URL to your site. When you arrive at your site login as an administrator.

If you are not redirected to view the new settings change your URL to <nowiki>http://www.yoursite.com/admin/</nowiki> and your will see a screen to set the new theme settings we have just created. This lets us know that everything has worked correctly.

At any point now you are able to log in as administrator and within the settings block browse to '''Site administration > Appearance > Themes > Demystified theme''' to change those settings.

The screenshot below shows you what you should see at this point:

[[Image:Theme.settings.page.03.png|715px|thumb|left|The settings page we just created]]
<br style="clear:both;" />

==Using the settings in CSS==
With the settings page now created and operational it is time to make use of our new settings. The settings that we want to use within our CSS is as follows:

; backgroundcolor : Will be used to set the background colour in CSS.
; regionwidth : Will be the width of the column for CSS.
; customcss : Will be some custom CSS to add to our stylesheet.

At this point those names are the names we used for our setting with the slash and everything before it having been removed.

Before we start tearing into some code it is important that we have a look at what we are going to do and how we are going to go about it.

===How it all works within Moodle===
The first thing to understand is that while Moodle allows you to create a settings page and automates it inclusion and management right into the administration interfaces there is no smart equivalent for using the settings. This is simply because there is no way to predict how people will want to use the settings.

However don't think of this as a disadvantage, in fact it is quite the contrary. Although we can't just ''use'' our settings we can take full control over how and where we use them. It means it will take a little more code but in the end that will work to our advantage as we can do anything we want.

Moodle does help us out a little but not in an obvious way. The first thing that Moodle does is look for a config variable '''csspostprocess''' that should be the name of a function which we want called to make any changes to the CSS after it has been prepared.

The second thing Moodle does is include a lib.php from the theme's directory if one exists (also for the themes the current theme extends.) which ensures that as long as we write our code within '''theme/demystified/lib.php''' it will be included and ready to be used.

The third and final thing Moodle does that will help us out here is ensure that by the time any of code is ready to execute the settings have been prepared and are ready to be used within a theme config object which is passed into our ''csspostprocess'' function.

===Our plan===
As you have already probably guessed we will need to create a function to make the changes to the CSS that we want. We will then set the theme config option '''$THEME->csspostprocess''' to the name of our function.

By doing this when Moodle builds the CSS file it will call our function afterwards with the CSS and the theme object that contains our setting.

Now we know that we will use the ''csspostprocess'' function but how are we going to change the CSS, we could get the function to add CSS, or we could get the function to replace something within the CSS. My personal preference is to replace something within the CSS, just like what is happening with images. If you want to use an image within CSS you would write <nowiki>[[pix:theme|imagename]]</nowiki>.

For settings I am going to use <nowiki>[[setting:settingname]]</nowiki>, this way it looks a bit like something you are already familiar with.

What we need to decide upon next is the best way in which to replace our settings tag with the settings that the user has set.

There are two immediate options available to us:
# Make the ''csspostprocess'' function do all the work.
# Make the ''csspostprocess'' function call a separate function for each setting.
Solution 1 might sound like the simplest however it is going to result in a '''VERY''' complex function. Remember the user might have left settings blank or entered something that wouldn't be valid so we would need to make the sure there is some validation and a good default.
Because of this I think that solution 2 is the better solution.

So we are going to need a ''csspostprocess'' function and then a function for each of the three settings we have that will do the replacements.
<code php>
// This is our css post process function
function demystified_process_css($css, $theme) {};
// This replaces [[setting:backgroundcolor]] with the background colour
function demystified_set_backgroundcolor($css, $backgroundcolor) {};
// This replaces [[setting:regionwidth]] with the correct region width
function demystified_set_regionwidth() {$css, $regionwidth};
// This replaces [[setting:customcss]] with the custom css
function demystified_set_customcss() {$css, $customcss};
</code>

What you should note about the above functions is that they all start with the theme's name. This is required to ensure that the functions are named uniquely as it is VERY unlikely that someone has already created these functions.

So with our plan set out lets start writing the code.

===Writing the code===
The very first thing that we need to do is create a lib.php for our theme into which our css processing functions are going to go. So please at this point create '''theme/demystified/lib.php''' and open it in your editor ready to go.

The first bit of code we have to write is the function that will be called by Moodle to do the processing '''demystified_process_css'''.

Before we start out please remember that the wonderful thing about coding is that there is any number of solutions to a problem. The solutions that you are seeing here in this tutorial are solutions that I have come up with to meet fulfil the needs of the tutorial without being so complex that they are hard to understand. This probably isn't how I would go about it normally but this is a little easier to understand for those who aren't overly familiar with PHP and object orientation.

====The function: demystified_process_css====

<code php>
function demystified_process_css($css, $theme) {

if (!empty($theme->settings->backgroundcolor)) {
$backgroundcolor = $theme->settings->backgroundcolor;
} else {
$backgroundcolor = null;
}
$css = demystified_set_backgroundcolor($css, $backgroundcolor);

if (!empty($theme->settings->regionwidth)) {
$regionwidth = $theme->settings->regionwidth;
} else {
$regionwidth = null;
}
$css = demystified_set_regionwidth($css, $regionwidth);

if (!empty($theme->settings->customcss)) {
$customcss = $theme->settings->customcss;
} else {
$customcss = null;
}
$css = demystified_set_customcss($css, $customcss);

return $css;
}
</code>

So lets look at the things that make up this function:

<code php>
function demystified_process_css($css, $theme) {
//.....
return $css
}
</code>

This of course is the function declaration.

The function gets given two variables, the first '''$css''' is a pile of CSS as one big string, and the second is the theme object '''$theme''' that contains all of the configuration, options, and settings for our theme.

It then returns the ''$css'' variable, essentially returning the modified CSS.

<code php>
//...
if (!empty($theme->settings->backgroundcolor)) {
$backgroundcolor = $theme->settings->backgroundcolor;
} else {
$backgroundcolor = null;
}
$css = demystified_set_backgroundcolor($css, $backgroundcolor);
//...
</code>

Here we are processing our first setting ''backgroundcolor''.

The first thing that we need to do is check whether it has been set and whether it has a value. If it has then we store that value in '''$backgroundcolor'''. It is doesn't have a value then we set ''$backgroundcolor'' to null. This ensures that ''$backgroundcolor'' is set because if it isn't then you are going to get a notice (if you have debugging on).

The final line of this block calls the function '''demystified_set_backgroundcolor'''. We haven't written this function yet but we will shortly. When we call it we give it the ''$css'' variable that contains all of the CSS and we give it the background colour variable ''$backgroundcolor''. Once this function is finished it returns the ''$css'' variable with all of the changes made much like how our css processing function works.

What you should also note about this code is this:
<code php>
$theme->settings->backgroundcolor
</code>
As mentioned earlier ''$theme'' is an object that contains all of the configuration and settings for our theme. The ''$theme'' object has a $settings property which contains all of the settings for our theme, and finally the settings property contains a variable backgroundcolor that is the value the user entered for that setting. That is how we get a settings value.

<code php>
if (!empty($theme->settings->regionwidth)) {
$regionwidth = $theme->settings->regionwidth;
} else {
$regionwidth = null;
}
$css = demystified_set_regionwidth($css, $regionwidth);

if (!empty($theme->settings->customcss)) {
$customcss = $theme->settings->customcss;
} else {
$customcss = null;
}
$css = demystified_set_customcss($css, $customcss);
</code>

These two routines are nearly identical to the routine above. For both the regionwidth and the customcss we make sure it has a value and then store it in a variable. We then call the relevant function to make the changes for that setting.

Now that we have the general processing function it is time to write the three functions we have used but not written, ''demystified_set_backgroundcolor'', ''demystified_set_regionwidth'', ''demystified_set_customcss''.

====The function: demystified_set_backgroundcolor====

First up demystified_set_backgroundcolor.

<code php>
/**
* Sets the background colour variable in CSS
*
* @param string $css
* @param mixed $backgroundcolor
* @return string
*/
function demystified_set_backgroundcolor($css, $backgroundcolor) {
$tag = '[[setting:backgroundcolor]]';
$replacement = $backgroundcolor;
if (is_null($replacement)) {
$replacement = '#DDDDDD';
}
$css = str_replace($tag, $replacement, $css);
return $css;
}
</code>

Ok so what is happening here?

First we need a variable '''$tag''' that contains the tag we are going to replace. As mentioned earlier we are going to use tags that look like the image tags you are already familiar with ''<nowiki>[[setting:settingname]]</nowiki>'', in this case ''<nowiki>[[setting:backgroundcolor]]</nowiki>''.

Next I am going to create a variable called '''$replacement''' into which I put '''$backgroundcolor'''.

The '''IF''' statement that comes next checks ''$replacement'' to make sure it is not null. If it is then we need to set it to a default value. In this case I have used ''#DDD'' as that was the default for the settings.

The line after the IF statement puts it all together. The ''str_replace'' function that we are calling takes three arguments in this order:
# The text to search for.
# The text to replace it with.
# The text to do the replacement in.
It then returns the text with all of the replacements made. So in this case we are replacing the tag with the background colour and it is returning the changed CSS.

The final thing is to return the ''$css'' variable which now contains the correct background colour.

====The function: demystified_set_regionwidth====

Next we have the demystified_set_regionwidth function.
<code php>
/**
* Sets the region width variable in CSS
*
* @param string $css
* @param mixed $regionwidth
* @return string
*/
function demystified_set_regionwidth($css, $regionwidth) {
$tag = '[[setting:regionwidth]]';
$doubletag = '[[setting:regionwidthdouble]]';
$replacement = $regionwidth;
if (is_null($replacement)) {
$replacement = 200;
}
$css = str_replace($tag, $replacement.'px', $css);
$css = str_replace($doubletag, ($replacement*2).'px', $css);
return $css;
}
</code>

This function is very similar to the above function however there is one key thing we are doing different. We are doing two replacements.

# The first replacement is for the width that the user selected. In this case I am replacing the tag ''<nowiki>[[setting:regionwidth]]</nowiki>'' with the width.
# The second replacement is for the width x 2. This is because the page layout requires that the width be doubled for some of the CSS. Here I will replace ''<nowiki>[[setting:regionwidthdouble]]</nowiki>'' with the doubled width.

Remember because it is still just a number we need to add '''px''' to the end of each before we do the replacement.

So the overall process of this function is:
# Define the two tags as '''$tag''' and '''$doubletag'''.
# Make '''$replacement''' the region width ''$regionwidth''.
# Set ''$replacement'' to a default value of 200 is it is null.
# Replace '''<nowiki>[[setting:regionwidth]]</nowiki>''' with the width.
# Replace '''<nowiki>[[setting:regionwidthdouble]]</nowiki>''' with the width x 2.
# Return the changed CSS.

====The function: demystified_set_customcss====

The final function that we need to write is the demystified_set_customcss function.
<code php>
/**
* Sets the custom css variable in CSS
*
* @param string $css
* @param mixed $customcss
* @return string
*/
function demystified_set_customcss($css, $customcss) {
$tag = '[[setting:customcss]]';
$replacement = $customcss;
if (is_null($replacement)) {
$replacement = '';
}
$css = str_replace($tag, $replacement, $css);
return $css;
}
</code>

This function is just like the first function. I'm going to let you work it out on your own.

And that is it no more PHP... Hallelujah I can hear you yelling. The final thing we need to do is tell our theme about the functions we have written and put the settings tags into the CSS.

===Finishing it all off===

So there are two things we have to do in order to complete this section and have our the settings page implemented and our settings being used.

First we need to tell our theme that we want to use the function ''demystified_process_css'' as the ''csspostprocess'' function. This is done very simply by adding the following line of PHP to the bottom of our theme's config.php file '''theme/demystified/config.php'''.

<code php>
$THEME->csspostprocess = 'demystified_process_css';
</code>

With that done the only thing left is to add the settings tag into the CSS. Remember those settings tags are:

; <nowiki>[[setting:backgroundcolor]]</nowiki> : We need to add this where ever we want the background colour setting to be used.
; <nowiki>[[setting:regionwidth]]</nowiki> : We need to add this where ever we want to set the width of the block regions.
; <nowiki>[[setting:regionwidthdouble]]</nowiki> : We need to add this where ever we want to set the doubled width of the block regions.
; <nowiki>[[setting:customcss]]</nowiki> : We need to add this to the bottom of the CSS file that we want the custom CSS added to.

So lets make those changes in CSS now, open up your ''core.css'' file and replace the CSS with the CSS below:
<code css>
/** Background color is a setting **/
html {background-color:[[setting:backgroundcolor]];}
body {margin:30px;padding:0;border:1px solid #333;border-width:0 10px 0 10px;background-color:#333;}
body #page {background-color:#FFF;position:relative;top:-10px;}
.block .header {background-image:none;background-color:#0C5CAC;border:1px solid #0C5CAC;color:#FFF;}
.block {border-color:#4BA7FF;background-color:#DDEEFF;}
.block .content {background-color:#F1F8FF;}
a:link,
a:visited {color:#0C5CAC;}
a:hover {color:#C77500;}
#page #page-header {background-color:#0C5CAC;margin:0;padding:0;width:100%;color:#fff;}
#page #page-header a:link, #page #page-header a:visited {color:#FFAC02}
#page #page-header .navbar, #page #page-header .navbar a:link, #page #page-header .navbar a:visited {color:#0C5CAC;}
/** Override the region width **/
#page-content #region-main-box {left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidthdouble]];}
#page-content #region-main-box #region-post-box #region-pre {width:[[setting:regionwidth]];left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-post {width:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidthdouble]];}
.side-pre-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-pre-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
/** Custom CSS **/
[[setting:customcss]]
</code>

You will notice that <nowiki>[[setting:backgroundcolor]]</nowiki> has been used for the html tags background colour:
<code css>
html {background-color:[[setting:backgroundcolor]];}
</code>

We have also set the width of the block regions by adding <nowiki>[[setting:regionwidth]]</nowiki> as the width for region-pre and region-post as shown below:
<code css>
#page-content #region-main-box {left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidthdouble]];}
#page-content #region-main-box #region-post-box #region-pre {width:[[setting:regionwidth]];left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-post {width:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidthdouble]];}
.side-pre-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-pre-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
</code>
You'll notice here that we have to set several different widths and margins using the regionwidth setting and make use of the special regionwidthdouble setting that we added.

The final thing that we did was add the <nowiki>[[setting:customcss]]</nowiki> to the bottom of the file to ensure that the custom CSS comes last (and therefore can override all other CSS).

And with that we are finished. The screenshot below shows how this now looks in the browser if I set the background colour setting to '''<span style='color:#FFA800;'>#FFA800</span>''' and made the column width 240px;

[[Image:Theme.settings.page.04.png|715px|thumb|left|Our settings in action]]<br style="clear:both;" />

==Using the settings within our layout files==
Now that we have utilised the first three settings within our theme's CSS file it is time to implement the other two settings within the layout files so that they are written directly into the page.

You'll be glad to know this is no where near as difficult as utilising settings within a CSS file although it still does require a little bit of PHP.

First up is the logo setting. Into this setting the user is able to enter the URL to an image to use as the logo for the site. In my case I want this to be just a background logo on top of which I want to position the page header.

Before I start there is one thing I need to do however and that is create a default logo background that gets shown if the user hasn't set a specific logo file. To do this I simply created an image '''logo.jpg''' and put it into a pix directory within the demystified theme. You should end up with '''theme/demystified/pix/logo.jpg'''.

Next open up the front-page layout file ''theme/demystified/layout/frontpage.php''. At the top of the file is the PHP that checks what blocks regions the page has and a bit of other stuff. Well right below the existing bit of PHP we want to add the following code:
<code php>
if (!empty($PAGE->theme->settings->logo)) {
$logourl = $PAGE->theme->settings->logo;
} else {
$logourl = $OUTPUT->pix_url('logo', 'theme');
}
</code>
What we are doing here is creating a variable called $logourl that will contain the URL to a logo file that was either entered by the user or if they left it blank is that of our default logo file.

There are two things that you should notice about this. First the logo setting can be retrieved through '''$PAGE->theme->settings->logo''' and second we get the default logo url by calling '''$OUTPUT->pix_url('logo', 'theme')'''.

Now that we have the logo URL we are going to use we need to add an image to the header section of the page as shown below:
<code php>
<div id="page-header" class="clearfix">
<img class="sitelogo" src="<?php echo $logourl;?>" alt="Custom logo here" />
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
....
</code>

If you save that and browse to your sites front page you will notice that the logo file is now being shown. Hooray. However it is probably not styled too nicely so lets quickly fix that. Open up the core.css file and add the following lines of CSS to the bottom of the file.
<code css>
#page-header {position:relative;min-height:100px;}
#page-header .sitelogo {float:left;}
#page-header .headermain {position:absolute;left:0.5em;top:50px;margin:0;float:none;font-size:40px;}
</code>
These three lines position the image correctly and if you now refresh everything should appear perfectly.

With the logo done the last setting we need to deal with is the footnote setting. The idea with this setting was that the administrator could enter some text into the editor and it would be displayed in the footer of the page.

This is probably the easiest setting to implement.

Within the front page layout file that we edited above add the following lines below those we added previously.

<code php>
if (!empty($PAGE->theme->settings->footnote)) {
$footnote = $PAGE->theme->settings->footnote;
} else {
$footnote = '';
}
</code>

Here we are just collecting the footnote into a variable '''$footnote''' and setting a default footnote comment if the user hasn't entered one.

We can now echo the $footnote variable within the page footer. This can be done as shown below.

<code php>

<div id="page-footer">
<div class="footnote"><?php echo $footnote; ?></div>
<p class="helplink">
<?php echo page_doc_link(get_string('moodledocslink')) ?>
</p>
</code>

And with that done we are finished! Congratulations if you got this far.

The screenshot below shows the demystified theme we have just created that is styled by the settings page.

[[Image:Theme.settings.page.05.png|715px|thumb|left|My finished demystified theme]]<br style="clear:both" />

==Testing our creation==
Congratulations to you! If you've made it this far you have done very well. Now it is time to have a look at what we have created and give it a quick test run.

So in this tutorial we have achieved the following:

* We created a theme called demystified that is based on the standard theme.
* We added a settings page to our new theme.
* We added the following settings to our settings page:
** We can set a background colour through the admin interface.
** We can change the logo of the site.
** We can change the block region width.
** We can add a footnote to the page footer
** We can add some custom CSS to seal the deal.
* Those settings were then used in the CSS files for our theme.
* They were also used in the layout files for our theme.
* And here we are testing it all.

The screenshots below show my testing process and I change each setting and view the outcome. The great thing about this is that with theme designer mode on you see the changes as soon as the form refreshes.

[[Image:Theme.settings.page.06.png|300px|thumb|left|Default settings]]
[[Image:Theme.settings.page.07.png|300px|thumb|left|Changed the background colour setting]]
[[Image:Theme.settings.page.08.png|300px|thumb|left|Changed the logo and region width]]
[[Image:Theme.settings.page.09.png|300px|thumb|left|Added a footnote]]
[[Image:Theme.settings.page.10.png|300px|thumb|left|Added some custom CSS]]
<br style="clear:both" />

==The different settings you can use==
During this tutorial we use four different kinds of settings, a text box, text area, a select (dropdown) and the editor however as I'm sure you have all guessed there is many more some of which will certainly be useful for theme settings.

The following are examples of some of the different settings. I should add that these build upon what we have already done within the tutorial but are not included in the download.

===Colour picker===
[[Image:Theme.settings.page.11.png|400px|thumb|The colour picker]]
I can hear you all asking now 'Why didn't you mention this one earlier?' well the answer is simple it didn't exist when I first wrote the tutorial. It is an admin setting that I wrote several days after because of the fantastic effort people were putting into trying out settings pages.

A bit about the colour picker. First up it is a text box that when the page loads turns into a colour picker that can be used to select a colour and can even preview the selected colour in the page (by clicking the preview button). It is designed to be very easy to use and the code is just about as simple as creating a normal text box setting.

In the image to the left I have replaced the background colour setting we created during the tutorial with the colour picker. Lets have a look at the code involved for that.
<code php>
// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$previewconfig = array('selector'=>'html', 'style'=>'backgroundColor');
$setting = new admin_setting_configcolourpicker($name, $title, $description, $default, $previewconfig);
$temp->add($setting);
</code>
So first thing you should notice is that the first four lines of code have not changed at all!

The first change we have is to create a variable '''$previewconfig'''.
This variable is used to tell the colour picker what to do when the user clicks the preview button. It should be an array that contains two things, first a selector, and second a style.
# The selector is a CSS selector like ''.page .header h2''.
# The style is a what should change, there are two immediate values it can be, either '''backgroundColor''' or '''color'''.
In my case the selector is '''html''' to target the html tag and the style is backgroundColor to change the background colour.

The second change is to use '''admin_setting_configcolourpicker''' instead of ''admin_setting_configtext''. The arguments are nearly identical as well except that there is an extra argument to which we give the '''$previewconfig''' variable.

And that is it! it is all you need to get the colour picker up and running.

'''Extra note:''' The $previewconfig variable is optional. If you don't want a preview button the simply set ''$previewconfig = null''

==Common pitfalls and useful notes==

This section is really just a collection of pointers, tips, notes, and other short useful stuff that may be of use to those attempting this tutorial.

# First up and most importantly there are very few limitations to what you achieve in this fashion.
# If you get stuck or need a hand ask in the forums, there's always someone round who can help.
# If you do something really cool let us know, I know everyone in the community loves finding our what others are achieving.
# You don't have to use ''admin_settingpage'' you can also use '''admin_externalpage''' if you prefer. It should be noted however that it is not the preferred way to do it as admin_externalpage's were only left in Moodle 2.0 for backwards compatibility (although they are more flexible one day they will be deprecated or removed). Thank you to Darryl for raising this.
# If you find that your language strings aren't being used (you are getting language string notices) and you have double checked that you have turned '''langstringcache''' off then you may need to delete the language cache directory. This is located in the moodledata directory for you installation: moodledata/cache/lang/*. You should delete the directory for your chosen language by default ''en''.

==See also==

* [[Adding theme upgrade code]]
* [[Styling and customising the dock]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=152053 Theme 2.0: Adding a settings page to your theme] forum discussion

Moodle.org forums help

2014-02-06T11:42:04Z

Tqr: /* Example of new post */

The Moodle Forums are a tremendous resource. For a new user, they can be confusing and overpowering. This page will provide more details to points raised in the [[Forums code of conduct]].

The 3 most important things to remember: Ask your question in the right place, write a good discussion/subject title, include information that will help solve the problem, and enjoy Moodling.
:Ooops, classic writing always has 3 things that are important but enjoying life is right up there for most Moodlers.

==The basics==
=== Ask your question in the right forum===
The first important thing you need to do is find the right forum to ask the question. We recommend the [http://moodle.org/mod/forum/search.php?search=&id=5 Forum search tool] or even the [https://docs.moodle.org/en/Main_Page?search=&go=Go "Search moodle.org" tool] found on most pages in the upper right corner. At least look over the [http://moodle.org/course/view.php?id=5 list of forums] and remember there are [http://moodle.org/course/category.php?id=3 forums in many other languages] besides English or check [[:Category:FAQ|the list of frequently asked questions categories]]

If you really do not know which forum to post in, go to the [http://moodle.org/mod/forum/view.php?id=50 General help forum].

===Write a subject line (discussion topic) that is a one-line summary of your question===

The subject line or a discussion topic is like a advertisement. You want experts who know how to solve your problem to give you the answer. Helpful Moodlers, or those looking for a solution to a problem just like yours, do not always read every post. They do scan the subject lines on a forum. The subject line should let them know what your problem is about.

:''TIP:'' People already know you need help because you took the time to post :)

:For example, you are having trouble locating newly created course topics in your Moodle installation, a subject line like "Help My Moodle is broken!" or "PLEASE HELP ME!!!" is less likely to encourage people to read and answer your question than a subject line like: "Moodle 1.8.4, new course topics missing."

=== Things to include in the content of your post===
Now that you have interested Moodlers opening your post, you can speed up the process that will give you a solution by including information in the initial post. Many times a helpful Moodler will ask you for this information or make a wrong assumption. All this takes time to get the basics. In the best of all possible worlds, you want the solution yesterday, not after 3 or 4 replies that go into next week :)

====Your question should contain====
:''TIP:'' If you don't have all this information, fill in as much as you can.

* The version of Moodle used (or upgraded To or From). ''' Most important information'''
* The server operating system and version [e.g. RedHat Linux 9.1, Mac OS X 1.4, Windows 2000, etc.]
* The web server used [e.g. Apache 1.3.18, Apache 2.0.63, IIS 5, IIS 6, etc]
* The PHP version used [e.g. 4.47, 5.23. 5.25, etc]
* The database used [MySQL 5.0.41, PostgresQL 7.4, Windows Sequel 2000, etc]
* The version of the addin or special feature you are trying to use, if any

*And of course your post should contain your question. See heading below.

====Remember to keep the story simple====
Your question should be more like a (very) short story than a novel. It should be direct and to the point. Like any good report or story, tell what you did leading up to the problem, what the problem looked like and perhaps things you did to try to solve it.

Many problems have happened before and helpful Moodlers will recognize these right away. So try to keep the story simple.

:And remember, helpful Moodlers do understand frustrations, deadlines and what is like to use a program for the first time and/or not have it cooperate. If you must vent, a simple "I am frustrated" is enough detail.

==Good post==
Several helpful Moodlers have suggested examples of a good post.
===Example of new post ===
[[Image:Forum Post Example edit mode2.png|frame|center|New post example. This teacher is also a site administrator, so they know about their Moodle site. The Moodle version is the minimum requirement.]]

===Explanation of Example===
The subject line describes the problem. The poster knows that other versions of Moodle did not have this problem and included it in the subject line.

This question first lists the Moodle version, server operating system, web server software, PHP version and MySQL database version. It might include information about the computer and versions of add-in modules. Some like to put this basic info at the bottom of their post. As we have said before, put what you know.

The short story includes: the events leading up to the problem, the problem itself, and a request for a resource that might help the questioner solve his own problem.
Knowledgeable Moodlers with experience or insight into that particular problem may even offer solutions in lieu of, or in addition to, any available resources that the questioner requested.

===How it looks in a forum list===
[[Image:Forum Post Discussion List.png|center|frame|Help people who know find your problem. We added the NOT and Check icons.]]

'''If you are a volunteer Helpful Moodler with limited time, you will first look at the topics you know something about.''' "Please help me" will not be at the top of that list. In fact the "Please help me!!!" could contain the same content as any of the other 3 discussion threads.

==Editing your message in the Forum==

Sometimes after posting a question in the Forum you may realize that you've omitted some important information, left out a word or phrase, or made some typographical error that needs to be corrected. For the first 30 minutes after you posted your question you can simply click on the Edit link at the lower right side of your message and return to the Moodle editor to make corrections, You can edit both the body of your Forum posting and the Subject line until the time period expires.
== Posting a Follow-up Message ==

===Reply to your own message to update its content===
Replying to your own message is a good way to update information or even suggest an answer to your original question.

Many Forum users read the messages using a "threaded" view. In the "threaded" view messages are grouped according to their Subject line. Each message descends from its parent message according to its date. The oldest messages are at the top of the thread and each reply is nested below the original message. When you reply to your own message and keep the Subject intact, you not only have the opportunity to change or clarify the original question (or other information) that you posted, but you ensure its position in the thread by keeping it directly below your original posting. In that position people are more likely to see your messages, read through the thread and reply to your most recent post. If you change your Subject line, the message will still be available in the threaded view beneath your original post, but that change may make the message's context less obvious and lessen the likelihood that you'll receive a helpful reply.

Forum users who read messages in a "list" view, see messages vertically descending from oldest to newest with replies descending vertically from original messages. Quite often a reader must scroll down the page to follow the replies. These message postings and their replies are not grouped by subject but stacked below the oldest messages. A long scroll down a page can make it difficult to follow a message and its replies; a long scroll down a page to a message with a new subject makes it extremely difficult to follow the context of the original message and (if you can find them) the original message's replies.

===Quote sparingly from your original message===

If you need to highlight inaccurate or incomplete information in your original message, quote just that specific information at the top of your message. There is no need to quote your entire original message.

There are many different ways to quote original content in a reply. We recommend the single "greater-than" sign (the > symbol) at the beginning of each line you are quoting.

:> Why doesn't the screen show the changes I made?

Some people will quote previous message segments by using italics to highlight the quote, but this method (and any method that uses stylized test) may make it difficult for people using an adaptive technology method (screen reader software) to read the message and determine what is a quote from a previous message and what is actually new information.

:''Tip:'' If you have kept your Subject line intact, the original post will still be available in the thread or the message listing.

===Topic creep - recognize when you are asking a new question===
Sometimes one question will naturally lead to another in a reply post. Sometimes it is best to start a new topic and consider if the current forum is the best place to ask the new question. For example, you might ask about different ways to score a muliple choice question in the Lesson forum, but then ask about how questions are scored and graded in a Quiz.

Forum threads can be split and moved to new forums. Some Moodlers will ignore questions when they are off topic or belong in another forum.

==Good manners==
=== Patience is still a Virtue so, please, be virtuous===

If you post a message that needs additional clarification it is likely that there may be some additional delay before the message receives a reply. Forum readers are likely to initially skip questions that are missing important information --it is difficult to provide an accurate answer when the question, itself, is unclear. Please wait at least 48 hours before you post another message on the same subject. Please remember that Forum readers are from all around the world and the time zone differences may delay even immediate responses by 12 to 14 hours.

If you require urgent help, or have a complicated problem, you may wish to consider paid support from a Moodle Partner.

===Try to resist emailing or messaging users directly===

It might be tempting to email the maintainer of the module you have a question about. You are almost always better asking questions in a forum as the audience is much bigger. Remember that Moodle contributors take holidays (sometimes). And some helpful Moodlers like to answer the simple questions, so that those with more technical knowledge have time to answer the tougher questions.

However, do not worry about "clogging" up the forums or asking a stupid question in public. There are so many users in Moodle Land that someone has probably seen a similar issue and your question will help them clarify their issues, or suggest to someone they need to add some words to Moodle Docs.

===Bad behavior ===
Questions and comments which are rude, incomprehensible or inappropriate in a multi cultural, world wide environment will not be tolerated. In short, be respectful.

Mistakes and misunderstandings happen. It is your actions and words that people will remember, and others are no different than yourself. A brief apology is always acceptable even when you intended no harm but believe someone else reacted unexpectedly to your post.

:''Tip:'' If you are frustrated by your experience and feel the need to rant (as we all do sometimes), please remember that these Help forums are not the place for diatribes or flames. If you feel the need to address an aspect of Moodle or the online digital environment with other Moodle users that doesn't fit into any of the Help topics, you can use the Lounge (the Social Forum) for general discussions. But even in the Lounge, civil discourse is the Rule of the Day.

==Who answers those posts==
The Moodle Forums are free, community-supported, resources. Almost all of the participants donate their time and brain-power to the further refining of Moodle. These resources have made Moodle an excellent and evolving learning management system.

Moodle itself is provided without license fees to the general public and the Moodle community contributes to its success.

The Moodle Forums are a tremendous resource in the world of open source community-supported learning management systems. They will continue to evolve and improve as long as all of the participants also continue to be dedicated to their own improvement and that of the entire Moodle community.

==See also==

* [[Forums code of conduct]]
* [http://catb.org/~esr/faqs/smart-questions.html How To Ask Questions The Smart Way] by Eric Raymond, is a classic, if opinionated essay on this subject.

[[Category:Moodle.org]]

Theme checklist

2014-01-16T00:06:20Z

Tqr: /* Right-to-left languages */

{{Template:Themes}}So, you think your theme is finished? Well, Moodle is a big complex beast, and there are lots of obscure corners, that you might not know about. This page lists lots of things that you might have missed when working on your theme. To be sure your theme is really complete, you need to check these out.

== All the different forms of the front page ==

Depending on how many courses there are in your Moodle site, and how many of them the current user is enrolled in, the [[:en:Front_page|front page]] looks different. Have you tested all the different ways it can look?

== Big report tables ==

The [[:en:Gradebook|grader report]], and other similar reports like the quiz reports, are very big tables that don't fit on one screen. How does your theme cope. Is it easy for the teacher to scroll sideways to see all the data?

== Quiz 'secure' pop-up ==

When a quiz set to [[:en:Quiz_settings#Extra_restrictions_on_attempts|Full screen pop-up with some JavaScript security]] then the page uses a special 'secure' layout template that should have minimal headers or links.

== Fake blocks ==

While you are looking at the quiz, pay attention to the [[:en:Using_Quiz|Quiz navigation block]]. This is not a normal block that teachers or admins can add or remove, it is a 'Fake block' that looks like any other block but is part of the Moodle UI. Are you happy with where it appears, and how it looks?

Other parts of Moodle that use fake blocks are the [[:en:Lesson_module|Lesson activity]] and [[:en:Calendar|the calendar UI]].

== Right-to-left languages ==

In languages like Hebrew or Farsi, lots of things that you made left-aligned probably need to be right-aligned instead. Moodle adds .dir-rtl or .dir-ltr class to the body element, which you can use in CSS rules.

== ... please add more things here ... ==

Clean theme

2013-11-02T12:52:52Z

Tqr: /* Include a renderer in a bootstrap based theme */

{{Template:Themes}}{{Moodle 2.5}}This document describes how to copy and customise the Clean (bootstrapbase) theme so that you can build on this to create a theme of your own. It assumes you have some understanding of how themes work within Moodle 2.5, as well as a basic understanding of HTML and CSS. Also, because of the rapid development within Moodle, resulting in a number of versions available namely 2.3.x and 2.4.x, and 2.5.x it is important to understand that this tutorial is only valid for the Moodle 2.5+ Clean theme.

==Getting started==

From your Moodle '''theme''' directory '''right click''' on the '''clean''' theme and then '''''copy''' and '''paste''''' back into your Moodle '''theme''' directory. You should now have a folder called '''Copy of clean'''. If you '''right click''' this folder you are given the option to '''Rename''' it. So rename this folder to your choosen theme name, using only lower case letters, and if needed, underscores. For the purpose of this tutorial we will call the theme 'cleantheme'.

On opening 'cleantheme' you will find several files and sub-directories which have files within them.

These are:
; config.php : Where all the theme configurations are made. ''(contains some elements that require renaming)''
; lib.php : Where all the functions for the themes settings are found. ''(contains some elements that require renaming)''
; settings.php : Where all the setting for this theme are created. ''(contains some elements that require renaming)''
; version.php : Where the version number and plugin componant information is kept. ''(contains some elements that require renaming)''
; /lang/ : This directory contains all language sub-directories for other languages if and when you want to add them.
; /lang/en/ : This sub-directory contains your language files, in this case ''English''.
; /lang/en/theme_clean.php : This file contains all the language strings for your theme. ''(contains some elements that require renaming as well as the filename itself)''
; /layout/ : This directory contains all the layout files for this theme.
; /layout/columns1.php : Layout file for a one column layout (content only).
; /layout/columns2.php : Layout file for a two column layout (side-pre and content).
; /layout/columns3.php : Layout file for a three column layout (side-pre, content and side-post) and the front page.
; /layout/embedded.php : Embedded layout file for embeded pages, like iframe/object embeded in moodleform - it needs as much space as possible.
; /layout/maintenance.php : Maintenance layout file which does not have any blocks, links, or API calls that would lead to database or cache interaction.
; /layout/secure.php : Secure layout file for safebrowser and securewindow.
; /style/ : This directory contains all the CSS files for this theme.
; /style/custom.css : This is where all the settings CSS is generated.
; /pix/ : This directory contains a screen shot of this theme as well as a favicon and any images used in the theme.

==Renaming Elements==

The problem when '''cloning''' a theme is that you need to rename all those instances where the old theme name occurs, in this case '''clean'''. So using the above list as a guide, search through and change all the instances of the theme name 'clean' to 'cleantheme'. This includes the filename of the lang/en/theme_clean.php. You need to change this to 'theme_cleantheme.php'.

==Installing your theme==

Once all the changes to the name have been made, you can safely install the theme. If you are already logged in just refreshing the browser should trigger your Moodle site to begin the install 'Plugins Check'. If not then navigate to Administration > Notifications.

Once your theme is successfully installed you can select it and begin to modify it using the custom settings page found by navigating to Administration > Site Administration > Appearance > Themes >> and then click on (Cleantheme) or whatever you renamed your theme to, from the list of theme names that appear at this point in the side block.

==Include a renderer in a bootstrap based theme==

If you need to override any renderers in your theme, then make sure you override the renderers by extending the parent theme renderers, which in this case is bootstrapbase. For example the class that you need to start your renderer with is as follows...

<code php>
class theme_yourtheme_core_renderer extends theme_bootstrapbase_core_renderer {

}
</code>

...where ''''yourtheme'''' requires you to change it to your theme name otherwise it will not work.

(Please note: The normal recipe <tt>class theme_'''yourtheme'''_core_renderer extends core_renderer</tt> is wrong for themes whose parent theme uses renderers, because this method will ultimately conflict with the parent theme's renderers.)

==See also==

* [http://www.somerandomthoughts.com/blog/2013/05/08/moodle-2-5-and-the-bootstrap-based-theme-clean/ Moodle 2.5 and the Bootstrap based theme – Clean] blog post by Gavin Henrick
* [http://basbrands.nl/blog/2013/05/21/building-with-bootstrap/ Building With Bootstrap] blog post by Bas Brands

Clean theme

2013-11-02T12:50:22Z

Tqr: /* Include a renderer in a bootstrap based theme */

{{Template:Themes}}{{Moodle 2.5}}This document describes how to copy and customise the Clean (bootstrapbase) theme so that you can build on this to create a theme of your own. It assumes you have some understanding of how themes work within Moodle 2.5, as well as a basic understanding of HTML and CSS. Also, because of the rapid development within Moodle, resulting in a number of versions available namely 2.3.x and 2.4.x, and 2.5.x it is important to understand that this tutorial is only valid for the Moodle 2.5+ Clean theme.

==Getting started==

From your Moodle '''theme''' directory '''right click''' on the '''clean''' theme and then '''''copy''' and '''paste''''' back into your Moodle '''theme''' directory. You should now have a folder called '''Copy of clean'''. If you '''right click''' this folder you are given the option to '''Rename''' it. So rename this folder to your choosen theme name, using only lower case letters, and if needed, underscores. For the purpose of this tutorial we will call the theme 'cleantheme'.

On opening 'cleantheme' you will find several files and sub-directories which have files within them.

These are:
; config.php : Where all the theme configurations are made. ''(contains some elements that require renaming)''
; lib.php : Where all the functions for the themes settings are found. ''(contains some elements that require renaming)''
; settings.php : Where all the setting for this theme are created. ''(contains some elements that require renaming)''
; version.php : Where the version number and plugin componant information is kept. ''(contains some elements that require renaming)''
; /lang/ : This directory contains all language sub-directories for other languages if and when you want to add them.
; /lang/en/ : This sub-directory contains your language files, in this case ''English''.
; /lang/en/theme_clean.php : This file contains all the language strings for your theme. ''(contains some elements that require renaming as well as the filename itself)''
; /layout/ : This directory contains all the layout files for this theme.
; /layout/columns1.php : Layout file for a one column layout (content only).
; /layout/columns2.php : Layout file for a two column layout (side-pre and content).
; /layout/columns3.php : Layout file for a three column layout (side-pre, content and side-post) and the front page.
; /layout/embedded.php : Embedded layout file for embeded pages, like iframe/object embeded in moodleform - it needs as much space as possible.
; /layout/maintenance.php : Maintenance layout file which does not have any blocks, links, or API calls that would lead to database or cache interaction.
; /layout/secure.php : Secure layout file for safebrowser and securewindow.
; /style/ : This directory contains all the CSS files for this theme.
; /style/custom.css : This is where all the settings CSS is generated.
; /pix/ : This directory contains a screen shot of this theme as well as a favicon and any images used in the theme.

==Renaming Elements==

The problem when '''cloning''' a theme is that you need to rename all those instances where the old theme name occurs, in this case '''clean'''. So using the above list as a guide, search through and change all the instances of the theme name 'clean' to 'cleantheme'. This includes the filename of the lang/en/theme_clean.php. You need to change this to 'theme_cleantheme.php'.

==Installing your theme==

Once all the changes to the name have been made, you can safely install the theme. If you are already logged in just refreshing the browser should trigger your Moodle site to begin the install 'Plugins Check'. If not then navigate to Administration > Notifications.

Once your theme is successfully installed you can select it and begin to modify it using the custom settings page found by navigating to Administration > Site Administration > Appearance > Themes >> and then click on (Cleantheme) or whatever you renamed your theme to, from the list of theme names that appear at this point in the side block.

==Include a renderer in a bootstrap based theme==

If you need to override any renderers in your theme, then make sure you override the renderers by extending the parent theme renderers, which in this case is bootstrapbase. For example the class that you need to start your renderer with is as follows...

<code php>
class theme_yourtheme_core_renderer extends theme_bootstrapbase_core_renderer {

}
</code>

...where '*yourtheme*' requires you to change that to the your theme name otherwise it will not work.

(Please note: The normal recipe <tt>class theme_*yourtheme*_core_renderer extends core_renderer</tt> is wrong for themes whose parent theme uses renderers, because this method will ultimately conflict with the parent theme's renderers.)

==See also==

* [http://www.somerandomthoughts.com/blog/2013/05/08/moodle-2-5-and-the-bootstrap-based-theme-clean/ Moodle 2.5 and the Bootstrap based theme – Clean] blog post by Gavin Henrick
* [http://basbrands.nl/blog/2013/05/21/building-with-bootstrap/ Building With Bootstrap] blog post by Bas Brands

Creating a theme

2013-08-07T22:19:51Z

Tqr: /* Configuring our theme */

{{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:
<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
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 } ?>
</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 sute 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]]

LESS

2013-05-24T18:25:13Z

Tqr: /* Using Recess */

== Overview ==

LESS ([http://lesscss.org lesscss.org]) extends CSS with dynamic behavior such as variables, mixins, operations and functions. It's an advanced way of writing CSS that we use in some themes within Moodle.

Browsers don't interpret it themselves, however, so LESS files need to be converted into normal CSS before use.

Recess is one tool used to compile and compress LESS into CSS under *nix based systems. There are [https://github.com/cloudhead/less.js/wiki/GUI-compilers-that-use-LESS.js many others tools for LESS].

== The bootstrapbase theme ==

Moodle's [[Bootstrap]] base theme has rules written using LESS.

The main LESS file is '''theme/bootstrapbase/less/moodle.less''', with additional files in '''theme/bootstrapbase/less/moodle/''' imported by the main file.

After compiling the LESS files, CSS ends up in '''theme/bootstrapbase/style/moodle.css'''. This file should not be edited manually.

== Compilers ==

=== Recess ===
==== Installing Recess under Ubuntu ====
The following commands should be run to install Recess

<pre>
1. sudo apt-get install npm node
(if the above fails due to the error "The following packages have unmet dependencies", run the commands separately, ie. sudo apt-get install npm and then sudo apt-get install node)
2. npm install recess -g
</pre>

<code>npm</code> stands for Node Package Manager, and is the equivalent of apt-get for node.js packages.

==== Installing Recess on Mac OS X ====
1. Install the basic node packages from the web site: [http://nodejs.org http://nodejs.org] (or use your favourite package manager to install <code>node</code> and <code>npm</code>).

2. On the command line, install recess like this:
<pre>
npm install recess -g
</pre>

==== Installing Recess under Windows7 ====

In order to install Recess you need to have Node.js installed first, which is relatively simple to do.

====Install Node.js====

These instructions are for Windows 7 64 bit.

Go to nodejs.org click install.

When installed go to -> Start -> All Programs -> type Node.js into the Search box, then select Node.js Command prompt (black icon) from the list. Now you are ready to install Recess. So at the command line prompt type the following:

<pre>
npm install recess -g
</pre>

<code>npm</code> stands for Node Package Manager, and is the equivalent of apt-get for node.js packages.

==== Using Recess ====

After editing the LESS files, compile (minified) your CSS as follows:

<pre>
cd theme/bootstrapbase/less/
recess --compile --compress moodle.less > ../style/moodle.css
</pre>

This will compile and compress the moodle.less file (and all the LESS and CSS files it imports) into a single file, moodle.css, and store it in the style folder of the bootstrapbase theme.

Alternatively if you want to view the normal (un-minified) CSS then use the following method.

<pre>
recess --compile moodle.less > ../style/moodle.css
</pre>

'''NOTE:''' if you are getting an empty moodle.css file, this is being caused by a parsing error in your LESS code. A bug in <code>recess</code> currently prevents it giving you helpful error messages in many cases. You will need to examine what you have altered or written to make sure it is complete and the syntax is correct. The <code>lessc</code> compiler is what is used by <code>recess</code> to do the actual compiling and will have been installed automatically along with it. If you call it directly as <code>lessc moodle.less</code> it should give you a helpful error message that points you to where the problem is.

LESS

2013-05-24T18:21:38Z

Tqr: /* Using Recess */

== Overview ==

LESS ([http://lesscss.org lesscss.org]) extends CSS with dynamic behavior such as variables, mixins, operations and functions. It's an advanced way of writing CSS that we use in some themes within Moodle.

Browsers don't interpret it themselves, however, so LESS files need to be converted into normal CSS before use.

Recess is one tool used to compile and compress LESS into CSS under *nix based systems. There are [https://github.com/cloudhead/less.js/wiki/GUI-compilers-that-use-LESS.js many others tools for LESS].

== The bootstrapbase theme ==

Moodle's [[Bootstrap]] base theme has rules written using LESS.

The main LESS file is '''theme/bootstrapbase/less/moodle.less''', with additional files in '''theme/bootstrapbase/less/moodle/''' imported by the main file.

After compiling the LESS files, CSS ends up in '''theme/bootstrapbase/style/moodle.css'''. This file should not be edited manually.

== Compilers ==

=== Recess ===
==== Installing Recess under Ubuntu ====
The following commands should be run to install Recess

<pre>
1. sudo apt-get install npm node
(if the above fails due to the error "The following packages have unmet dependencies", run the commands separately, ie. sudo apt-get install npm and then sudo apt-get install node)
2. npm install recess -g
</pre>

<code>npm</code> stands for Node Package Manager, and is the equivalent of apt-get for node.js packages.

==== Installing Recess on Mac OS X ====
1. Install the basic node packages from the web site: [http://nodejs.org http://nodejs.org] (or use your favourite package manager to install <code>node</code> and <code>npm</code>).

2. On the command line, install recess like this:
<pre>
npm install recess -g
</pre>

==== Installing Recess under Windows7 ====

In order to install Recess you need to have Node.js installed first, which is relatively simple to do.

====Install Node.js====

These instructions are for Windows 7 64 bit.

Go to nodejs.org click install.

When installed go to -> Start -> All Programs -> type Node.js into the Search box, then select Node.js Command prompt (black icon) from the list. Now you are ready to install Recess. So at the command line prompt type the following:

<pre>
npm install recess -g
</pre>

<code>npm</code> stands for Node Package Manager, and is the equivalent of apt-get for node.js packages.

==== Using Recess ====

After editing the LESS files, compile (minified) your CSS as follows:

<pre>
cd theme/bootstrapbase/less/
recess --compile --compress moodle.less > ../style/moodle.css
</pre>

Alternatively if you want to view the normal (un-minified) CSS then use the following method.

<pre>
recess --compile moodle.less > ../style/moodle.css
</pre>

This will compile and compress the moodle.less file (and all the LESS and CSS files it imports) into a single file, moodle.css, and store it in the style folder of the bootstrapbase theme.

NOTE: if you are getting empty moodle.css files, this is being caused by a parsing error in your LESS code. A bug in <code>recess</code> currently prevents it giving you helpful error messages in many cases. You will need to examine what you have altered or written to make sure it is complete and the syntax is correct. The <code>lessc</code> compiler is what is used by <code>recess</code> to do the actual compiling and will have been installed automatically along with it. If you call it directly as <code>lessc moodle.less</code> it should give you a helpful error message that points you to where the problem is.

LESS

2013-05-24T00:08:11Z

Tqr: /* The bootstrap theme */

LESS

2013-05-24T00:07:12Z

Tqr: /* The bootstrap theme */

LESS

2013-05-24T00:05:33Z

Tqr: /* Using Recess */

Clean theme

2013-05-05T12:44:23Z

Tqr: /* Renaming Elements */

Clean theme

2013-05-05T12:42:47Z

Tqr: /* Getting started */

Themes

2013-05-05T12:36:30Z

Tqr: Added a link

This page is a starting point for Moodle theme developers.

For documentation on installing and using themes, please see the [[:en:Themes|Themes user documentation]] and [[:en:Themes FAQ|Themes FAQ]].

Moodle has a powerful themes system that allows for a variety of effects through the use of XHTML and CSS.

* [[Themes overview]]
* [[Creating a theme]] - A quick step by step guide to creating your first theme.
* [[Cloning a theme]]
* [[Using images in a theme]] - How to use and override images within your theme.
* [[Creating a theme settings page]] - Looks at how to add a setting page making your theme easily customisable.
* [[Extending the theme custom menu]] - Customising the custom menu.
* [[Overriding a renderer]] - A tutorial on creating a custom renderer and changing the HTML Moodle produces.
* [[Clean theme]] (new in 2.5) - How to copy and customise the Clean theme to create your own theme.
* [https://moodle.org/mod/forum/discuss.php?d=224651 How to add a 'Watermark' as a background image to your theme.]

==See also==

* [[:Category:Themes|List of all themes-related developer documentation]]

[[Category:Themes]]

LESS

2013-04-28T17:42:22Z

Tqr: /* The bootstrap theme */

Clean theme

2013-04-25T09:47:25Z

Tqr: Updating contents ready for name change. :)

Cloning a theme

2013-04-23T21:32:31Z

Tqr: /* Renaming Elements */

{{Template:Themes}}This document describes how to clone a theme from an existing Moodle 2 theme. It assumes you have some understanding of how themes work within Moodle, as well as a basic understanding of XHTML and CSS. Also, because of the rapid development within Moodle, resulting in a number of versions available namely 2.0.x, 2.1.x 2.2.x 2.3.x 2.4.x and soon to be announced Moodle 2.5.x it is important to know that this tutorial is valid for ONLY Moodle Boxxie theme, and as such does not take into account the various other elements you will find in other Moodle versions of themes like Afterburner, Formal White, Sky High, to name but a few. If you are looking to clone one of these themes then checkout my new tutorials. [https://docs.moodle.org/dev/Themes_2.2_how_to_clone_a_Moodle_2.2_theme How to clone a Moodle 2.2 theme].

==Getting started==

Since this is a very easy introduction to creating a custom theme, the first thing to create is a copy of the version of the theme you want to clone. For the purpose of this tutorial, we will be cloning '''Boxxie''', which is one of several Moodle '''core''' themes. There are other themes you can 'clone' which are a little harder to do, but once you are familiar with this easy one, you can tackle the harder ones later.

OK...let's get started. From your Moodle '''theme''' directory '''right click''' on '''boxxie''' and then '''''copy''' and '''paste''''' back into your Moodle '''theme''' directory. You should now have a folder called '''Copy of boxxie'''. If you '''right click''' this folder you are given the option to '''Rename''' it. So let's rename this folder to '''foxxie''' (or to whatever name you want to call your '''cloned''' theme). It is important to use only lower case letters and underscores.

If you open the '''foxxie''' directory you will find several directories, sub-directories and files within it. One of these sub-directories '''''lang/en/''''' contain a file called '''theme_boxxie.php''' which will need to be re-named to '''theme_foxxie.php'''. But we shall address this later. For now just familiarise yourself with what you find in the '''foxxie''' directory.

These are:
; config.php : Where all the theme configurations are made.
; /lang/ : This directory contains all language sub-directories for other languages if and when you want to add them.
; /lang/en/ : This sub-directory contains your language files, in this case ''English''.
; /lang/en/theme_boxxie.php : This file contains all the language strings for your theme.
; /layout/ : This directory contains all the layout files for this theme.
; /layout/frontpage.php : Layout file for front page.
; /layout/general.php : Layout file for all pages other than the front page.
; /layout/embedded.php : Layout file for embedded pages.
; /style/ : This directory contains all the CSS files for this theme.
; /style/core.css : Contains all the CSS rules for this theme.
; /style/boilerplate.css : Contains all the ''reset'' CSS rules for this theme.
; /pix/ : This directory contains a screen shot of this theme as well as a favicon and any images used in the theme.
; /pix/tabs : This contains all the tab images for this theme.

==Renaming Elements==

The problem when '''cloning''' a theme is that you need to rename all those instances where the theme name, in this case '''boxxie''', occurs. The first place to look is '''config.php''', where you need to change the theme name.
<code php>
$THEME->name = 'boxxie';

////////////////////////////////////////////////////
// Name of the theme. Most likely the name of
// the directory in which this file resides.
////////////////////////////////////////////////////
</code>

The next place to look, as mentioned above, is '''lang/en/theme_boxxie.php'''. This file, as well as needing to be renamed, also needs some of its content renaming too. So before we forget, let's '''right click''' on this file and '''rename''' it '''theme_foxxie.php''' before we open it.

=== Language Strings ===

When you open '''theme_foxxie.php''' the first thing you will see are the '''credits''' for the theme.
<code php>
/**
* Strings for component 'theme_boxxie', language 'en', branch 'MOODLE_20_STABLE'
*
* @package moodlecore
* @copyright 2010 Patrick Malley
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>
Here you will need to change the reference from '''boxxie''' to '''foxxie''', you can leave the rest of this as it is.

The next things you will find in this file are what are known as the '''language strings'''. These are used for any customised '''''words'' or ''phrases''''' used in a theme. And because this is in the '''foxxie/lang/en/''' directory all the $strings are in English. But if you wanted to add some foreign words and phrases for whenever a user switched languages, you just need to create a new sub-directory in the '''foxxie/lang/''' directory for the language files you need to add there, and then copy and paste this file to that new sub-directory. For example: '''foxxie/lang/it/theme_foxxie.php''' (where '''it''' is the code which represents the Italian language). We will explore the Language aspect of themes in another Moodle Doc. So let's just concentrate on the changes we need to make to rest of the contents of '''theme_foxxie.php'''.

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

In the $string section above, the only thing you need to change here is the '''pluginname''' from '''boxxie''' to '''foxxie'''.

In this next section, the '''choosereadme''', which is written in XHTML and is the contents of the page that you will see when selecting '''Foxxie''' in the Theme Selector. However, you are advised to read what is actually written there and change it accordingly, renaming 'Boxxie' to 'Foxxie', and changing the contents of this part to suit yourself. You might not want to keep all that is written here. You could actually condense it, but that's up to you. Just as long as you give credit, where credit is due, to the original theme designer by stating something on similar lines to what I have written below.

<code php>
$string['choosereadme'] = 'Foxxie is a customised Moodle theme
by Mary Evans based on the original Boxxie theme by Patrick Malley';
</code>

==Recipe for the Impatient==
For those who want a minimal set of instructions to semi-blindly blast through this:

'''1.''' Copy ''[moodleroot]/theme/boxxie'' to ''[moodleroot]/theme/foxxie''

'''2.''' Rename ''[moodleroot]/theme/foxxie/lang/en/theme_boxxie.php'' to ''[moodleroot]/theme/foxxie/lang/en/theme_foxxie.php''

'''3.''' In ''[moodleroot]/theme/foxxie/lang/en/theme_foxxie.php'', replace any instances of "boxxie" with "foxxie", likewise for "Boxxie" and "Foxxie".

'''4.''' Edit ''[moodleroot]/theme/foxxie/config.php'' to replace instance(s) of "boxxie" with "foxxie".

==Appendix==
Please Note: All theme names, directory names, and file names MUST be in lowercase.

==See also==

* [[Making a horizontal dock]] - Modifying the dock to make it horizontal.
* [[Styling and customising the dock]] - How to style and customise the dock.
* [[Adding theme upgrade code]]
* [[Theme changes in 2.0]]
* [[Using jQuery with Moodle]]

Cloning a theme

2013-04-23T07:40:56Z

Tqr:

{{Template:Themes}}This document describes how to clone a theme from an existing Moodle 2 theme. It assumes you have some understanding of how themes work within Moodle, as well as a basic understanding of XHTML and CSS. Also, because of the rapid development within Moodle, resulting in a number of versions available namely 2.0.x, 2.1.x 2.2.x 2.3.x 2.4.x and soon to be announced Moodle 2.5.x it is important to know that this tutorial is valid for ONLY Moodle Boxxie theme, and as such does not take into account the various other elements you will find in other Moodle versions of themes like Afterburner, Formal White, Sky High, to name but a few. If you are looking to clone one of these themes then checkout my new tutorials. [https://docs.moodle.org/dev/Themes_2.2_how_to_clone_a_Moodle_2.2_theme How to clone a Moodle 2.2 theme].

==Getting started==

Since this is a very easy introduction to creating a custom theme, the first thing to create is a copy of the version of the theme you want to clone. For the purpose of this tutorial, we will be cloning '''Boxxie''', which is one of several Moodle '''core''' themes. There are other themes you can 'clone' which are a little harder to do, but once you are familiar with this easy one, you can tackle the harder ones later.

OK...let's get started. From your Moodle '''theme''' directory '''right click''' on '''boxxie''' and then '''''copy''' and '''paste''''' back into your Moodle '''theme''' directory. You should now have a folder called '''Copy of boxxie'''. If you '''right click''' this folder you are given the option to '''Rename''' it. So let's rename this folder to '''foxxie''' (or to whatever name you want to call your '''cloned''' theme). It is important to use only lower case letters and underscores.

If you open the '''foxxie''' directory you will find several directories, sub-directories and files within it. One of these sub-directories '''''lang/en/''''' contain a file called '''theme_boxxie.php''' which will need to be re-named to '''theme_foxxie.php'''. But we shall address this later. For now just familiarise yourself with what you find in the '''foxxie''' directory.

These are:
; config.php : Where all the theme configurations are made.
; /lang/ : This directory contains all language sub-directories for other languages if and when you want to add them.
; /lang/en/ : This sub-directory contains your language files, in this case ''English''.
; /lang/en/theme_boxxie.php : This file contains all the language strings for your theme.
; /layout/ : This directory contains all the layout files for this theme.
; /layout/frontpage.php : Layout file for front page.
; /layout/general.php : Layout file for all pages other than the front page.
; /layout/embedded.php : Layout file for embedded pages.
; /style/ : This directory contains all the CSS files for this theme.
; /style/core.css : Contains all the CSS rules for this theme.
; /style/boilerplate.css : Contains all the ''reset'' CSS rules for this theme.
; /pix/ : This directory contains a screen shot of this theme as well as a favicon and any images used in the theme.
; /pix/tabs : This contains all the tab images for this theme.

==Renaming Elements==

The problem when '''cloning''' a theme is that you need to rename all those instances where the theme name, in this case '''boxxie''', occurs. The first place to look is '''config.php''', where you need to change the theme name.
<code php>
$THEME->name = 'boxxie';

////////////////////////////////////////////////////
// Name of the theme. Most likely the name of
// the directory in which this file resides.
////////////////////////////////////////////////////
</code>

The next place to look, as mentioned above, is '''lang/en/theme_boxxie.php'''. This file, as well as needing to be renamed, also needs some of its content renaming too. So before we forget, let's '''right click''' on this file and '''rename''' it '''theme_foxxie.php''' before we open it.

=== Language Strings ===

When you open '''theme_foxxie.php''' the first thing you will see are the '''credits''' for the theme.
<code php>
/**
* Strings for component 'theme_boxxie', language 'en', branch 'MOODLE_20_STABLE'
*
* @package moodlecore
* @copyright 2010 Patrick Malley
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>
Here you will need to change the reference from '''boxxie''' to '''foxxie''', you can leave the rest of this as it is.

The next things you will find in this file are what are known as the '''language strings'''. These are used for any customised '''''words'' or ''phrases''''' used in a theme. And because this is in the '''foxxie/lang/en/''' directory all the $strings are in English. But if you wanted to add some foreign words and phrases for whenever a user switched languages, you just need to create a new sub-directory in the '''foxxie/lang/''' directory for the language files you need to add there, and then copy and paste this file to that new sub-directory. For example: '''foxxie/lang/it/theme_foxxie.php''' (where '''it''' is the code which represents the Italian language). We will explore the Language aspect of themes in another Moodle Doc. So let's just concentrate on the changes we need to make to rest of the contents of '''theme_foxxie.php'''.

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

In the $string section above, the only thing you need to change here is the '''pluginname''' from '''boxxie''' to '''foxxie'''.

In this next section, the '''choosereadme''', which is written in XHTML and is the contents of the page that you will see when selecting '''Foxxie''' in the Theme Selector. However, you are advised to read what is actually written there and change it accordingly, renaming 'Boxxie' to 'Foxxie', and changing the contents of this part to suit yourself. You might not want to keep all that is written here. You could actually condense it, but that's up to you. Just as long as you give credit, where credit is due, to the original theme designer by stating something on similar lines to what I have written below.

<code php>
$string['choosereadme'] = 'Foxxie is a customised Moodle theme
by Mary Evans based on the original Boxxie theme by Patrick Malley';
</code>

And that is all there is to this Moodle 2.0 theme.

==Recipe for the Impatient==
For those who want a minimal set of instructions to semi-blindly blast through this:

'''1.''' Copy ''[moodleroot]/theme/boxxie'' to ''[moodleroot]/theme/foxxie''

'''2.''' Rename ''[moodleroot]/theme/foxxie/lang/en/theme_boxxie.php'' to ''[moodleroot]/theme/foxxie/lang/en/theme_foxxie.php''

'''3.''' In ''[moodleroot]/theme/foxxie/lang/en/theme_foxxie.php'', replace any instances of "boxxie" with "foxxie", likewise for "Boxxie" and "Foxxie".

'''4.''' Edit ''[moodleroot]/theme/foxxie/config.php'' to replace instance(s) of "boxxie" with "foxxie".

==Appendix==
Please Note: All theme names, directory names, and file names MUST be in lowercase.

==See also==

* [[Making a horizontal dock]] - Modifying the dock to make it horizontal.
* [[Styling and customising the dock]] - How to style and customise the dock.
* [[Adding theme upgrade code]]
* [[Theme changes in 2.0]]
* [[Using jQuery with Moodle]]

Cloning a theme

2013-04-23T07:38:16Z

Tqr: Simplifying

{{Template:Themes}}This document describes how to clone a theme from an existing Moodle 2 theme. It assumes you have some understanding of how themes work within Moodle, as well as a basic understanding of XHTML and CSS. Also, because of the rapid development within Moodle, resulting in a number of versions available namely 2.0.x, 2.1.x 2.2.x 2.3.x 2.4.x and soon to be announced Moodle 2.5.x it is important to know that this tutorial is valid for ONLY Moodle Boxxie theme, and as such does not take into account the various other elements you will find in other Moodle versions of themes like Afterburner, Formal White, Sky High, to name but a few. If you are looking to clone one of these themes then checkout my new tutorials. [https://docs.moodle.org/dev/how_to_clone_a_Moodle_2.2_theme How to clone a Moodle 2.2 theme].

==Getting started==

Since this is a very easy introduction to creating a custom theme, the first thing to create is a copy of the version of the theme you want to clone. For the purpose of this tutorial, we will be cloning '''Boxxie''', which is one of several Moodle '''core''' themes. There are other themes you can 'clone' which are a little harder to do, but once you are familiar with this easy one, you can tackle the harder ones later.

OK...let's get started. From your Moodle '''theme''' directory '''right click''' on '''boxxie''' and then '''''copy''' and '''paste''''' back into your Moodle '''theme''' directory. You should now have a folder called '''Copy of boxxie'''. If you '''right click''' this folder you are given the option to '''Rename''' it. So let's rename this folder to '''foxxie''' (or to whatever name you want to call your '''cloned''' theme). It is important to use only lower case letters and underscores.

If you open the '''foxxie''' directory you will find several directories, sub-directories and files within it. One of these sub-directories '''''lang/en/''''' contain a file called '''theme_boxxie.php''' which will need to be re-named to '''theme_foxxie.php'''. But we shall address this later. For now just familiarise yourself with what you find in the '''foxxie''' directory.

These are:
; config.php : Where all the theme configurations are made.
; /lang/ : This directory contains all language sub-directories for other languages if and when you want to add them.
; /lang/en/ : This sub-directory contains your language files, in this case ''English''.
; /lang/en/theme_boxxie.php : This file contains all the language strings for your theme.
; /layout/ : This directory contains all the layout files for this theme.
; /layout/frontpage.php : Layout file for front page.
; /layout/general.php : Layout file for all pages other than the front page.
; /layout/embedded.php : Layout file for embedded pages.
; /style/ : This directory contains all the CSS files for this theme.
; /style/core.css : Contains all the CSS rules for this theme.
; /style/boilerplate.css : Contains all the ''reset'' CSS rules for this theme.
; /pix/ : This directory contains a screen shot of this theme as well as a favicon and any images used in the theme.
; /pix/tabs : This contains all the tab images for this theme.

==Renaming Elements==

The problem when '''cloning''' a theme is that you need to rename all those instances where the theme name, in this case '''boxxie''', occurs. The first place to look is '''config.php''', where you need to change the theme name.
<code php>
$THEME->name = 'boxxie';

////////////////////////////////////////////////////
// Name of the theme. Most likely the name of
// the directory in which this file resides.
////////////////////////////////////////////////////
</code>

The next place to look, as mentioned above, is '''lang/en/theme_boxxie.php'''. This file, as well as needing to be renamed, also needs some of its content renaming too. So before we forget, let's '''right click''' on this file and '''rename''' it '''theme_foxxie.php''' before we open it.

=== Language Strings ===

When you open '''theme_foxxie.php''' the first thing you will see are the '''credits''' for the theme.
<code php>
/**
* Strings for component 'theme_boxxie', language 'en', branch 'MOODLE_20_STABLE'
*
* @package moodlecore
* @copyright 2010 Patrick Malley
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>
Here you will need to change the reference from '''boxxie''' to '''foxxie''', you can leave the rest of this as it is.

The next things you will find in this file are what are known as the '''language strings'''. These are used for any customised '''''words'' or ''phrases''''' used in a theme. And because this is in the '''foxxie/lang/en/''' directory all the $strings are in English. But if you wanted to add some foreign words and phrases for whenever a user switched languages, you just need to create a new sub-directory in the '''foxxie/lang/''' directory for the language files you need to add there, and then copy and paste this file to that new sub-directory. For example: '''foxxie/lang/it/theme_foxxie.php''' (where '''it''' is the code which represents the Italian language). We will explore the Language aspect of themes in another Moodle Doc. So let's just concentrate on the changes we need to make to rest of the contents of '''theme_foxxie.php'''.

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

In the $string section above, the only thing you need to change here is the '''pluginname''' from '''boxxie''' to '''foxxie'''.

In this next section, the '''choosereadme''', which is written in XHTML and is the contents of the page that you will see when selecting '''Foxxie''' in the Theme Selector. However, you are advised to read what is actually written there and change it accordingly, renaming 'Boxxie' to 'Foxxie', and changing the contents of this part to suit yourself. You might not want to keep all that is written here. You could actually condense it, but that's up to you. Just as long as you give credit, where credit is due, to the original theme designer by stating something on similar lines to what I have written below.

<code php>
$string['choosereadme'] = 'Foxxie is a customised Moodle theme
by Mary Evans based on the original Boxxie theme by Patrick Malley';
</code>

And that is all there is to this Moodle 2.0 theme.

==Recipe for the Impatient==
For those who want a minimal set of instructions to semi-blindly blast through this:

'''1.''' Copy ''[moodleroot]/theme/boxxie'' to ''[moodleroot]/theme/foxxie''

'''2.''' Rename ''[moodleroot]/theme/foxxie/lang/en/theme_boxxie.php'' to ''[moodleroot]/theme/foxxie/lang/en/theme_foxxie.php''

'''3.''' In ''[moodleroot]/theme/foxxie/lang/en/theme_foxxie.php'', replace any instances of "boxxie" with "foxxie", likewise for "Boxxie" and "Foxxie".

'''4.''' Edit ''[moodleroot]/theme/foxxie/config.php'' to replace instance(s) of "boxxie" with "foxxie".

==Appendix==
Please Note: All theme names, directory names, and file names MUST be in lowercase.

==See also==

* [[Making a horizontal dock]] - Modifying the dock to make it horizontal.
* [[Styling and customising the dock]] - How to style and customise the dock.
* [[Adding theme upgrade code]]
* [[Theme changes in 2.0]]
* [[Using jQuery with Moodle]]

LESS

2013-04-23T01:25:42Z

Tqr: /* Install Node.js */

LESS

2013-04-23T01:23:41Z

Tqr: /* Install Node.js */