MoodleDocs - User contributions [en]

Using the File API in Moodle forms

2021-05-16T11:36:43Z

Gb2048: _manager should be _filemanager as per 'file_postupdate_standard_filemanager()' in '/lib/filelib.php'.

{{Moodle 2.0}}

==Overview==

In Moodle 2.0 all files are stored in a central database accessible via the [[File API|File API]], and every file is associated with a component and a "file area" in Moodle, such as a particular module.

A common use case is to provide a form (using Moodle's [[lib/formslib.php|Forms API]]) which allows users to upload or import files as attachments or media embedded into HTML.

Normally this works like this:
# User starts creation or re-edits an existing item in Moodle (eg forum post, resource, glossary entry etc)
# User presses some sort of button to browse for new files to attach or embed
# User sees our "Choose file..." dialog, which contains one or more repository instances.
# User chooses a file, the corresponding [[Repository plugins|Repository plugin]] takes care of copying the file into a "draft file area" within Moodle
# File appears in the text or as an attachment in the form.
# When the user hits save, the [[File API|File API]] is invoked to move the file from the draft file area into a permanent file area associated with that data

This document shows you exactly how to use Moodle forms to interact with users in a standard and secure way.

If you just want to write code to manipulate Moodle files internally (without user input) then see [[File API]].

==Form elements==

In Moodle 2.0 there are three file-related form elements for interacting with users:

# filemanager - the way to attach one or more files as a set
# editor - the way to specify a textarea with a HTML editor, and all the handling of images and movies within that HTML
# filepicker - a way to specify one file for the case when you want to process the file and throw it away

In Moodle 1.9 there were two other types which are now '''deprecated''' (they work, but please do not use these anymore)
# file - used to just allow a normal file upload from the desktop only.
# htmleditor - this old method of embedding a HTML editor in a textarea is not able to support repositories etc.

===filepicker===

File picker (''filepicker'') is a direct replacement of the older ''file'' formslib element.

It is intended for situations when you want the user to upload '''one''' file so you can process it and delete it, such as when you are importing data from a CSV file.
If you want a file that remains part of the Moodle storage and will reappear when you reopen the form, then you should use a filemanager instead (and restrict it to a single file, if necessary).

==== Using the filepicker element ====

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null,
array('maxbytes' => $maxbytes, 'accepted_types' => '*'));
</code>

==== Obtain the chosen file ====

To get the contents of the file:

<code php>
$content = $mform->get_file_content('userfile');
</code>

To get the name of the chosen file:

<code php>
$name = $mform->get_new_filename('userfile');
</code>

To save the chosen file to the server filesystem (such as to moodledata folder):

<code php>
$success = $mform->save_file('userfile', $fullpath, $override);
</code>

To store the chosen file in the Moodle files pool:

<code php>
$storedfile = $mform->save_stored_file('userfile', ...);
</code>

=== filemanager ===

The File Manager element improves on file picker by allowing you to manage more than one file. It is expected that the files will be stored permanently for future use (such as forum and glossary attachments).

==== Add file manager element ====

Example:
<code php>
$mform->addElement('filemanager', 'attachments', get_string('attachment', 'moodle'), null,
array('subdirs' => 0, 'maxbytes' => $maxbytes, 'areamaxbytes' => 10485760, 'maxfiles' => 50,
'accepted_types' => array('document'), 'return_types'=> FILE_INTERNAL | FILE_EXTERNAL));
</code>

Here are the fields for filemanager:

;'filemanager':This is a filemanager element :)
;elementname:The unique name of the element in the form
;elementlabel:The label string that users see
;attributes:(leave it as null)
;options: an array of further options for the filepicker (see below)

The options array can contain:

;subdirs:(Default 1) Are subdirectories allowed? (true or false)
;maxbytes:(Default 0) Restricts the size of each individual file.
;areamaxbytes:(Default 0) Restricts the total size of all the files.
;maxfiles:(Default -1) Restricts the total number of files.
;accepted_types:(Default *) You can specify what file types are accepted by filemanager. All current file types are listed in <code>get_mimetypes_array()</code> in [https://github.com/moodle/moodle/blob/master/lib/classes/filetypes.php lib/classes/filetypes.php].

Example usage: '''array('audio', 'video', 'document')''', you can include file extensions as well, for example: '''array('.txt', '.jpg', 'audio')'''.

==== Load existing files into draft area ====

<code php>
if (empty($entry->id)) {
$entry = new stdClass;
$entry->id = null;
}

$draftitemid = file_get_submitted_draft_itemid('attachments');

file_prepare_draft_area($draftitemid, $context->id, 'mod_glossary', 'attachment', $entry->id,
array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));

$entry->attachments = $draftitemid;

$mform->set_data($entry);

</code>

==== Store updated set of files ====

<code php>
if ($data = $mform->get_data()) {
// ... store or update $entry
file_save_draft_area_files($data->attachments, $context->id, 'mod_glossary', 'attachment',
$entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
}
</code>

===editor===
There are two ways of using the editor element in code, the first one is easier but expects some standardized fields. The second method is more low level.

====Simple use====
# name database fields: ''textfield'', ''textfieldformat'' (and ''textfieldtrust'' if required)
# create options array. note that context is the best, most local context you have available.
#:<code php>$textfieldoptions = array('trusttext'=>true, 'subdirs'=>true, 'maxfiles'=>$maxfiles, 'maxbytes'=>$maxbytes, 'context'=>$context);</code>
# add editor ''textfield_editor'' to moodle form, pass options through custom data in form constructor, set $data->id to null if data not exist yet
#:<code php>$mform->addElement('editor', 'textfield_editor', get_string('fieldname', 'somemodule'), null, $textfieldoptions);</code>
# prepare data
#:<code php>$data = file_prepare_standard_editor($data, 'textfield', $textfieldoptions, $context, 'mod_somemodule', 'somearea', $data->id);</code>
# get submitted data and after inserting/updating of data
#:<code php>$data = file_postupdate_standard_editor($data, 'textfield', $textfieldoptions, $context, 'mod_somemodule', 'somearea', $data->id);</code>

Real world examples are in mod/glossary/edit.php and mod/glossary/comment.php

====Low level use====

When using editor element you need to preprocess and postprocess the data:
# detect if form was already submitted (usually means draft is area already exists) - ''file_get_submitted_draft_itemid()''
# prepare draft file area, temporary storage of all files attached to the text - ''file_prepare_draft_area()''
# convert encoded relative links to absolute links - ''file_prepare_draft_area()''
# create form and set current data
# after submission the changed files must be merged back into original area - ''file_save_draft_area_files()''
# absolute links have to be replaced by relative links - ''file_save_draft_area_files()''

=====Replace old htmleditor with editor=====

The file picker has been integrated with with TinyMCE to make the editor element. This new element should support all types on editors and should be able to switch them on-the-fly. Instances of the old htmleditor element in your forms should be replaced by the new editor element, this may need adding of new format and trusttext columns. For example:
<code php>
$mform->addElement('editor', 'entry', get_string('definition', 'glossary'), null,
array('maxfiles' => EDITOR_UNLIMITED_FILES));
</code>
The editor element can take following options: maxfiles, maxbytes, subdirs and changeformat. Please note that the embedded files is optional feature and is not expected be used everywhere.

'''Note''': the editor element now includes text format option. You should no longer use the separate format element type.

=====Prepare current data - text and files=====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
$entry->definition = '';
$entry->format = FORMAT_HTML;
}

$draftid_editor = file_get_submitted_draft_itemid('entry');
$currenttext = file_prepare_draft_area($draftid_editor, $context->id, 'mod_glossary', 'entry',
$entry->id, array('subdirs'=>true), $entry->definition);
$entry->entry = array('text'=>$currenttext, 'format'=>$entry->format, 'itemid'=>$draftid_editor);

$mform->set_data($entry);
</code>

If there are multiple files, they will share the same itemid.

=====Obtain text, format and save draft files=====

To retrieve editor content, you need to use following code:

<code php>
if ($fromform = $mform->get_data()) {
// content of editor
$messagetext = $fromform->entry['text'];
// format of content
$messageformat = $fromform->entry['format'];
}
</code>

When a user selects a file using the file picker, the file is initially stored in a draft file area, and a URL is inserted into the HTML in the editor that lets the person editing the content (but no one else) see the file.

When the user submits the form, we then need to save the draft files to the correct place in permanent storage. (Just like you have to call $DB->update_record('tablename', $data); to have the other parts of the form submission stored correctly.)

The save_files_from_draft_area function and replace absolute links with internal relative links do:
<code php>
$messagetext = file_save_draft_area_files($draftid_editor, $context->id, 'mod_glossary', 'entry',
$entry->id, array('subdirs'=>true), $messagetext);
</code>
; $context->id, 'component', 'proper_file_area' and $entry->id : correspond to the contextid, filearea and itemid columns in the [[File_API#Table:_files|files table]].
; $messagetext : this is the message text. As the files are saved to the real file area, the URLs in this content are rewritten.

All URLs in content that point to files managed to the File API are converted to a form that starts '@@PLUGINFILE@@/' before the content is stored in the database. That is what we mean by rewriting.

== File serving==

=== Convert internal relative links to absolute links ===

Before text content is displayed to the user, any URLs in the '@@PLUGINFILE@@/' form in the content need to be rewritten to the real URL where the user can access the files.
<code php>
$messagetext = file_rewrite_pluginfile_urls($messagetext, 'pluginfile.php',
$context->id, 'mod_mymodule', 'proper_file_area', $itemid);
</code>
; $messagetext : is the content containing the @@PLUGINFILE@@ URLs from the database.
; 'pluginfile.php' : there are a number of different scripts that can serve files with different permissions checks. You need to specify which one to use.
; $context->id, 'mod_mymodule', 'proper_file_area', $itemid : uniquely identifies the file area, as before.

=== Implement file serving access control ===

Attachments and embedded images should have the same access control like the text itself, in majority of cases these files are served using pluginfile.php. Access control is defined in ''module/lib.php'' file in function ''module_pluginfile()''.

== File browsing support ==
Only owner of each file area is allowed to use low level File API function to access files, other parts of Moodle should use file browsing API.

Activities may specify browsing support in own module/lib.php file by implementing functions module_get_file_areas() and module_get_file_info().

== Upgrading your code ==
Here I will attempt to describe some simple steps you can take to upgrade your file-handling form elements from pre-2.0 code to 2.0. We will use the example of glossary, since it has been used above.

=== Preparing your options ===
Unless you are happy with the defaults, you will need to define an array of options for each file-handling form element. You could define it at different places, but it's best to put it in one place and make the array(s) available to other files if they need it. In the majority of cases, this will be in a file like edit.php

Previous code in mod/glossary/edit.php:
<code php>
$mform =& new mod_glossary_entry_form(null, compact('cm', 'glossary', 'hook', 'mode', 'e', 'context'));
</code>
New code:
<code php>
$maxbytes = $course->maxbytes;
// Could also use $CFG->maxbytes if you are not coding within a course context

$definitionoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes, 'trusttext'=>true,
'context'=>$context);
$attachmentoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes);
$mform = new mod_glossary_entry_form(null, array('current'=>$entry, 'cm'=>$cm, 'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Note that the data being passed to the form constructor have changed also, but this is not part of the file API changes, I just include them to avoid confusion.

These options are for the htmleditor (definition field) and the filemanager (attachment field). They are used by a file called edit_form.php.

=== Element preparation ===
Before we look at this, however, we need to "prepare" the elements so that they can correctly display existing embedded images and attached files when you are editing a record instead of just creating one. So, let's take the code we've got so far in edit.php and add to it:

Currently upgraded code in edit.php:
<code php>
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
New code with element preparation:
<code php>
$entry = new stdClass();
$entry->id = 0; \\ See notes!
$entry = file_prepare_standard_editor($entry, 'definition', $definitionoptions, $context,
'mod_glossary', 'entry', $entry->id);
$entry = file_prepare_standard_filemanager($entry, 'attachment', $attachmentoptions, $context,
'mod_glossary', 'attachment', $entry->id);
$mform = new mod_glossary_entry_form(null, array('current'=>$entry, 'cm'=>$cm, 'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
$mform->set_data($entry);
</code>
Things to note:
* $entry in this case is simply a stdClass object which may either represent a new glossary entry or an existing one.
* $entry->id must be the unique identifier for the current object. If we are creating a new entry, it will be null, but in all cases it must be defined.
* These two functions (file_prepare_standard_editor and file_prepare_standard_filemanager) are shortcuts functions that take care of some of the tedious setting up for you, but they make a couple of assumptions:
*# You '''must''' name the form element as {element}_editor or {element}_filemanager (see next section)
*# You '''must''' have at least the following fields in the database: {element} and {element}summary, as described earlier in this documentation
*# $entry will be populated with a field (in this case) 'definition_filemanager' having the draftfileid of your files. This needs to get passed to the 'value' of the filemanager control in the form. If you get this wrong, existing file will not appear in the control when it is reloaded.

We can now look at the upgrades needed in the form definition file.

=== Form definition ===
Previous code in mod/glossary/edit_form.php:
<code php>
$mform->addElement('htmleditor', 'definition', get_string('definition', 'glossary'),
array('rows'=>20));
$mform->setType('definition', PARAM_RAW);
$mform->addRule('definition', null, 'required', null, 'client');
$mform->setHelpButton('definition', array('writing', 'richtext'), false, 'editorhelpbutton');
$mform->addElement('format');
// a bit further...
$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0,
true, true, false));
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
$mform->setHelpButton('attachment', array('attachment', get_string('attachment', 'glossary'),
'glossary'));
</code>
New code:
<code php>
$definitionoptions = $this->_customdata['definitionoptions'];
$attachmentoptions = $this->_customdata['attachmentoptions'];
// a bit further...
$mform->addElement('editor', 'definition_editor', get_string('definition', 'glossary'), null,
$definitionoptions);
$mform->setType('definition_editor', PARAM_RAW);
$mform->addRule('definition_editor', get_string('required'), 'required', null, 'client');
// a bit further...
$mform->addElement('filemanager', 'attachment_filemanager', get_string('attachment', 'glossary'),
null, $attachmentoptions);
$mform->setHelpButton('attachment_filemanager', array('attachment2',
get_string('attachment', 'glossary'), 'glossary'));
</code>

Note the following:
* The format element and the help button are no longer required for the HTML editor element
* The name of the form element needs to be changed by adding '_editor' or '_filemanager' to the original name. This is a naming convention that is used by a couple of functions we will look at shortly
* Make sure $definitionoptions has context parameter, else system context is used and editor will not respect filter settings.

=== Handling submitted data ===
The final step is to handle the submitted data properly, i.e. retrieve the files and save them to disk, associating them with the record we have just created (a glossary entry in our example). This happens in edit.php:

Previous code in edit.php:
<code php>
// Section that updates an entry:
$todb->id = $e;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
$todb->attachment = $newfilename;
}

// Section that adds an entry:
if ($todb->id = insert_record("glossary_entries", $todb)) {
$e = $todb->id;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
set_field("glossary_entries", "attachment", $newfilename, "id", $todb->id);
}
}
</code>
New code:
<code php>
// $todb was renamed to $entry, and the code was refactored
// so that the file-handling code is only used once for either an add or an update action.
// If an entry is being added, $DB->insert() has already been called, so we have a valid $entry->id
$entry = file_postupdate_standard_editor($entry, 'definition', $definitionoptions, $context,
'mod_glossary', 'entry', $entry->id);
$entry = file_postupdate_standard_filemanager($entry, 'attachment', $attachmentoptions, $context,
'mod_glossary', 'attachment', $entry->id);
// store the updated value values
$DB->update_record('glossary_entries', $entry);
</code>
Things to note:
* If you are adding a new record, you will still need to call update_record after calling the file_postupdate* functions

=== Gotchas ===
A few things to keep in mind:
* Make sure that you instantiate the moodle form before any call to $OUTPUT->header()

== See also ==

* [[File API]]
* [[Using the file API]]
* [[Repository plugins]]
* [[Portfolio API]]
* MDL-14589 - File API Meta issue
* [https://moodle.org/mod/forum/discuss.php?d=207748 Adding a text editor to a Moodle form]
* [https://moodle.org/mod/forum/discuss.php?d=157953#p692822 Button actions in Moodle form]
* [https://moodle.org/mod/forum/discuss.php?d=351013#p1416554 File Picker]
* [https://github.com/CARLOSEDUARDOVIEIRA/moodle-uploadfile Example of filemanager in an activity module]

[[Category:Files]]
[[Category:Repositories]]

Miscellaneous callbacks

2019-01-16T16:28:09Z

Gb2048: /* override_webservice_execution */

This page contains documentation for general callbacks available in Moodle plugins.

== control_view_profile ==

This callback allows an installation to control access to a user's profile page. It modifies the response of the user_can_view_profile function; this function is what causes Moodle to show a 'not allowed' error message if you try to view somebody's profile when you aren't allowed to.

You can use this callback if your institution needs to implement policies about who can view profiles in addition to those supported by standard Moodle. Normally it would be implemented in a local plugin, but you can implement in any type of plugin.

Your callback can return one of three values (all constants defined in the core_user class):

; VIEWPROFILE_DO_NOT_PREVENT : Use standard Moodle behaviour - apply Moodle's normal rules about whether the current user is allowed to view that profile or not. Your callback should return this if you don't need to change behaviour for the profile in question.
; VIEWPROFILE_PREVENT : Prevent the current user from viewing that user's profile, even if Moodle's normal rules would allow it.
; VIEWPROFILE_FORCE_ALLOW : Allow the current user to view that user's profile, even if Moodle's normal rules would prevent it.

=== Example code ===

This silly example, placed in local/myplugin/lib.php, prevents everyone from accessing the profile of a user 'abc123'.

<code php>
function local_myplugin_control_view_profile($user, $course = null, context_user $usercontext = null) {
if ($user->username='abc123') {
return core_user::VIEWPROFILE_PREVENT;
}
return core_user::VIEWPROFILE_DO_NOT_PREVENT;
}
</code>

=== Multiple plugins ===

The callback can be implemented by multiple plugins. Provided they behave sensibly and return DO_NOT_PREVENT when they don't need to modify behaviour, it should work as expected. The specific rules are:

* If any function returns VIEWPROFILE_PREVENT then the user will be prevented from viewing the profile.
* Otherwise, if no function returns VIEWPROFILE_PREVENT but any function returns VIEWPROFILE_FORCE_ALLOW , then the user will be allowed to view the profile.
* Otherwise all plugins returned VIEWPROFILE_DO_NOT_PREVENT, and Moodle standard behaviour will be used.

== store_profiling_data ==

This callback allows a plugin to get the profiling information from xhprof/tideways-xhprof and do it's own processing or storage with it.

=== Example code ===

This is a fragment of a possible plugin that writes files to /tmp/output.

<code php>
function local_profilestorefile_store_profiling_data($rec) {
$file = fopen("/tmp/output/" . $rec->runid, "w") or die("Unable to write to file, does the folder exist?");
fwrite($file, json_encode($rec));
fclose($file);
}
</code>

== override_webservice_execution ==
{{Moodle 3.6}}

This callback allows an installation to modify the standard behaviour of web service functions. It overrides the execution of the web service - the point where the actual function that does something is about to be called.

It works with:
* Web service calls from the mobile app.
* Other web service calls using the token system.
* AJAX web service calls.

You can call the standard function and modify the result, or do something entirely different.

This callback '''should not be used in core code'''. It is designed to allow people a way to change the standard behaviour for their instance.

Be aware that when you upgrade to a new Moodle version, the web service that you have overridden may change its definition or behaviour. In that case you would have to update this callback as well.

=== Usage ===

The function is called with the web service function object (as returned by external_api::external_function_info) and a numerically-indexed array of the parameters for the function.

* If the callback wants to override the function, it should return a value in the same format as returned by the real function. Moodle will check this return value to make sure it matches the web service return type definition.
* If the callback does not want to override the function, it should return false to allow standard execution.

You will probably need to look at the code of the original implementation for the web service function so that you know how it works and what format the results are returned in.

The callback can be implemented by multiple plugins. If it is implemented multiple times then the first function that doesn't return false (in the order that Moodle lists plugins) will be used.

=== Example code ===

This example, placed in '''local/myplugin/lib.php''', changes the course list returned by the '''core_course_get_courses''' web service function so that it does not include a particular course.

This will have the result of hiding the course from the mobile app. (It may have other undesirable effects within the mobile app - obviously, this override is not officially supported.)

<code php>
function local_myplugin_override_webservice_execution($function, $params) {
// Check if it's the function we want to override.
if ($function->name === 'core_course_get_courses') {
// Call the original function.
$result = call_user_func_array([$function->classname, $function->methodname], $params);

// Get rid of a specific course from the results
foreach ($result as $index => $course) {
if ($course['shortname'] === 'SNEAKY') {
unset($result[$index]);
}
}

$result = array_values($result);
return $result;
}

return false;
}
</code>

This second example modifies the '''core_fetch_notifications''' function, which is called by AJAX after every page load, to add a notification with the current time:

<code php>
function local_myplugin_override_webservice_execution($function, $params) {
// Check if it's the AJAX function that fetches notifications.
if ($function->name === 'core_fetch_notifications') {
// Call the original function.
$result = call_user_func_array([$function->classname, $function->methodname], $params);

// Add an extra notification.
$result[] = [
'template' => 'core/notification_info',
'variables' => ['message' => 'The time is: ' . date('H:i:s'), 'extraclasses' => '',
'closebutton' => false, 'announce' => true]
];
return $result;
}

return false;
}
</code>

=== Security considerations ===

This mechanism can bypass security checks. When this function is called, Moodle has checked the user's token or basic access but other checks have not yet been done.

* If you call the original function, that function will apply its security checks as normal, so this part should be safe.
* If you add extra data to the result, or extra functionality, make sure you have checked the appropriate permissions for the current user.
* If you replace the original function, make sure you do all the relevant security checks (look at the source code of the original function).

Javascript Modules

2015-04-24T17:29:27Z

Gb2048: /* Embedding AMD code in a page - $OUTPUT wrong, changed to $PAGE */

{{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>
$PAGE->requires->js_call_amd($modulename, $functionname, $params);
</code>

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

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

Themes overview

2014-04-06T19:00:08Z

Gb2048: /* Font file locations */

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

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

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

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

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

===Fonts===

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

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

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

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

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

===HTML 5 doctype===

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

===Internet Explorer standards mode===

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

===SVG icons===

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

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

==What's new in 2.0==

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

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

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

==The structure of a theme==

Some important things to know when building good themes:

# '''config.php''' - this file is required in every theme. It defines configuration settings and definitions required to make the theme work in Moodle. These include theme, file, region, default region and options.
# '''Layouts and layout files''' - in config.php there is one definition for each page type (see [[#theme_layouts_table|Appendix A: Theme layouts]] for a list of over 12 types). Each page type definition tells Moodle which layout file will be used, what block regions this page type should display and so on. The layout file contains the HTML and the minimum PHP required to display basic structure of pages. (If you know Moodle 1.9, it's like a combination of header.html and footer.html).
# '''The base theme''' - is not intended to be used for production sites. It sets up the simplest possible generic layout and includes only CSS essential to that layout ''or'' to Moodle as a whole. It tries not to make any unnecessary rules and makes as few assumptions as possible. It's the perfect base on which to start designing a theme, as there are very few colours, borders, margins, and alignments to override. You can just start adding what you need.

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

{| class="nicetable"
|-
! Directory
! File
! Description
|-
| /
| config.php
| Contains all of the configuration and definitions for each theme
|-
| /
| lib.php
| Contains speciality classes and functions that are used by theme
|-
| /
| renderers.php
| Contains any custom renderers for the theme.
|-
| /
| settings.php
| Contains custom theme settings. These local settings are defined by the theme allowing the theme user to easily alter something about the way it looks or operates. (eg a background colour, or a header image)
|-
| /
| version.php
| Contains the theme name, version number and Moodle version requirements for using the theme
|-
| /fonts/
| *.woff, *.ttf, *.eot, *.svg, *.otf
| Theme fonts (since 2.6).
|-
| /fonts_core/
| *.woff, *.ttf, *.eot, *.svg, *.otf
| Contains fonts that override standard core fonts (since 2.6).
|-
| /fonts_plugins/plugintype/pluginname/
| *.woff, *.ttf, *.eot, *.svg, *.otf
| Contains fonts that override plugin fonts (since 2.6).
|-
| /javascript/
| *.js
| All specialty JavaScript files the theme requires should be located in here.
|-
| /lang/
|
| Any special language files the theme requires should be located in here.
|-
| /layout/
| *.php
| Contains the layout files for the theme.
|-
| /pix/
| *.png, *.jpg, *.gif, *.svg
| Contains any images the theme makes use of either in CSS or in the layout files.
|-
| /pix/
| favicon.ico
| The favicon to display for this theme.
|-
| /pix/
| screenshot.png
| A screenshot of the theme to be displayed in on the theme selection screen.
|-
| /pix_core/
| *.png, *.jpg, *.gif, *.svg
| Contains images that override standard core images.
|-
| /pix_plugins/plugintype/pluginname/
| *.png, *.jpg, *.gif, *.svg
| Contains images that override plugin images.
|-
| /style/
| *.css
| Default location for CSS files.
|}

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

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

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

===Basic theme config example===
Lets have a look at a basic theme configuration file and the different bits that make it up:
<code php>
$THEME->name = 'newtheme';

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

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

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

$THEME->javascripts_footer = array(
'navigation'
);
</code>

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

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

; $THEME->parents : This defines the themes that the theme will extend. In this case it is extending only the base theme.

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

; $THEME->layouts : In this example, two layouts have been defined to override the layouts from the base theme. For more information see the [[#Layouts|layouts]] section below.

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

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

==CSS==
===Locations of CSS files===
First lets look at where CSS can be included from within Moodle:
; \theme\themename\style\*.css : This is the default location for all of the stylesheets that are used by a theme and the place which should be used by a theme designer.

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

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

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

As theme designers, we will only use the first method of introducing CSS: adding rules to a stylesheet file located in the theme's style directory.

===Moodle's core CSS organisation===
The next thing to look at is the organisation of CSS and rules within a theme. Although as a theme designer it is entirely up to you as to how you create and organise your CSS. Please note that within the themes provided in the standard install by Moodle there is a very clear organisation of CSS.

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

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

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

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

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

===How to write effective CSS rules within Moodle===
In Moodle 2.0, writing good CSS rules is incredibly important.

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

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

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

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

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

What does all of this look like in practise? Well using the above example /mod/forum/view.php you would get at least the following body tag:
<code html4strict><body id=”page-mod-forum-view” class=”path-mod path-mod-forum” /></code>

====Writing your rules====

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

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

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

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

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

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

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

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

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

It is also important to note that a new theme that will base itself on another theme (overriding it) does not need to define any layouts or use any layout files if there are no changes that it wishes to make to the layouts of the existing theme. The standard theme in Moodle is a good example of this as it extends the base theme simply adding CSS to achieve its look and feel.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==Language File==

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

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

<code php>
$string['pluginname'] = 'Standard';
$string['region-side-post'] = 'Right';
$string['region-side-pre'] = 'Left';
$string['choosereadme'] = 'This theme is a very basic white theme, with a minimum amount of
CSS added to the base theme to make it actually usable.';
</code>

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

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

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

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

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

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

The following code snippet illustrates how to make use of your images within HTML, such as if you wanted to use them within a layout file.
<code php>
<img src="<?php echo $OUTPUT->pix_url('imageone', 'theme');?>" alt="" />
<img src="<?php echo $OUTPUT->pix_url('subdir/imagetwo', 'theme');?>" alt="" />
</code>

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

In this case rather than writing out the URL to the image we use a method of Moodle's output library. Its not too important how that functions works but it is important that we use it as it is what allows images within Moodle to be over-rideable.

The following is how you would use the images from within CSS as background images.
<code css>
.divone {
background-image: url([[pix:theme|imageone]]);
}

.divtwo {
background-image: url([[pix:theme|subdir/imagetwo]]);
}
</code>
If this case we have to use some special notations that Moodle looks for. Whenever Moodle hands out a CSS file it first searches for all ''[[something]]'' tags and replaces them with what is required.

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

From within a theme you can VERY easily override any standard image within Moodle by simply adding the replacement image to the theme's pix directory in the same sub directory structure as it is in Moodle.
So for instance we wanted to override the following two images:
# /pix/moodlelogo.gif
# /pix/i/user.gif
We would simply need to add our replacement images to the theme in the following locations
# /theme/themename/pix_core/moodlelogo.gif
# /theme/themename/pix_core/i/user.gif
''Note that we have created a '''pix_core''' directory in our theme. For module images we need a '''pix_mod''' directory.

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

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

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

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

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

===Font file locations===

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

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

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

===CSS placeholders===

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

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

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

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

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

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

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

===More free fonts===

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

===Warning===

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

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

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

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

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

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

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

===Required theme divs===

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

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

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

==Appendix A==
===Theme options as of 17th April 2013===
{| class="nicetable" id="theme_options_table"
|-
! Setting
! Effect
|-
| $THEME->'''csspostprocess'''
| Allows the user to provide the name of a function that all CSS should be passed to before being delivered.
|-
| $THEME->'''editor_sheets'''
| An array of stylesheets to include within the body of the editor.
|-
| $THEME->'''enable_dock'''
| If set to true the side dock is enabled for blocks
|-
| $THEME->'''hidefromselector'''
| Used to hide a theme from the theme selector (unless theme designer mode is on). Accepts true or false.
|-
| $THEME->'''filter_mediaplugin_colors'''
| Used to control the colours used in the small media player for the filters
|-
| $THEME->'''javascripts'''
| An array containing the names of JavaScript files located in /javascript/ to include in the theme. (gets included in the head)
|-
| $THEME->'''javascripts_footer'''
| As above but will be included in the page footer.
|-
| $THEME->'''larrow'''
| Overrides the left arrow image used throughout Moodle
|-
| $THEME->'''layouts'''
| An array setting the layouts for the theme
|-
| $THEME->'''name'''
| Name of the theme. Most likely the name of the directory in which this file resides.
|-
| $THEME->'''parents'''
| An array of themes to inherit from
|-
| $THEME->'''parents_exclude_javascripts'''
| An array of JavaScript files NOT to inherit from the themes parents
|-
| $THEME->'''parents_exclude_sheets'''
| An array of stylesheets not to inherit from the themes parents
|-
| $THEME->'''plugins_exclude_sheets'''
| An array of plugin sheets to ignore and not include.
|-
| $THEME->'''rarrow'''
| Overrides the right arrow image used throughout Moodle
|-
| $THEME->'''renderfactory'''
| Sets a custom render factory to use with the theme, used when working with custom renderers.
|-
| $THEME->'''resource_mp3player_colors'''
| Controls the colours for the MP3 player
|-
| $THEME->'''sheets'''
| An array of stylesheets to include for this theme. Should be located in the theme's style directory.
|-
| $THEME->'''supportscssoptimisation'''
| When set to 'FALSE' then the theme will not be affected by the 'CSS Optimiser'. The 'CSS Optimiser' is enabled in Development > Experimental > Experimental settings. When it is enabled CSS will be run through an optimisation process before being cached. The optimiser processes the CSS removing duplicate rules and styles, as well as white space removable and reformatting. Please note turning this on at the same time as theme designer mode is awful for performance but will help theme designers create optimised CSS.
|}

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

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

===Moodle 2.2+===

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

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

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

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

[[Category:Plugins]]

Themes overview

2014-04-06T18:57:01Z

Gb2048: /* Files and folders */

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

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

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

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

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

===Fonts===

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

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

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

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

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

===HTML 5 doctype===

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

===Internet Explorer standards mode===

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

===SVG icons===

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

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

==What's new in 2.0==

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

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

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

==The structure of a theme==

Some important things to know when building good themes:

# '''config.php''' - this file is required in every theme. It defines configuration settings and definitions required to make the theme work in Moodle. These include theme, file, region, default region and options.
# '''Layouts and layout files''' - in config.php there is one definition for each page type (see [[#theme_layouts_table|Appendix A: Theme layouts]] for a list of over 12 types). Each page type definition tells Moodle which layout file will be used, what block regions this page type should display and so on. The layout file contains the HTML and the minimum PHP required to display basic structure of pages. (If you know Moodle 1.9, it's like a combination of header.html and footer.html).
# '''The base theme''' - is not intended to be used for production sites. It sets up the simplest possible generic layout and includes only CSS essential to that layout ''or'' to Moodle as a whole. It tries not to make any unnecessary rules and makes as few assumptions as possible. It's the perfect base on which to start designing a theme, as there are very few colours, borders, margins, and alignments to override. You can just start adding what you need.

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

{| class="nicetable"
|-
! Directory
! File
! Description
|-
| /
| config.php
| Contains all of the configuration and definitions for each theme
|-
| /
| lib.php
| Contains speciality classes and functions that are used by theme
|-
| /
| renderers.php
| Contains any custom renderers for the theme.
|-
| /
| settings.php
| Contains custom theme settings. These local settings are defined by the theme allowing the theme user to easily alter something about the way it looks or operates. (eg a background colour, or a header image)
|-
| /
| version.php
| Contains the theme name, version number and Moodle version requirements for using the theme
|-
| /fonts/
| *.woff, *.ttf, *.eot, *.svg, *.otf
| Theme fonts (since 2.6).
|-
| /fonts_core/
| *.woff, *.ttf, *.eot, *.svg, *.otf
| Contains fonts that override standard core fonts (since 2.6).
|-
| /fonts_plugins/plugintype/pluginname/
| *.woff, *.ttf, *.eot, *.svg, *.otf
| Contains fonts that override plugin fonts (since 2.6).
|-
| /javascript/
| *.js
| All specialty JavaScript files the theme requires should be located in here.
|-
| /lang/
|
| Any special language files the theme requires should be located in here.
|-
| /layout/
| *.php
| Contains the layout files for the theme.
|-
| /pix/
| *.png, *.jpg, *.gif, *.svg
| Contains any images the theme makes use of either in CSS or in the layout files.
|-
| /pix/
| favicon.ico
| The favicon to display for this theme.
|-
| /pix/
| screenshot.png
| A screenshot of the theme to be displayed in on the theme selection screen.
|-
| /pix_core/
| *.png, *.jpg, *.gif, *.svg
| Contains images that override standard core images.
|-
| /pix_plugins/plugintype/pluginname/
| *.png, *.jpg, *.gif, *.svg
| Contains images that override plugin images.
|-
| /style/
| *.css
| Default location for CSS files.
|}

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

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

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

===Basic theme config example===
Lets have a look at a basic theme configuration file and the different bits that make it up:
<code php>
$THEME->name = 'newtheme';

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

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

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

$THEME->javascripts_footer = array(
'navigation'
);
</code>

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

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

; $THEME->parents : This defines the themes that the theme will extend. In this case it is extending only the base theme.

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

; $THEME->layouts : In this example, two layouts have been defined to override the layouts from the base theme. For more information see the [[#Layouts|layouts]] section below.

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

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

==CSS==
===Locations of CSS files===
First lets look at where CSS can be included from within Moodle:
; \theme\themename\style\*.css : This is the default location for all of the stylesheets that are used by a theme and the place which should be used by a theme designer.

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

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

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

As theme designers, we will only use the first method of introducing CSS: adding rules to a stylesheet file located in the theme's style directory.

===Moodle's core CSS organisation===
The next thing to look at is the organisation of CSS and rules within a theme. Although as a theme designer it is entirely up to you as to how you create and organise your CSS. Please note that within the themes provided in the standard install by Moodle there is a very clear organisation of CSS.

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

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

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

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

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

===How to write effective CSS rules within Moodle===
In Moodle 2.0, writing good CSS rules is incredibly important.

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

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

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

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

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

What does all of this look like in practise? Well using the above example /mod/forum/view.php you would get at least the following body tag:
<code html4strict><body id=”page-mod-forum-view” class=”path-mod path-mod-forum” /></code>

====Writing your rules====

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

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

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

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

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

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

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

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

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

It is also important to note that a new theme that will base itself on another theme (overriding it) does not need to define any layouts or use any layout files if there are no changes that it wishes to make to the layouts of the existing theme. The standard theme in Moodle is a good example of this as it extends the base theme simply adding CSS to achieve its look and feel.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==Language File==

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

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

<code php>
$string['pluginname'] = 'Standard';
$string['region-side-post'] = 'Right';
$string['region-side-pre'] = 'Left';
$string['choosereadme'] = 'This theme is a very basic white theme, with a minimum amount of
CSS added to the base theme to make it actually usable.';
</code>

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

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

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

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

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

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

The following code snippet illustrates how to make use of your images within HTML, such as if you wanted to use them within a layout file.
<code php>
<img src="<?php echo $OUTPUT->pix_url('imageone', 'theme');?>" alt="" />
<img src="<?php echo $OUTPUT->pix_url('subdir/imagetwo', 'theme');?>" alt="" />
</code>

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

In this case rather than writing out the URL to the image we use a method of Moodle's output library. Its not too important how that functions works but it is important that we use it as it is what allows images within Moodle to be over-rideable.

The following is how you would use the images from within CSS as background images.
<code css>
.divone {
background-image: url([[pix:theme|imageone]]);
}

.divtwo {
background-image: url([[pix:theme|subdir/imagetwo]]);
}
</code>
If this case we have to use some special notations that Moodle looks for. Whenever Moodle hands out a CSS file it first searches for all ''[[something]]'' tags and replaces them with what is required.

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

From within a theme you can VERY easily override any standard image within Moodle by simply adding the replacement image to the theme's pix directory in the same sub directory structure as it is in Moodle.
So for instance we wanted to override the following two images:
# /pix/moodlelogo.gif
# /pix/i/user.gif
We would simply need to add our replacement images to the theme in the following locations
# /theme/themename/pix_core/moodlelogo.gif
# /theme/themename/pix_core/i/user.gif
''Note that we have created a '''pix_core''' directory in our theme. For module images we need a '''pix_mod''' directory.

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

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

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

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

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

===Font file locations===

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

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

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

===CSS placeholders===

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

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

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

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

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

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

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

===More free fonts===

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

===Warning===

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

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

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

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

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

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

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

===Required theme divs===

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

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

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

==Appendix A==
===Theme options as of 17th April 2013===
{| class="nicetable" id="theme_options_table"
|-
! Setting
! Effect
|-
| $THEME->'''csspostprocess'''
| Allows the user to provide the name of a function that all CSS should be passed to before being delivered.
|-
| $THEME->'''editor_sheets'''
| An array of stylesheets to include within the body of the editor.
|-
| $THEME->'''enable_dock'''
| If set to true the side dock is enabled for blocks
|-
| $THEME->'''hidefromselector'''
| Used to hide a theme from the theme selector (unless theme designer mode is on). Accepts true or false.
|-
| $THEME->'''filter_mediaplugin_colors'''
| Used to control the colours used in the small media player for the filters
|-
| $THEME->'''javascripts'''
| An array containing the names of JavaScript files located in /javascript/ to include in the theme. (gets included in the head)
|-
| $THEME->'''javascripts_footer'''
| As above but will be included in the page footer.
|-
| $THEME->'''larrow'''
| Overrides the left arrow image used throughout Moodle
|-
| $THEME->'''layouts'''
| An array setting the layouts for the theme
|-
| $THEME->'''name'''
| Name of the theme. Most likely the name of the directory in which this file resides.
|-
| $THEME->'''parents'''
| An array of themes to inherit from
|-
| $THEME->'''parents_exclude_javascripts'''
| An array of JavaScript files NOT to inherit from the themes parents
|-
| $THEME->'''parents_exclude_sheets'''
| An array of stylesheets not to inherit from the themes parents
|-
| $THEME->'''plugins_exclude_sheets'''
| An array of plugin sheets to ignore and not include.
|-
| $THEME->'''rarrow'''
| Overrides the right arrow image used throughout Moodle
|-
| $THEME->'''renderfactory'''
| Sets a custom render factory to use with the theme, used when working with custom renderers.
|-
| $THEME->'''resource_mp3player_colors'''
| Controls the colours for the MP3 player
|-
| $THEME->'''sheets'''
| An array of stylesheets to include for this theme. Should be located in the theme's style directory.
|-
| $THEME->'''supportscssoptimisation'''
| When set to 'FALSE' then the theme will not be affected by the 'CSS Optimiser'. The 'CSS Optimiser' is enabled in Development > Experimental > Experimental settings. When it is enabled CSS will be run through an optimisation process before being cached. The optimiser processes the CSS removing duplicate rules and styles, as well as white space removable and reformatting. Please note turning this on at the same time as theme designer mode is awful for performance but will help theme designers create optimised CSS.
|}

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

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

===Moodle 2.2+===

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

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

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

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

[[Category:Plugins]]

Moodle.org courses and course formats forum help

2014-02-16T15:57:34Z

Gb2048:

== Courses and course formats forum posting guide ==

When posting on the forum, whether asking questions, wanting help or reporting an issue, it is really useful to include the following information in the post:

1) Moodle version and release details. They can be extracted from the 'version.php' file in the 'root' of your installation:

[[File:2014-02-04_14_43_07-F_moodledev_moodle26_version.php_-_Notepad%2B%2B_h.png]]

2) Course format version and release details, if your question relates to a course format. They can be extracted from the course formats 'version.php' file:

[[File:2014-02-04_14_47_51-F_moodledev_moodle26_course_format_topcoll_version.php_-_Notepad%2B%2B_h.png]]

And where you retrieved the version from, such as Moodle.org, GitHub etc.

3) Often issues can arise with clashes with themes. So, if you are using a contributed theme such as 'Essential', then provide those details too:

[[File:2014-02-04_14_52_02-F_moodledev_moodle26_theme_essential_version.php_-_Notepad%2B%2B_h.png]]

Along with where you retrieved the version from. If you are using a core theme, then just state which one as their version is linked to the Moodle version.

If you do not have access to the file system, then as an 'administrator' under 'Site administration' -> 'Notifications' you will find the Moodle release details:

[[File:2014-02-04_15_19_05-Moo26_Administration_Notifications_h.png]]

And under 'Site administration' -> 'Plugins' -> 'Plugins overview' with 'Showing add-ons only':

[[File:2014-02-04_15_34_04-2014-02-04_15_31_23-Moo26_Administration_Plugins_Plugins_overview_h.png]]

You will see the 'version' number for both course formats and themes.

4) A picture speaks a thousand words, so an annotated screen shot explaining the issue goes a long way:

[[File:2014-02-04_14_55_22-Course_t_h.png]]

5) All of the steps you did to produce the issue in the first place. Include where possible the test data files you used.

6) Details of any other contributed plugins you have installed. Which you consider relevant to the post.

All of this information makes it much easier for the person who replies to:

Replicate the issue using the same set-up as you have.
Understand exactly what you are talking about.
Reply quicker and not to ask for the details this guide states as they cannot replicate.

This will benefit you in getting the response you need. So please supply the information.

--[[User:Gareth Barnard|Gareth Barnard]] ([[User talk:Gareth Barnard|talk]]) 23:57, 16 February 2014 (WST)

P.S. In case you are wondering what the answer is to the question posed in the screen shot:

[[File:2014-02-04_14_58_45-Edit_course_settings_h.png]]

Moodle.org courses and course formats forum help

2014-02-16T15:52:09Z

Gb2048: Created page with " == Courses and course formats forum posting guide == When posting on the forum, whether asking questions, wanting help or reporting an issue, it is really useful to include ..."

== Courses and course formats forum posting guide ==

When posting on the forum, whether asking questions, wanting help or reporting an issue, it is really useful to include the following information in the post:

1) Moodle version and release details. They can be extracted from the 'version.php' file in the 'root' of your installation:

[[File:2014-02-04_14_43_07-F_moodledev_moodle26_version.php_-_Notepad%2B%2B_h.png]]

2) Course format version and release details, if your question relates to a course format. They can be extracted from the course formats 'version.php' file:

[[File:2014-02-04_14_47_51-F_moodledev_moodle26_course_format_topcoll_version.php_-_Notepad%2B%2B_h.png]]

And where you retrieved the version from, such as Moodle.org, GitHub etc.

3) Often issues can arise with clashes with themes. So, if you are using a contributed theme such as 'Essential', then provide those details too:

[[File:2014-02-04_14_52_02-F_moodledev_moodle26_theme_essential_version.php_-_Notepad%2B%2B_h.png]]

Along with where you retrieved the version from. If you are using a core theme, then just state which one as their version is linked to the Moodle version.

If you do not have access to the file system, then as an 'administrator' under 'Site administration' -> 'Notifications' you will find the Moodle release details:

[[File:2014-02-04_15_19_05-Moo26_Administration_Notifications_h.png]]

And under 'Site administration' -> 'Plugins' -> 'Plugins overview' with 'Showing add-ons only':

[[File:2014-02-04_15_34_04-2014-02-04_15_31_23-Moo26_Administration_Plugins_Plugins_overview_h.png]]

You will see the 'version' number for both course formats and themes.

4) A picture speaks a thousand words, so an annotated screen shot explaining the issue goes a long way:

[[File:2014-02-04_14_55_22-Course_t_h.png]]

5) All of the steps you did to produce the issue in the first place. Include where possible the test data files you used.

6) Details of any other contributed plugins you have installed. Which you consider relevant to the post.

All of this information makes it much easier for the person who replies to:

Replicate the issue using the same set-up as you have.
Understand exactly what you are talking about.
Reply quicker and not to ask for the details this guide states as they cannot replicate.

This will benefit you in getting the response you need. So please supply the information.

In case you are wondering what the answer is to the question posed in the screen shot:

[[File:2014-02-04_14_58_45-Edit_course_settings_h.png]]

File:2014-02-04 14 58 45-Edit course settings h.png

2014-02-16T15:50:26Z

Gb2048: Courses and course formats forum posting guide

Courses and course formats forum posting guide

File:2014-02-04 14 55 22-Course t h.png

2014-02-16T15:49:00Z

Gb2048: Courses and course formats forum posting guide

Courses and course formats forum posting guide

File:2014-02-04 15 34 04-2014-02-04 15 31 23-Moo26 Administration Plugins Plugins overview h.png

2014-02-16T15:47:45Z

Gb2048: Courses and course formats forum posting guide

Courses and course formats forum posting guide

File:2014-02-04 15 19 05-Moo26 Administration Notifications h.png

2014-02-16T15:46:23Z

Gb2048: Courses and course formats forum posting guideCourses and course formats forum posting guide

Courses and course formats forum posting guideCourses and course formats forum posting guide

File:2014-02-04 14 52 02-F moodledev moodle26 theme essential version.php - Notepad++ h.png

2014-02-16T15:44:27Z

Gb2048: Courses and course formats forum posting guide

Courses and course formats forum posting guide

File:2014-02-04 14 47 51-F moodledev moodle26 course format topcoll version.php - Notepad++ h.png

2014-02-16T15:42:36Z

Gb2048: Courses and course formats forum posting guide

Courses and course formats forum posting guide

File:2014-02-04 14 43 07-F moodledev moodle26 version.php - Notepad++ h.png

2014-02-16T15:40:46Z

Gb2048: Courses and course formats forum posting guide

Courses and course formats forum posting guide

NEWMODULE Adding capabilities

2014-02-08T10:41:21Z

Gb2048: Fixed typo

{{New_Module}}
In order to add a capabilities for your <<NEWMODULE>> you need to:

==1. Create a file access.php in the <<NEWMODULE>>/db directory==

This should contain a list of the capabilities that you want to define. For example:

<code php>
$capabilities = array(
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,
'captype' => 'write',
'contextlevel' => CONTEXT_MODULE,
'archetypes' => array(
'student' => CAP_ALLOW,
'teacher' => CAP_ALLOW,
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
)
),

// Add more capabilities here ...
)
</code>

The various parts of the capability definition are:

===Capability name ('mod/<<NEWMODULE>>:<<CAPABILITYNAME>>)===

This is the internal name used for this this capability. In addition to this internal name, you should also add the language string <<NEWMODULE>>:<<CAPABILITYNAME>> to your module's language file, to give the capability a name that users will see in the interface.

===riskbitmask===

Allowing people to do various things sometimes requires introducing possible security risks. For example, if you can post to a forum, you can post unsolicited advertising. To a certain extent users have to be trusted. To help administrators and teachers know what the issues are, each capability should list any associated risks. See [[Hardening_new_Roles_system]]. will be reflected in the list of icons of each row of the 'Override permissions'->roles page.

Technically, this value is a bit field, so you should combine the relevant risks constants with the '|' operator. So typical values might be:
* RISK_SPAM
* RISK_PERSONAL | RISK_XSS | RISK_DATALOSS

===captype===

Should be either 'read' or 'write'. 'read' is for capabilities that just let you view things. 'write' for capabilities that let you change things.

===contextlevel===

The context level where this capability is most relevant. If you are writing a module this will almost always be [[Context|CONTEXT_MODULE]]. (This does not have much effect. It is just used to sort and group capabilities on the define roles and override roles pages.)

===archetypes===

This section defines, for each role type, what default permissions those roles should be given when your module is first installed (or when a new capability is detected on upgrade).

Normally, you just add one line for each role that you want to give the capability to. The line should look like 'roletype' => CAP_ALLOW. Just leave out roles that you do not want to get the capability be default. Very exceptionally, you may need to specify a default permission of CAP_PREVENT, CAP_PROHIBIT.

Note that once a capability is established, permissions will not be automatically overwritten when a module is updated. If permissions have changed, an administrator must manually change or force capabilities to be [[:en:Manage_roles#Reset_role_to_defaults|reset to default]] for a role.

==2. Get Moodle to load the updated capabilities==

The capabilities you defined are only read (and copied into the Moodle database) when your module is installed or upgraded. So every time you edit the db/access.php file you must
# Increase your module's version number by editing the file mod/<<NEWMODULE>>/version.php.
# Go to the the Administration ► Notifications page, and click through the steps to let Moodle upgrade itself. You should see the name of your module in one of the steps.

==3. Checking the capability in your code==

In order to check whether the current user has a particular capability, you need to use the has_capability function. To do that, first you have to get the appropriate context. In this case, it will be a module context.

1. First we need to get the $cm id, and verify that it is correct (there are lots of different ways you might do this, this is only an example.
<code php>
$cmid = required_param('cmid', PARAM_INT);
if (!$cm = get_coursemodule_from_id('<<NEWMODULE>>', $cmid)) {
error("Course module ID was incorrect");
}
</code>

2. Then you get the module context:
<code php>
$context = get_context_instance(CONTEXT_MODULE, $cm->id);
</code>

3. Finally, you can actually check the permission
<code php>
if (has_capability('mod/<<NEWMODULE>>:<<CAPABILITYNAME>>', $context)) {
</code>

Normally, you do 1. and 2. once at the top of a script, and then call has_capability as needed within the script with the appropriate capabilities.

===Useful variations===

====Controlling overall access to a script====

Suppose you have a page that should only be available to users with a particular capability. For example, only users with mod/quiz:viewreports should be able to access mod/quiz/report.php. In cases like this, you can use the require_capability function:
<code php>
require_capability($capability, $context);
</code>
near the top of your script. (As soon as you have got the context and called require_login is a good time.) All this does internally is
<code php>
if (!has_capability($capability, $context)) {
// Display error and exit.
}
</code>
but using require_capability makes your code simpler and is recommended. (Of course, anywhere you might print a link to a page like this, you should only print the link if the user has the right capability.)

====Getting a list of users with a capability====

Suppose you need to get a list of all the users with a particular capability. (For example, the quiz reports list all the users with the mod/quiz:attempt capability. Then you can use the get_users_by_capability function.

====Checking the permissions of another user====

There is an optional 3rd parameter to has_capability that you can use to check another user's permissions:
<code php>
has_capability($capability, $context, $otheruser->id);
</code>

====Excluding administrators====

Administrators have a magic 'moodle/site:doanything' capability that gives them every other capability. If you wish to disable that magic override for one particular capability check, you can use the optional 4th parameter to has capability:
<code php>
has_capability($capability, $context, NULL, false);
</code>
However, you normally should not do this.

====Performance considerations====

The has_capability function has been carefully optimised, and is pretty fast and you should not really worry. However, it has to perform a fairly complex computation, and if you are going to make exactly the same has_capability call several times in a page (perhaps in a loop) it is probably worth moving the permission check outside the loop. For example don't do:
<code php>
foreach ($attempts as $attempt) {
if (has_capability('mod/quiz:viewreports', $context)) {
// ...
}
}
</code>
Instead do
<code php>
$canviewreports = has_capability('mod/quiz:viewreports', $context);
foreach ($attempts as $attempt) {
if ($canviewreports) {
// ...
}
}
</code>

get_users_by_capability is a very expensive computation. If you are calling it more than once in your script, you are probably doing something wrong ;-)

==See also==

* [[Access API]]
* [[Roles]]
* [[Hardening_new_Roles_system]] - information about risks
* [[NEWMODULE_Documentation]] - NEWMODULE Documentation front page

[[Category:Roles]]

Themes overview

2014-02-06T18:03:07Z

Gb2048: Fixed paths as wrong against https://docs.moodle.org/dev/Using_images_in_a_theme#Overriding_plugin_images

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

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

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

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

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

===Fonts===

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

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

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

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

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

===HTML 5 doctype===

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

===Internet Explorer standards mode===

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

===SVG icons===

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

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

==What's new in 2.0==

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

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

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

==The structure of a theme==

Some important things to know when building good themes:

# '''config.php''' - this file is required in every theme. It defines configuration settings and definitions required to make the theme work in Moodle. These include theme, file, region, default region and options.
# '''Layouts and layout files''' - in config.php there is one definition for each page type (see [[#theme_layouts_table|Appendix A: Theme layouts]] for a list of over 12 types). Each page type definition tells Moodle which layout file will be used, what block regions this page type should display and so on. The layout file contains the HTML and the minimum PHP required to display basic structure of pages. (If you know Moodle 1.9, it's like a combination of header.html and footer.html).
# '''The base theme''' - is not intended to be used for production sites. It sets up the simplest possible generic layout and includes only CSS essential to that layout ''or'' to Moodle as a whole. It tries not to make any unnecessary rules and makes as few assumptions as possible. It's the perfect base on which to start designing a theme, as there are very few colours, borders, margins, and alignments to override. You can just start adding what you need.

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

{| class="nicetable"
|-
! Directory
! File
! Description
|-
| /
| config.php
| Contains all of the configuration and definitions for each theme
|-
| /
| lib.php
| Contains speciality classes and functions that are used by theme
|-
| /
| renderers.php
| Contains any custom renderers for the theme.
|-
| /
| settings.php
| Contains custom theme settings. These local settings are defined by the theme allowing the theme user to easily alter something about the way it looks or operates. (eg a background colour, or a header image)
|-
| /
| version.php
| Contains the theme name, version number and Moodle version requirements for using the theme
|-
| /fonts/
| *.woff
| Theme fonts (since 2.6).
|-
| /fonts_core/
| *.woff
| Contains fonts that override standard core fonts (since 2.6).
|-
| /fonts_plugins/plugintype/pluginname/
| *.woff
| Contains fonts that override plugin fonts (since 2.6).
|-
| /javascript/
| *.js
| All specialty JavaScript files the theme requires should be located in here.
|-
| /lang/
|
| Any special language files the theme requires should be located in here.
|-
| /layout/
| *.php
| Contains the layout files for the theme.
|-
| /pix/
| *.png, *.jpg, *.gif, *.svg
| Contains any images the theme makes use of either in CSS or in the layout files.
|-
| /pix/
| favicon.ico
| The favicon to display for this theme.
|-
| /pix/
| screenshot.png
| A screenshot of the theme to be displayed in on the theme selection screen.
|-
| /pix_core/
| *.png, *.jpg, *.gif, *.svg
| Contains images that override standard core images.
|-
| /pix_plugins/plugintype/pluginname/
| *.png, *.jpg, *.gif, *.svg
| Contains images that override plugin images.
|-
| /style/
| *.css
| Default location for CSS files.
|}

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

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

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

===Basic theme config example===
Lets have a look at a basic theme configuration file and the different bits that make it up:
<code php>
$THEME->name = 'newtheme';

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

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

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

$THEME->javascripts_footer = array(
'navigation'
);
</code>

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

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

; $THEME->parents : This defines the themes that the theme will extend. In this case it is extending only the base theme.

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

; $THEME->layouts : In this example, two layouts have been defined to override the layouts from the base theme. For more information see the [[#Layouts|layouts]] section below.

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

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

==CSS==
===Locations of CSS files===
First lets look at where CSS can be included from within Moodle:
; \theme\themename\style\*.css : This is the default location for all of the stylesheets that are used by a theme and the place which should be used by a theme designer.

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

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

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

As theme designers, we will only use the first method of introducing CSS: adding rules to a stylesheet file located in the theme's style directory.

===Moodle's core CSS organisation===
The next thing to look at is the organisation of CSS and rules within a theme. Although as a theme designer it is entirely up to you as to how you create and organise your CSS. Please note that within the themes provided in the standard install by Moodle there is a very clear organisation of CSS.

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

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

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

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

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

===How to write effective CSS rules within Moodle===
In Moodle 2.0, writing good CSS rules is incredibly important.

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

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

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

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

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

What does all of this look like in practise? Well using the above example /mod/forum/view.php you would get at least the following body tag:
<code html4strict><body id=”page-mod-forum-view” class=”path-mod path-mod-forum” /></code>

====Writing your rules====

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

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

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

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

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

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

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

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

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

It is also important to note that a new theme that will base itself on another theme (overriding it) does not need to define any layouts or use any layout files if there are no changes that it wishes to make to the layouts of the existing theme. The standard theme in Moodle is a good example of this as it extends the base theme simply adding CSS to achieve its look and feel.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==Language File==

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

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

<code php>
$string['pluginname'] = 'Standard';
$string['region-side-post'] = 'Right';
$string['region-side-pre'] = 'Left';
$string['choosereadme'] = 'This theme is a very basic white theme, with a minimum amount of
CSS added to the base theme to make it actually usable.';
</code>

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

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

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

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

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

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

The following code snippet illustrates how to make use of your images within HTML, such as if you wanted to use them within a layout file.
<code php>
<img src="<?php echo $OUTPUT->pix_url('imageone', 'theme');?>" alt="" />
<img src="<?php echo $OUTPUT->pix_url('subdir/imagetwo', 'theme');?>" alt="" />
</code>

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

In this case rather than writing out the URL to the image we use a method of Moodle's output library. Its not too important how that functions works but it is important that we use it as it is what allows images within Moodle to be over-rideable.

The following is how you would use the images from within CSS as background images.
<code css>
.divone {
background-image: url([[pix:theme|imageone]]);
}

.divtwo {
background-image: url([[pix:theme|subdir/imagetwo]]);
}
</code>
If this case we have to use some special notations that Moodle looks for. Whenever Moodle hands out a CSS file it first searches for all ''[[something]]'' tags and replaces them with what is required.

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

From within a theme you can VERY easily override any standard image within Moodle by simply adding the replacement image to the theme's pix directory in the same sub directory structure as it is in Moodle.
So for instance we wanted to override the following two images:
# /pix/moodlelogo.gif
# /pix/i/user.gif
We would simply need to add our replacement images to the theme in the following locations
# /theme/themename/pix_core/moodlelogo.gif
# /theme/themename/pix_core/i/user.gif
''Note that we have created a '''pix_core''' directory in our theme. For module images we need a '''pix_mod''' directory.

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

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

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

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

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

===Font file locations===

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

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

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

===CSS placeholders===

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

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

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

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

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

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

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

===More free fonts===

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

===Warning===

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

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

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

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

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

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

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

===Required theme divs===

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

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

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

==Appendix A==
===Theme options as of 17th April 2013===
{| class="nicetable" id="theme_options_table"
|-
! Setting
! Effect
|-
| $THEME->'''csspostprocess'''
| Allows the user to provide the name of a function that all CSS should be passed to before being delivered.
|-
| $THEME->'''editor_sheets'''
| An array of stylesheets to include within the body of the editor.
|-
| $THEME->'''enable_dock'''
| If set to true the side dock is enabled for blocks
|-
| $THEME->'''hidefromselector'''
| Used to hide a theme from the theme selector (unless theme designer mode is on). Accepts true or false.
|-
| $THEME->'''filter_mediaplugin_colors'''
| Used to control the colours used in the small media player for the filters
|-
| $THEME->'''javascripts'''
| An array containing the names of JavaScript files located in /javascript/ to include in the theme. (gets included in the head)
|-
| $THEME->'''javascripts_footer'''
| As above but will be included in the page footer.
|-
| $THEME->'''larrow'''
| Overrides the left arrow image used throughout Moodle
|-
| $THEME->'''layouts'''
| An array setting the layouts for the theme
|-
| $THEME->'''name'''
| Name of the theme. Most likely the name of the directory in which this file resides.
|-
| $THEME->'''parents'''
| An array of themes to inherit from
|-
| $THEME->'''parents_exclude_javascripts'''
| An array of JavaScript files NOT to inherit from the themes parents
|-
| $THEME->'''parents_exclude_sheets'''
| An array of stylesheets not to inherit from the themes parents
|-
| $THEME->'''plugins_exclude_sheets'''
| An array of plugin sheets to ignore and not include.
|-
| $THEME->'''rarrow'''
| Overrides the right arrow image used throughout Moodle
|-
| $THEME->'''renderfactory'''
| Sets a custom render factory to use with the theme, used when working with custom renderers.
|-
| $THEME->'''resource_mp3player_colors'''
| Controls the colours for the MP3 player
|-
| $THEME->'''sheets'''
| An array of stylesheets to include for this theme. Should be located in the theme's style directory.
|-
| $THEME->'''supportscssoptimisation'''
| When set to 'FALSE' then the theme will not be affected by the 'CSS Optimiser'. The 'CSS Optimiser' is enabled in Development > Experimental > Experimental settings. When it is enabled CSS will be run through an optimisation process before being cached. The optimiser processes the CSS removing duplicate rules and styles, as well as white space removable and reformatting. Please note turning this on at the same time as theme designer mode is awful for performance but will help theme designers create optimised CSS.
|}

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

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

===Moodle 2.2+===

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

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

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

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

[[Category:Plugins]]

Theme checklist

2014-02-01T16:11:18Z

Gb2048:

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

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

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

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

2014-02-01T16:08:04Z

Gb2048:

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

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

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

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

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

2014-02-01T15:33:06Z

Gb2048:

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

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

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

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

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

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

2014-02-01T15:24:35Z

Gb2048:

Theme checklist

2014-02-01T15:21:02Z

Gb2048:

Theme checklist

2014-02-01T15:17:08Z

Gb2048:

Clean theme

2013-10-31T14:28:21Z

Gb2048: /* Getting started */

{{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 from the bootstrap theme, like

<code php>
class theme_overridetest_core_renderer extends theme_bootstrapbase_core_renderer {

}
</code>

(The normal recipe <tt>class theme_overridetest_core_renderer extends core_renderer</tt> is wrong for bootstrap-based themes.)

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

XMLDB editor

2013-10-02T11:40:38Z

Gb2048: Fix incorrect navigation.

Location: ''Site administration > Development > XMLDB editor''

*The XMLDB editor is a tool for making the .xml files that specify how moodle should set up its database tables. Previously, developers had to make separate .sql install files for mysql and postgres, but now only database-neutral file is needed, which supports many more databases.

*It makes the editing of tables/fields/keys/indexes almost a trivial task, allowing developers to spend the time coding and improving things instead of fighting with XML files and the errors caused by manual editing (of course, developers are free to use such extra time as desired - beers, dance, books, music...) ;-)

*All new ''install.xml'' files present under each ''db'' directory in Moodle can be edited (and we recommend it) with just some clicks and keystrokes. Those ''install.xml'' will contain all the info needed to generate the specific objects needed for each RDBMS supported.

*Note: To be able to handle files properly, the web server needs write access to all ''db'' directories where the ''install.xml'' files reside (and to the files themselves, of course). If you cannot click either the load or create link, that means that you either have not created the /db directory, or that it is not writeable by the webserver.

== Quick Start ==

To use the XMLDB editor to create tables for a new plugin:

# Under your plugin's directory, create a '''<code>db</code>''' directory, e.g. '''<code>mod/mymodule/db</code>'''. Make sure the web server has write access to this directory.
# In Moodle, navigate to Site administration->Development->XMLDB editor
# You should now see '''<code>mod/mymodule/db</code>''' in the list of XMLDB locations, and the '''Create''' link should now be clickable. (If you see your directory but none of the links are clickable, make sure the web server has write access to this directory!)
# Click '''Create'''. (This will create a blank install.xml file)
# Click '''Load'''. (This will load the contents of the install.xml file into memory)
# Click '''Edit'''.
# Now you can actually use the XMLDB editor, to create and edit tables for your plugin.
# When you're done, keep clicking '''Back''' and '''Back to Main''' until you get back to the list of XMLDB locations, and then click '''Save'''.

This will create an ''install.xml'' file, which can be used to load your tables into the database in conjunction with a ''version.php'' file. See [[Installing_and_upgrading_plugin_database_tables]] for more information.

After the initial installation of a plugin, for subsequent updates to the plugin's table structure you'll need to manually create an ''upgrade.php'' file in your module's ''db'' folder. The ''upgrade.php'' file should start off looking something like this:

<code php>
<?php

function xmldb_mymodule_upgrade($oldversion) {
global $CFG;

$result = TRUE;

// Insert PHP code from XMLDB Editor here

return $result;
}
?>
</code>

To get the code for the '// Insert PHP code here' bit, open the XMLDB Editor and load the relevant ''install.xml'' file. Choose the 'View PHP' option and then copy and paste the generated code.

== Use==

*The XMLDB editor is pretty easy to use so there's no need for a complete guide here. Playing with it for a while is highly recommended, viewing how it works and how it modifies the ''install.xml'' files.

*It's organised in a top-bottom structure, where you start ''loading''' (or ''creating'') a new XMLDB file. Then, you can ''edit'' the file and its ''general structure'' will be shown. This structure has two types of elements, ''tables'' and ''statements'' and the XMLDB editor allows you to ''add'', ''edit'', ''delete'', and ''move'' them easily. Also, for initial creation of tables, one small but effective '''reverse-enginery''' tool has been developed (only under MySQL) allowing you to retrofit any table from the DB to the XMLDB Editor.

*Whilst editing tables you will see their ''fields'', ''keys'' and ''indexes'' and you'll be able to handle all them easily. Note that some fields can be non-editable. This is because they are being used in some way (part of one key or index) and the idea is to warn you about that.

*Fields can be edited and you can specify their ''name'', ''type'', ''length'', ''decimals'', ''null-ability'', ''defaults'' and so on. Exactly the same for both ''keys'' and ''indexes''.

*Whilst editing statements, you must think about them like "collections of sentences". Once you select the ''type'' (only inserts are allowed for now) and ''table'' you are interested in, you'll be able to introduce the exact values easily, being able to ''duplicate'' them easily to gain some speed if you have a lot of sentences in your development. Sentences can be ''edited'' and ''deleted'' easily too.

*One interesting feature is that all the XMLDB editor pages allow you to enter a ''comment'' about the item being modified (table, index, key, field, statement). Use it as you wish, sure that it helps other developers to understand a bit more about the DB model.

*If you define a field as an '''enum''', you should provide the enum options as a comma-separated list, with each option surrounded by single quotes. Example: '''<code>'option1','option2','option3'</code>'''. However, enum has been deprecated in Moodle 2.0, so it is probably better just to avoid enum types altogether.

== Conventions ==

Apart from the [[Database| Database Structures guidelines]], some more conventions should be followed:

# About names:
## All lowercase names (tables, indexes, keys and fields).
## Table names and field names must use only a-z, 0-9 and _ chars. Max 28 characters.
## Key and index names under the XMLDB Files must be formed by concatenating the name of the fields present in the key/index with the '"-" (minus) character.
## Primary key always must be named "primary" (this is one exception to the previous convention).
## It's highly recommended to avoid [[XMLDB_reserved_words|reserved words]] completely. We know we have some of them now but they should be completely out for next releases.
# About NULLS
## Avoid to create all the fields as NOT NULL with the ''silly'' default value <nowiki>''</nowiki> (empty string). The underlying code used to create tables will handle it properly but the XMLDB structure must be REAL. Read more in the [[XMLDB Problems#NOT NULL fields using a DEFAULT <nowiki>''</nowiki> clause|Problems Page]].
# About FOREIGN KEYS
## Under the tables of every XMLDB file, you must define the existing '''Foreign Keys''' (FK) properly. This will allow everybody to know a bit better the structure, allow to evolve to a better constrained system in the future and will provide the underlying code with the needed info to create the proper indexes.
## Note that, if you define any field combination as FK you won't have to create any index on that fields, the code will do it automatically!
## This convention is only applicable for relations INSIDE one file. Don't generate FK constraints against other files (courseid, userid), use indexes there.
## Respect Convention 1.3
# About UNIQUE KEYS
## Declare any fields as UNIQUE KEY (UK) only if they are going to be used as target for one FK. Create unique indexes instead.
## Respect Convention 1.3

==See also==
*[[XMLDB defining an XML structure]]
*[[Installing and upgrading plugin database tables]]
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=82231 Using XMLDB editor] forum discussion
* [http://dev.moodle.org/mod/resource/view.php?id=55 Appendix B - The XMLDB Editor] from the Introduction to Moodle Programming course

[[Category:XMLDB]]
[[Category:DB]]

YUI/Shifter

2013-09-08T14:28:48Z

Gb2048: /* What is Shifter and what does it do? */

== What is Shifter and what does it do? ==

[http://yui.github.com/shifter Shifter] is a tool written by the YUI team to help ''build'' YUI modules.
It has been supported since Moodle 2.5 and we encourage it's use.

It is written in JavaScript itself, and written as a [http://nodejs.org Node.JS] module which can be installed from [https://npmjs.org/package/shifter NPM].

Shifter takes your source JavaScript file(s), along with some meta-data, and wraps it all together into a built file. This file is known in YUI parlance as a '''module'''.
After building this file, Shifter then produces three versions:
* the file in it's original form (DEBUG - '-debug' filename postfix);
* the DEBUG file with all debugging calls to Y.Log removed (RAW - no filename postfix); and
* the RAW file minified using [https://github.com/mishoo/UglifyJS UglifyJS] ('-min' filename postfix).

The meta-data file includes information on the module name, and it's dependencies on other modules.

By separating out the actual JS code from it's dependencies, we are able to take those dependencies and use them elsewhere in Moodle.
As an example, this dependency data can be used to inform the Loading system to reduce the number of HTTP requests with Combo Loading. This has a benefical effect upon performance.

Another feature of Shifter is it's ability to handle ''rollups''. Rollups describe the inclusion of multiple YUI classes in the same module. This means that you can have different but related components all in the same module, but without having a single large and less-managable source file.

=== Why do I need build my modules? ===

Technically you don't, and you can continue to use the old data structure, but by doing so you can benefit from:
* reduced data sent over the wire due to minification - great for slower connections and mobile devices;
* reduced number of http queries - the separation of module meta-data means that it can be consumed and fed into the Loader allowing your module to use combo-loading;
* a slightly simplified JS syntax for your source files.

== Installing Shifter ==

Shifter is written in JavaScript and the [http://nodejs.org Node.JS] environment. You will need to install Node.JS first. This is usually fairly easy as there are pre-built binary packages for '''Windows and Mac OS'''.

After installing Node.JS you then use the Node NPM tool to install Shifter:
npm install shifter@0.3.1 -g

Note: At present, the supported version of Shifter for use in Moodle is version ''0.3.1''. You are not ''required'' to run a specific version of Shifter, but this is the version that Moodle YUI modules will be built with and you may find it beneficial to do so too.

For '''Ubuntu''' run:

sudo apt-get install npm
sudo apt-get install python-software-properties python g++ make
sudo apt-get update
sudo apt-get install nodejs
sudo ln -s /usr/bin/nodejs /usr/local/bin/node
sudo npm install shifter@0.3.1 -g

== How do I write a YUI module which uses Shifter? ==

Easy - it's mostly just a case of building the right directory structure.

Assuming that you are creating a new YUI module in your block named fruit, and that your new YUI module will be called fruitbowl, we know the following:
{|
|Plugin type
|block
|-
|Plugin name
|fruit
|-
|Plugin frankenstyle name
|block_fruit
|-
|YUI Module name
|moodle-block_fruit-fruitbowl
|-
|}

This means that your Moodle plugin directory is:
/blocks/fruit

And your ''fruitbowl'' YUI module source will therefore be in:
/blocks/fruit/yui/src/fruitbowl

The overall module directory structure looks like this:
<code bash>
yui/
|-- src
|-- fruitbowl
|-- build.json
|-- js
| |-- fruitbowl.js
|-- meta
|-- fruitbowl.json
</code>

=== build.json ===

The ''build.json'' file defines the eventual modules which will be built, and the source files that you've written:

<code javascript>
{
"name": "moodle-block_fruit-fruitbowl",
"builds": {
"moodle-block_fruit-fruitbowl": {
"jsfiles": [
"fruitbowl.js"
]
}
}
}
</code>

=== meta/MODNAME.json ===

The ''meta/MODNAME.json'' file describes the list of dependencies for each module:

<code javascript>
{
"moodle-block_fruit-fruitbowl": {
"requires": [
"base",
"node"
]
}
}
</code>

=== js/MODNAME.js ===

The files in the js directory are the contents of your YUI module. This should include setting it up in the '''''M''''' namespace. As an example of a very basic structure:

<code javascript>
M.block_fruit = M.block_fruit || {};
M.block_fruit.fruitbowl = {
init: function() {
Y.one('#example').set('innerHTML', 'Example content');
}
};
</code>

== How do I use shifter? ==

So after writing out your structure, you now need to build it into a module. After installing Shifter, you have several options.

=== During development ===

A really nice way of running shifter during development is to have it detect changes to your files as you save them:

cd ~/git/moodle/blocks/fruit/src
shifter --watch

The '''--watch''' option will watch for any changes to JS, JSON, CSS, or images within any module in the current directory and build that module when it detects changes.
''Note: There can be a short delay of a few seconds while the changes are discovered and the file is built''

This is great for development because you don't have to continously run shifter manually.

=== All YUI modules for the Moodle plugin you're currently working on ===

If you are working on several YUI modules at once, then you can have shifter build all of them at the same time:

cd ~/git/moodle/blocks/fruit/src
shifter --walk

=== Just the module you're working on now ===
If you want to build just the module you're working on at the moment:

cd ~/git/moodle/blocks/fruit/src
shifter --walk fruitbowl

Or:

cd ~/git/moodle/blocks/fruit/src/fruitbowl
shifter

=== Across the whole of Moodle ===
If you want to build every YUI module in Moodle at once:

cd ~/git/moodle
shifter --walk --recursive

== Submitting my JavaScript back to Moodle core ==

If you're working on some JavaScript for Moodle core, either in the form of a bug fix or a new feature, then you probably want to know what to do with your built module.

'''We ask that you build your module and submit both the changes to tbe built module and the source directory.'''

In addition, the Continuous Integration server (Jenkins) will run ''shifter --walk --recursive'' on every run to ensure that all built files are up-to-date and correct.

If there are several commits to the same YUI module within a single period of Moodle integration, then the built files will conflict. In this case the integration team will manually build the module and resolve the conflict. If you are aware that there may be multiple changes to the same file, please indicate this when submitting your change for Integration Review. If you are familiar with the changes, you may wish to consider building the issues upon one another too.

== How do I convert my existing module? ==

If you already have an existing moodle YUI module and want to convert it to the new Shifter format, then it's pretty easy on the whole:

# create a new src/MODNAME directory;
# create js and meta directories within this;
# copy over your existing js file into the js directory;
# extract the meta-data;
# write your build.json;
# remove the YUI.add() wrapper from the top and bottom of your js file; and
# remove the old file.

To create the complete directory structure and copy your existing code into the right directory (steps 1 - 3):

mkdir -p src/MODNAME/{js,meta}
cp MODNAME/MODNAME.js src/MODNAME/js/

Refer to the section above on the correct contents of the build.json and meta/MODNAME.json files.

== Can I run my shifted module in older versions of Moodle 2? ==

We are aware that many developers wish to reduce the overhead of maintaining a plugin for multiple versions of Moodle and that using Shifter will make this much harder. Unfortunately you can't use the shifted version of your module directly, but you can run them in parallel by copying the built file into the old directory structure.

Moodle will always ''prefer'' the built shifted module over the older style module if both are present.

If doing this, we would recommend copying over the minified version of your file so that older versions of moodle benefit from your user of shifted code.

On a Linux-like operating system, you can use the following (again with our fruit example):
cp yui/build/moodle-mod_fruit-fruitbowl/moodle-mod_fruit-fruitbowl-min.js yui/fruitbowl/fruitbowl.js

Whilst developing, you may want to use a symlink so that you don't have to keep copying your changes after building them:
ln -s yui/build/moodle-mod_fruit-fruitbowl/moodle-mod_fruit-fruitbowl.js yui/fruitbowl/fruitbowl.js

==See also==

* [[JavaScript guidelines]]

YUI/Modules

2013-07-06T16:25:43Z

Gb2048: /* Including your module from your PHP code */

{{draft}}
{{Work in progress}}
{{Moodle 2.5}}

== YUI modules ==

You may want to [[#Additional_functions_instead_of_anonymous_functions|Jump straight to the complete example]].

=== What is a module and why would I want to use one? ===

Many people are used to writing their JavaScript code either inline, or in a
separate file included using <script> tags in their HTML. Although both of
these are supported within Moodle, we highly recommend investing a little
time in looking into the [[YUI]] module system as it offers some really great
features which will benefit you in the long run.

These features and benefits include:
* a host of existing modules that you can hook into and use; which offer
* code sandboxing to ensure that you always have a good/clean copy of the code; with
* powerful dependency management; which can utilise
* asynchronous loading to load dependencies in parallel; and
* loading of dependencies in any order (you don't have to include script tags in a set order); and
* separation of loading from execution; and
* combo loading to reduce the number of individual HTTP transactions.

By using existing modules in your code, you can benefit in other ways too, such as:
* a consistent look and feel across Moodle; and
* most of the edge cases already catered for.

The Moodle community is in the process of improving much of its JavaScript
in areas such as code, documentation, and processes. This includes updating
older code, adding documentation, seeding dependency information for
modules to improve load efficiency for browsers, and much more.

You may find the following resources particularly helpful:
* [[YUI]]; and
* [[Javascript/Shifter]].

=== Structure and naming ===

A YUI module is structured in a particular way, both on file, and in the
file itself. Before you start writing your module, you need to know a few
bits of information:
* what is the [[Frankenstyle]] name of your Moodle plugin;
* what does your YUI module do in a single word.

You can use these pieces of information to work out the namespace for your
plugin. This namespace fits into the template:

moodle-FRANKENSTYLE-MODULENAME

As an example, writing a plugin for the fictional ''''fruit'''' '''block''' which
offers fruit to users:
* you may decide to call this module the ''''fruitbowl'''' as the module offers fruit to users, and presents it in an appealing way so that they can see it.
* The block is fruit, therefore the frankenstyle name is block_fruit.

Therefor the name for this module will be:

moodle-block_fruit-fruitbowl

The other thing that you need to know in order to create your first module
is where in your plugin the code needs to be.

As described in the [[Javascript/Shifter#How_do_I_write_a_YUI_module_which_uses_Shifter.3F]] documentation, the code will need to go in your plugin directory inside a yui directory.

Since Moodle 2.5, the structure for this directory is:
<code bash>
yui/
|-- src
|-- fruitbowl
|-- build.json
|-- js
| |-- fruitbowl.js
|-- meta
|-- fruitbowl.json
</code>
''Note: Moodle 2.5 onwards is backwards compatibly with the previous structure.''

So in the case of moodle-block_fruit-fruitbowl, the JavaScript code will need to go into:
/block/fruit/yui/src/fruitbowl/js/fruitbowl.js

(Sorry, it does look a little more complicated than it really is)

See the notes in the [[Javascript/Shifter#How_do_I_write_a_YUI_module_which_uses_Shifter.3F|Shifter]] documentation for details on the build.json and meta/MODULENAME.json file contents.

Now that you know where your code needs to be on disk, you can actually include and write it.

=== Including your module from your PHP code ===

Rather than using <script> tags to include JavaScript code, Moodle makes
use of the YUI loader and a single inline script tag in the page footer.

Moving JavaScript to a page footer is important to the perceived performance of a page, and the YUI loader helps further.

The YUI loader also intelligiently loads page dependencies, in as few
requests as possible by making use of a combo-loader system.
It will also attempt to use the appropriate version of your JavaScript
depending on your $CFG->jsrev settings. In normal operation, a minified
version of your code is used; and with $CFG->jsrev is set to a value of
'-1' or $CFG->cachejs is false, then a debugging version is used.

To ensure that your module is loaded, there is a '''yui_module()'''
function on the page requirements class. This can be accessed using:

<code php>
$PAGE->requires->yui_module();
// or:
$this->page->requires->yui_module();
</code>

The yui_module function takes the module name, and the init function to
call as it's first two arguments, and an optional list of arguments as a
third argument:

<code php>
$PAGE->requires->yui_module('moodle-block_fruit-fruitbowl',
'M.block_fruit.fruitbowl.init');
</code>

==== Passing arguments from your PHP to your module ====

You may want to pass a set of arguments to your JavaScript. You can do so
using the optional third argument to yui_module which accepts an array of
arguments.

<code php>
$PAGE->requires->yui_module('moodle-block_fruit-fruitbowl',
'M.block_fruit.fruitbowl.init',
array(
'value1',
'value2',
));
</code>

These will be presented to the JavaScript function you name:

<code javascript>
init = function(argument1, argument2) {
// Use the arguments here.
};
</code>

Often it makes more sense to pass a single argument with an associative array:

<code php>
$PAGE->requires->yui_module('moodle-block_fruit-fruitbowl',
'M.block_fruit.fruitbowl.init',
array(array(
'key1' => 'value1',
'key2' => 'value2',
)));
</code>

These will be presented to the JavaScript function you name:

<code javascript>
init = function(params) {
// Use the arguments through params.key1 and params.key2.
};
</code>

=== A basic module ===

The most common use-case for JavaScript in Moodle is to utilise existing
modules to do something. Your module isn't intended to be reused, or
extended by some other piece of code. In these cases, you want to keep
things simple.

This section will build up the YUI module gradually, but you can cheat and skip to the [[#Additional_functions_instead_of_anonymous_functions|completed example]].

==== Namespacing ====

One of the great benefits of using YUI is the ability to sandbox code in
such a way that you can be sure that it won't interfere with other JS code
in Moodle, this is done by placing your object in a JavaScript object.
Using our fictitious example, this namespace is very similar to the module
name namespace:

M.FRANKENSTYLE.MODNAME

As a JavaScript object this would look like:

<code bash>
M: {
FRANKENSTYLE: {
MODNAME: {
// Your code and functions go here.
}
}
}
</code>

The easiest way of creating this structure is by using the logical OR operator.

<code javascript>
M.block_fruit = M.block_fruit || {};
M.block_fruit.fruitbowl = {};
var NS = M.block_fruit.fruitbowl;
</code>

This ensures that any existing code on the M.block_fruit object is not
inadvertently overwritten, but also ensures that the definition for the
fruitbowl code is clean.

That's to say that, if you have already used your fruitbowl code once on
the page, and have modified it in some way (for example to override a
function), then the next time it is used, it will be in it's original state
with the original function.

==== Initialisation ====

Once you have your namespace, you'll want to create one or more functions on this namespace in which to put your code. Typically, we use an 'init' function to perform the initial setup.
The amount that this code does should be kept to a minimum because every
piece of JavaScript which has to be executed at page load is a piece of
code slowing the page down. As a best practice:
* don't modify the DOM unless you need to do so;
* don't create anything you aren't using immediately (for example a JS dialogue hidden until first used); and
* use event delegation where possible.

<code javascript>
M.block_fruit = M.block_fruit || {};
var NS = M.block_fruit.fruitbowl = {};

NS.init = function() {
Y.delegate('click', function(e) {
// Alert users when they've clicked on some fruit to tell them the obvious.
alert("You clicked on some fruit");

// Add a border to the fruit so we can see that it was selected.
e.setStyle('border', '1px solid black');
}, Y.config.doc, '.fruit');
};
</code>

==== Separation of code from configuration and style (loose coupling) ====

As another best practice, we encourage you to separate out the code from
configuration, and not to apply any CSS styles directly. Instead, use
techniques to move the configuration out of the code itself and into
variables or attributes, and use CSS classes which the theme can modify.

Typically to make it easier to read your code, and to modify it later, we
recommend creating two static objects at the top of your code: one for CSS
selectors, and one for CSS class names.
<code javascript>
var CSS = {
FRUIT: 'fruit',
SELECTED: 'selected'
},
SELECTORS = {
FRUIT: '.' + CSS.FRUIT
},
NS;

M.block_fruit = M.block_fruit || {};
NS = M.block_fruit.fruitbowl = {};

NS.init = function() {
Y.delegate('click', function() {
// Alert users when they've clicked on some fruit to tell them the obvious.
alert("You clicked on some fruit");

// Apply the relevant class which contains indications that this fruit was selected.
e.target.addClass(CSS.SELECTED);
}, Y.config.doc, SELECTORS.FRUIT, this);
};
</code>

With this change, if at a later date you need to change the styling on a
selected fruit, this can be done in the theme. An alternative theme can
also choose to theme the same item in a completely different way.

It also means that if you need to change the class names, you can do so
once in the JavaScript without making it difficult to work out the purpose
of a particular line of code from git.

==== Additional functions instead of anonymous functions ====

Although it's often quicker to write an inline anonymous function when
you write your event handlers, loops, and at other times, it's often much
easier to read the code if you move it to a function on your namespace and
call it accordingly.

<code javascript>
var CSS = {
FRUIT: 'fruit',
SELECTED: 'selected'
},
SELECTORS = {
FRUIT: '.' + CSS.FRUIT
},
NS;

M.block_fruit = M.block_fruit || {};
NS = M.block_fruit.fruitbowl = {};

NS.init = function() {
Y.delegate('click', this.handle_selection, Y.config.doc, SELECTORS.FRUIT, this);
};

NS.handle_selection = function(e) {
// Alert users when they've clicked on some fruit to tell them the obvious.
alert("You clicked on some fruit");

// Apply the relevant class which contains indications that this fruit was selected.
e.target.addClass(CSS.SELECTED);
};
</code>

Now you can clearly see your what your initialiser does, and you can call handle_selection for other events too without duplicating code.

=== A re-usable module ===

{{Work in progress}} This section of documentation has yet to be written.

=== Notes ===

There is a proposal to [[YUI/Namespacing|alter the namespace]] for YUI modules. This is likely to be implemented from Moodle 2.6

Themes overview

2013-04-17T15:52:34Z

Gb2048: /* The different layouts as of 17th August 2010 */

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

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

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

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

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

===HTML 5 doctype===

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

===Internet Explorer standards mode===

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

===SVG icons===

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

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

==What's new in 2.0==

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

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

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

==The structure of a theme==

Some important things to know when building good themes:

# '''config.php''' - this file is required in every theme. It defines configuration settings and definitions required to make the theme work in Moodle. These include theme, file, region, default region and options.
# '''Layouts and layout files''' - in config.php there is one definition for each page type (see [[#theme_layouts_table|Appendix A: Theme layouts]] for a list of over 12 types). Each page type definition tells Moodle which layout file will be used, what block regions this page type should display and so on. The layout file contains the HTML and the minimum PHP required to display basic structure of pages. (If you know Moodle 1.9, it's like a combination of header.html and footer.html).
# '''The base theme''' - is not intended to be used for production sites. It sets up the simplest possible generic layout and includes only CSS essential to that layout ''or'' to Moodle as a whole. It tries not to make any unnecessary rules and makes as few assumptions as possible. It's the perfect base on which to start designing a theme, as there are very few colours, borders, margins, and alignments to override. You can just start adding what you need.

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

{| class="nicetable"
|-
! Directory
! File
! Description
|-
|
| /config.php
| Contains all of the configuration and definitions for each theme
|-
|
| /lib.php
| Contains speciality classes and functions that are used by theme
|-
|
| /renderers.php
| Contains any custom renderers for the theme.
|-
|
| /settings.php
| Contains custom theme settings. These local settings are defined by the theme allowing the theme user to easily alter something about the way it looks or operates. (eg a background colour, or a header image)
|-
| /javascript/
|
| All specialty JavaScript files the theme requires should be located in here.
|-
| /lang/
|
| Any special language files the theme requires should be located in here.
|-
| /layout/
|
| Contains the layout files for the theme.
|-
| /pix/
|
| Contains any images the theme makes use of either in CSS or in the layout files.
|-
| /pix
| /favicon.ico
| The favicon to display for this theme.
|-
| /pix
| /screenshot.jpg
| A screenshot of the theme to be displayed in on the theme selection screen.
|-
| /style
|
| Default location for CSS files.
|-
|
|/*.css
|CSS files the theme requires
|}

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

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

===Basic theme config example===
Lets have a look at a basic theme configuration file and the different bits that make it up:
<code php>
$THEME->name = 'newtheme';

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

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

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

$THEME->javascripts_footer = array(
'navigation'
);
</code>

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

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

; $THEME->parents : This defines the themes that the theme will extend. In this case it is extending only the base theme.

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

; $THEME->layouts : In this example, two layouts have been defined to override the layouts from the base theme. For more information see the [[#Layouts|layouts]] section below.

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

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

==CSS==
===Locations of CSS files===
First lets look at where CSS can be included from within Moodle:
; \theme\themename\style\*.css : This is the default location for all of the stylesheets that are used by a theme and the place which should be used by a theme designer.

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

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

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

As theme designers, we will only use the first method of introducing CSS: adding rules to a stylesheet file located in the theme's style directory.

===Moodle's core CSS organisation===
The next thing to look at is the organisation of CSS and rules within a theme. Although as a theme designer it is entirely up to you as to how you create and organise your CSS. Please note that within the themes provided in the standard install by Moodle there is a very clear organisation of CSS.

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

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

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

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

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

===How to write effective CSS rules within Moodle===
In Moodle 2.0, writing good CSS rules is incredibly important.

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

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

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

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

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

What does all of this look like in practise? Well using the above example /mod/forum/view.php you would get at least the following body tag:
<code html4strict><body id=”page-mod-forum-view” class=”path-mod path-mod-forum” /></code>

====Writing your rules====

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

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

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

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

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

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

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

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

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

It is also important to note that a new theme that will base itself on another theme (overriding it) does not need to define any layouts or use any layout files if there are no changes that it wishes to make to the layouts of the existing theme. The standard theme in Moodle is a good example of this as it extends the base theme simply adding CSS to achieve its look and feel.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==Language File==

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

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

<code php>
$string['pluginname'] = 'Standard';
$string['region-side-post'] = 'Right';
$string['region-side-pre'] = 'Left';
$string['choosereadme'] = 'This theme is a very basic white theme, with a minimum amount of
CSS added to the base theme to make it actually usable.';
</code>

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

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

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

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

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

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

The following code snippet illustrates how to make use of your images within HTML, such as if you wanted to use them within a layout file.
<code php>
<img src="<?php echo $OUTPUT->pix_url('imageone', 'theme');?>" alt="" />
<img src="<?php echo $OUTPUT->pix_url('subdir/imagetwo', 'theme');?>" alt="" />
</code>

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

In this case rather than writing out the URL to the image we use a method of Moodle's output library. Its not too important how that functions works but it is important that we use it as it is what allows images within Moodle to be over-rideable.

The following is how you would use the images from within CSS as background images.
<code css>
.divone {
background-image: url([[pix:theme|imageone]]);
}

.divtwo {
background-image: url([[pix:theme|subdir/imagetwo]]);
}
</code>
If this case we have to use some special notations that Moodle looks for. Whenever Moodle hands out a CSS file it first searches for all ''[[something]]'' tags and replaces them with what is required.

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

From within a theme you can VERY easily override any standard image within Moodle by simply adding the replacement image to the theme's pix directory in the same sub directory structure as it is in Moodle.
So for instance we wanted to override the following two images:
# /pix/moodlelogo.gif
# /pix/i/user.gif
We would simply need to add our replacement images to the theme in the following locations
# /theme/themename/pix_core/moodlelogo.gif
# /theme/themename/pix_core/i/user.gif
''Note that we have created a '''pix_core''' directory in our theme. For module images we need a '''pix_mod''' directory. See [[Themes_2.0_How_to_use_images_within_your_theme|using images within your theme]] for the full story.

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

For a more detailed description of how this all works see the page on [[Themes_2.0_How_to_use_images_within_your_theme|using images within your theme]]

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

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

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

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

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

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

===Required theme divs===

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

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

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

==Appendix A==
===Theme options as of 17th April 2013===
{| class="nicetable" id="theme_options_table"
|-
! Setting
! Effect
|-
| $THEME->'''csspostprocess'''
| Allows the user to provide the name of a function that all CSS should be passed to before being delivered.
|-
| $THEME->'''editor_sheets'''
| An array of stylesheets to include within the body of the editor.
|-
| $THEME->'''enable_dock'''
| If set to true the side dock is enabled for blocks
|-
| $THEME->'''hidefromselector'''
| Used to hide a theme from the theme selector (unless theme designer mode is on). Accepts true or false.
|-
| $THEME->'''filter_mediaplugin_colors'''
| Used to control the colours used in the small media player for the filters
|-
| $THEME->'''javascripts'''
| An array containing the names of JavaScript files located in /javascript/ to include in the theme. (gets included in the head)
|-
| $THEME->'''javascripts_footer'''
| As above but will be included in the page footer.
|-
| $THEME->'''larrow'''
| Overrides the left arrow image used throughout Moodle
|-
| $THEME->'''layouts'''
| An array setting the layouts for the theme
|-
| $THEME->'''name'''
| Name of the theme. Most likely the name of the directory in which this file resides.
|-
| $THEME->'''parents'''
| An array of themes to inherit from
|-
| $THEME->'''parents_exclude_javascripts'''
| An array of JavaScript files NOT to inherit from the themes parents
|-
| $THEME->'''parents_exclude_sheets'''
| An array of stylesheets not to inherit from the themes parents
|-
| $THEME->'''plugins_exclude_sheets'''
| An array of plugin sheets to ignore and not include.
|-
| $THEME->'''rarrow'''
| Overrides the right arrow image used throughout Moodle
|-
| $THEME->'''renderfactory'''
| Sets a custom render factory to use with the theme, used when working with custom renderers.
|-
| $THEME->'''resource_mp3player_colors'''
| Controls the colours for the MP3 player
|-
| $THEME->'''sheets'''
| An array of stylesheets to include for this theme. Should be located in the theme's style directory.
|-
| $THEME->'''supportscssoptimisation'''
| When set to 'FALSE' then the theme will not be affected by the 'CSS Optimiser'. The 'CSS Optimiser' is enabled in Development > Experimental > Experimental settings. When it is enabled CSS will be run through an optimisation process before being cached. The optimiser processes the CSS removing duplicate rules and styles, as well as white space removable and reformatting. Please note turning this on at the same time as theme designer mode is awful for performance but will help theme designers create optimised CSS.
|}

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

==See also==
* [[Theme changes in 2.0]]
* [[Themes 2.0 creating your first theme]] - A quick step by step guide to creating your first theme.
* [[Themes 2.0 how to clone a Moodle 2.0 theme]]
* [[Themes 2.0 How to use images within your theme]] - Explains how to use and override images within your theme.
* [[Themes 2.0 adding a settings page]] - Looks at how to add a setting page making your theme easily customisable.
* [[Themes 2.0 extending the custom menu]] - Customising the custom menu.
* [[Themes 2.0 overriding a renderer]] - A tutorial on creating a custom renderer and changing the HTML Moodle produces.
* [[Themes 2.0 adding courses and categories to the custom menu]] - Extending the custom menu further adding all categories + courses
* [[Themes 2.0 how to make the dock horizontal]] - Modifying the dock to make it horizontal.
* [[Themes 2.0 adding upgrade code]]
* [[Styling and customising the dock]] - How to style and customise the dock.
* [[Themes 2.0 How to change 'Topic outline' and 'Weekly outline' to Page heading]]
* [[Using jQuery with Moodle 2.0]]
* [http://www.youtube.com/watch?v=OvaU54uh-qA New themes in Moodle 2.0 video]
===Moodle 2.2+===

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

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

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

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

[[Category:Plugins]]

Themes overview

2013-04-17T15:51:40Z

Gb2048: /* Theme options as of 17th April 2013 */

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

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

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

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

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

===HTML 5 doctype===

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

===Internet Explorer standards mode===

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

===SVG icons===

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

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

==What's new in 2.0==

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

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

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

==The structure of a theme==

Some important things to know when building good themes:

# '''config.php''' - this file is required in every theme. It defines configuration settings and definitions required to make the theme work in Moodle. These include theme, file, region, default region and options.
# '''Layouts and layout files''' - in config.php there is one definition for each page type (see [[#theme_layouts_table|Appendix A: Theme layouts]] for a list of over 12 types). Each page type definition tells Moodle which layout file will be used, what block regions this page type should display and so on. The layout file contains the HTML and the minimum PHP required to display basic structure of pages. (If you know Moodle 1.9, it's like a combination of header.html and footer.html).
# '''The base theme''' - is not intended to be used for production sites. It sets up the simplest possible generic layout and includes only CSS essential to that layout ''or'' to Moodle as a whole. It tries not to make any unnecessary rules and makes as few assumptions as possible. It's the perfect base on which to start designing a theme, as there are very few colours, borders, margins, and alignments to override. You can just start adding what you need.

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

{| class="nicetable"
|-
! Directory
! File
! Description
|-
|
| /config.php
| Contains all of the configuration and definitions for each theme
|-
|
| /lib.php
| Contains speciality classes and functions that are used by theme
|-
|
| /renderers.php
| Contains any custom renderers for the theme.
|-
|
| /settings.php
| Contains custom theme settings. These local settings are defined by the theme allowing the theme user to easily alter something about the way it looks or operates. (eg a background colour, or a header image)
|-
| /javascript/
|
| All specialty JavaScript files the theme requires should be located in here.
|-
| /lang/
|
| Any special language files the theme requires should be located in here.
|-
| /layout/
|
| Contains the layout files for the theme.
|-
| /pix/
|
| Contains any images the theme makes use of either in CSS or in the layout files.
|-
| /pix
| /favicon.ico
| The favicon to display for this theme.
|-
| /pix
| /screenshot.jpg
| A screenshot of the theme to be displayed in on the theme selection screen.
|-
| /style
|
| Default location for CSS files.
|-
|
|/*.css
|CSS files the theme requires
|}

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

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

===Basic theme config example===
Lets have a look at a basic theme configuration file and the different bits that make it up:
<code php>
$THEME->name = 'newtheme';

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

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

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

$THEME->javascripts_footer = array(
'navigation'
);
</code>

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

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

; $THEME->parents : This defines the themes that the theme will extend. In this case it is extending only the base theme.

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

; $THEME->layouts : In this example, two layouts have been defined to override the layouts from the base theme. For more information see the [[#Layouts|layouts]] section below.

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

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

==CSS==
===Locations of CSS files===
First lets look at where CSS can be included from within Moodle:
; \theme\themename\style\*.css : This is the default location for all of the stylesheets that are used by a theme and the place which should be used by a theme designer.

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

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

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

As theme designers, we will only use the first method of introducing CSS: adding rules to a stylesheet file located in the theme's style directory.

===Moodle's core CSS organisation===
The next thing to look at is the organisation of CSS and rules within a theme. Although as a theme designer it is entirely up to you as to how you create and organise your CSS. Please note that within the themes provided in the standard install by Moodle there is a very clear organisation of CSS.

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

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

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

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

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

===How to write effective CSS rules within Moodle===
In Moodle 2.0, writing good CSS rules is incredibly important.

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

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

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

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

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

What does all of this look like in practise? Well using the above example /mod/forum/view.php you would get at least the following body tag:
<code html4strict><body id=”page-mod-forum-view” class=”path-mod path-mod-forum” /></code>

====Writing your rules====

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

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

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

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

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

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

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

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

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

It is also important to note that a new theme that will base itself on another theme (overriding it) does not need to define any layouts or use any layout files if there are no changes that it wishes to make to the layouts of the existing theme. The standard theme in Moodle is a good example of this as it extends the base theme simply adding CSS to achieve its look and feel.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

==Language File==

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

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

<code php>
$string['pluginname'] = 'Standard';
$string['region-side-post'] = 'Right';
$string['region-side-pre'] = 'Left';
$string['choosereadme'] = 'This theme is a very basic white theme, with a minimum amount of
CSS added to the base theme to make it actually usable.';
</code>

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

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

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

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

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

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

The following code snippet illustrates how to make use of your images within HTML, such as if you wanted to use them within a layout file.
<code php>
<img src="<?php echo $OUTPUT->pix_url('imageone', 'theme');?>" alt="" />
<img src="<?php echo $OUTPUT->pix_url('subdir/imagetwo', 'theme');?>" alt="" />
</code>

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

In this case rather than writing out the URL to the image we use a method of Moodle's output library. Its not too important how that functions works but it is important that we use it as it is what allows images within Moodle to be over-rideable.

The following is how you would use the images from within CSS as background images.
<code css>
.divone {
background-image: url([[pix:theme|imageone]]);
}

.divtwo {
background-image: url([[pix:theme|subdir/imagetwo]]);
}
</code>
If this case we have to use some special notations that Moodle looks for. Whenever Moodle hands out a CSS file it first searches for all ''[[something]]'' tags and replaces them with what is required.

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

From within a theme you can VERY easily override any standard image within Moodle by simply adding the replacement image to the theme's pix directory in the same sub directory structure as it is in Moodle.
So for instance we wanted to override the following two images:
# /pix/moodlelogo.gif
# /pix/i/user.gif
We would simply need to add our replacement images to the theme in the following locations
# /theme/themename/pix_core/moodlelogo.gif
# /theme/themename/pix_core/i/user.gif
''Note that we have created a '''pix_core''' directory in our theme. For module images we need a '''pix_mod''' directory. See [[Themes_2.0_How_to_use_images_within_your_theme|using images within your theme]] for the full story.

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

For a more detailed description of how this all works see the page on [[Themes_2.0_How_to_use_images_within_your_theme|using images within your theme]]

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

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

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

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

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

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

===Required theme divs===

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

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

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

==Appendix A==
===Theme options as of 17th April 2013===
{| class="nicetable" id="theme_options_table"
|-
! Setting
! Effect
|-
| $THEME->'''csspostprocess'''
| Allows the user to provide the name of a function that all CSS should be passed to before being delivered.
|-
| $THEME->'''editor_sheets'''
| An array of stylesheets to include within the body of the editor.
|-
| $THEME->'''enable_dock'''
| If set to true the side dock is enabled for blocks
|-
| $THEME->'''hidefromselector'''
| Used to hide a theme from the theme selector (unless theme designer mode is on). Accepts true or false.
|-
| $THEME->'''filter_mediaplugin_colors'''
| Used to control the colours used in the small media player for the filters
|-
| $THEME->'''javascripts'''
| An array containing the names of JavaScript files located in /javascript/ to include in the theme. (gets included in the head)
|-
| $THEME->'''javascripts_footer'''
| As above but will be included in the page footer.
|-
| $THEME->'''larrow'''
| Overrides the left arrow image used throughout Moodle
|-
| $THEME->'''layouts'''
| An array setting the layouts for the theme
|-
| $THEME->'''name'''
| Name of the theme. Most likely the name of the directory in which this file resides.
|-
| $THEME->'''parents'''
| An array of themes to inherit from
|-
| $THEME->'''parents_exclude_javascripts'''
| An array of JavaScript files NOT to inherit from the themes parents
|-
| $THEME->'''parents_exclude_sheets'''
| An array of stylesheets not to inherit from the themes parents
|-
| $THEME->'''plugins_exclude_sheets'''
| An array of plugin sheets to ignore and not include.
|-
| $THEME->'''rarrow'''
| Overrides the right arrow image used throughout Moodle
|-
| $THEME->'''renderfactory'''
| Sets a custom render factory to use with the theme, used when working with custom renderers.
|-
| $THEME->'''resource_mp3player_colors'''
| Controls the colours for the MP3 player
|-
| $THEME->'''sheets'''
| An array of stylesheets to include for this theme. Should be located in the theme's style directory.
|-
| $THEME->'''supportscssoptimisation'''
| When set to 'FALSE' then the theme will not be affected by the 'CSS Optimiser'. The 'CSS Optimiser' is enabled in Development > Experimental > Experimental settings. When it is enabled CSS will be run through an optimisation process before being cached. The optimiser processes the CSS removing duplicate rules and styles, as well as white space removable and reformatting. Please note turning this on at the same time as theme designer mode is awful for performance but will help theme designers create optimised CSS.
|}

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

==See also==
* [[Theme changes in 2.0]]
* [[Themes 2.0 creating your first theme]] - A quick step by step guide to creating your first theme.
* [[Themes 2.0 how to clone a Moodle 2.0 theme]]
* [[Themes 2.0 How to use images within your theme]] - Explains how to use and override images within your theme.
* [[Themes 2.0 adding a settings page]] - Looks at how to add a setting page making your theme easily customisable.
* [[Themes 2.0 extending the custom menu]] - Customising the custom menu.
* [[Themes 2.0 overriding a renderer]] - A tutorial on creating a custom renderer and changing the HTML Moodle produces.
* [[Themes 2.0 adding courses and categories to the custom menu]] - Extending the custom menu further adding all categories + courses
* [[Themes 2.0 how to make the dock horizontal]] - Modifying the dock to make it horizontal.
* [[Themes 2.0 adding upgrade code]]
* [[Styling and customising the dock]] - How to style and customise the dock.
* [[Themes 2.0 How to change 'Topic outline' and 'Weekly outline' to Page heading]]
* [[Using jQuery with Moodle 2.0]]
* [http://www.youtube.com/watch?v=OvaU54uh-qA New themes in Moodle 2.0 video]
===Moodle 2.2+===

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

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

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

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

[[Category:Plugins]]

Talk:Hack-a-thon 2013

2013-02-23T11:37:51Z

Gb2048: Created page with "With reference to https://moodle.org/mod/forum/discuss.php?d=222697 - could there be a task for plugins to remove theme specific css? Also for contributed plugin's, how about 'c..."

With reference to https://moodle.org/mod/forum/discuss.php?d=222697 - could there be a task for plugins to remove theme specific css?

Also for contributed plugin's, how about 'code checking'(https://moodle.org/plugins/view.php?plugin=local_codechecker) the latest version, cleaning it and getting the author to make an update? Say 3 points for every plugin updated, verified by the author and T-Shirt for every two plugins cleaned, verified and updated on the plugin's / add-on's database?

--[[User:Gareth Barnard|Gareth Barnard]] 19:37, 23 February 2013 (WST)

Course formats

2013-02-05T11:31:12Z

Gb2048: /* Creating a New Format */

Course formats are plugins that determine the layout of [[:en:Course|course]] resources.

Course formats determine how the course main page looks like (/course/view.php) in both view and editing mode. They are also responsible for building navigation tree inside the course (displayed to user in navigation block and breadcrumb). They can organise the course content in sections. Course creator or teacher can specify course format for the course in course edit form.

Moodle 2.4 and above: Course formats also can add it's own options fields to the course edit form. They can add course dependend content to header/footer of any page inside the course, not only /course/view.php

=Components=

'''course/format/FORMATNAME/lang/en/format_FORMATNAME.php'''

Contains the English language strings used in the format. You can also define strings for other languages.

'''course/format/FORMATNAME/config.php''' (deprecated since 2.4)

Contains $format['defaultblocks'] which defines the default blocks loaded with the format.

'''course/format/FORMATNAME/format.php'''

This is is the layout itself. It is included in course/view.php.

'''course/format/FORMATNAME/lib.php'''

The main library of the format. In Moodle versions up to 2.3 it should contain implementations of course format callbacks. In versions 2.4 and above it should contain a class format_FORMATNAME extending format_base. Also it may contain callbacks for other core and contributed APIs if necessary

'''course/format/FORMATNAME/styles.css''', '''styles_THEMENAME.css'''

Optional stylesheet. Note that this file is included on all pages on the site, even in the courses that use other formats. In 2.4+ the class format-FORMATNAME is automatically added to body for all pages inside the course, it is recommended to prefix all directives in your styles.css with body.format-FORMATNAME

File styles.css will be included always, styles_THEMENAME.css only if theme_THEMENAME is used for the site (or for the course).

'''course/format/FORMATNAME/settings.php''' (version 2.4 and above)

Optional plugin administrative settings. See "Individual settings" in [[Admin settings]]

'''course/format/FORMATNAME/renderer.php'''

Optional but very recommended file containing renderer for this course format. This file will contain ''class format_FORMATNAME_renderer extends plugin_renderer_base''. See [[Output renderers]]

Since course format is all about the display it is very important to separate HTML and PHP. All HTML code should be in your format_FORMATNAME_renderer class in renderer.php. Ideally format.php will only call one function from renderer. Use of renderer is required if you want to output content header and footer.

'''course/format/FORMATNAME/version.php'''

Version definitions, see [[version.php]]. It is highly recommended always to have it and it is required if you have any files in db folder

'''course/format/db/install.xml''', '''course/format/db/install.php''', '''course/format/db/upgrade.php'''

Definitions of tables used by this plugin and upgrade script, see [[Upgrade API]]

'''course/format/backup/'''

Implementation of backup and restore for additional tables defined in your plugin. See [[Backup API]]. This is only needed if you define additional tables in your db folder. Data from table course_format_options is backed up for your plugin automatically

'''course/format/db/access.php'''

Capabilities introduced by this plugin, see [[Access API]]. Please note that if you define new capabilities inside course format they should not affect accessibility of course modules because other components (for example reports and/or gradebook) will not know about them

'''Javascript and YUI files'''

Also course format may contain Javascript files and/or YUI modules. See [[:Category:Javascript]] for documentation. Make sure that course format checks course_ajax_enabled() before including AJAX libraries

=Creating a New Format=
The easiest way to create a new course format is to copy an existing one.

1. Copy the folder containing the format files.

2. Rename the folder to the new name. Course format names cannot exceed 21 characters. (In Moodle 2.3 and below the limit is 10 characters)

3. Rename language files in ''course/format/FORMATNAME/lang/''

4. Change ''$string['pluginname']'' in ''course/format/FORMATNAME/lang/en/format_FORMATNAME.php'' to the new name.

5. Moodle 2.3 and below: Rename callback functions in lib.php. The names of the functions is formed as callback_FORMATNAME_CALLBACKNAME()

Moodle 2.4 and above: Rename class name in lib.php to format_FORMATNAME.

6. Search and replace other occurences of the old format name, for example in renderer, capabilities names, settings, javascript libraries, etc.

7. The new format is ready for modification.

8. After modifying the code, check it with the 'Code checker [https://moodle.org/plugins/view.php?plugin=local_codechecker]'.

=Upgrading format to the next Moodle version=

Read the files course/format/upgrade.txt, lib/upgrade.txt and also upgrade.txt of the core APIs that you use in your course format plugin and make changes according to them. When testing don't forget to enable Developer debugging level and error display (Settings->Developer->Debugging)

If you upgrade your course format plugin from Moodle 2.3 to Moodle 2.4 - copy class format_legacy to your lib.php and rename it to format_FORMATNAME. Then go through the class functions and replace calling of functions with the corresponding callbacks' code. Move blocks list from config.php to the function format_FORMATNAME::get_default_blocks()

=Developing course formats for Moodle 2.4 and above=

File lib.php in your course format will contain ''class format_FORMATNAME extends format_base''. The parent class is located in course/format/lib.php and has detailed PHPdocs for each functions that you can override. Some functions are defined as ''final'' and you can not override them. Some functions such as get_course(), get_format_options(), update_format_options() and get_renderer() usually do not need to be overriden unless you know exactly what you are doing.

Here are the main features in course formats and responsible for them format_base functions

==Course sections==

There is existing functionality in Moodle core to support organising course modules into sections. Course format plugins do not have to use them but the most of them do. Database table {course_sections} stores basic information about sections. Also sections info is cached and returned by get_fast_modinfo() so every action changing the sections must be followed by rebuild_course_cache(). Course module must always belong to the section. Even if your course format does not use sections, the section with number 0 is always created.

You must define $string['sectionname'] if your language file even if format does not use sections because it can be called unconditionally from other parts of the code, even though it won't be displayed.

{| class="nicetable"
|-
! format_base method in 2.4+
! description
! Moodle 2.3- callback
|-
| uses_sections()
| returns true or false if the format uses sections or not. There is a global function course_format_uses_secions() that invokes it. It affects default navigation tree building. Various modules and reports may call this function to know whether to display section name for the particular module or not.
| callback_FORMATNAME_uses_sections()
|-
| get_section_name()
| Returns the name for particular section. This function may be called often so it should use only fields cached in section_info object (field course_sections.name is always cached)
| callback_FORMATNAME_get_section_name()
|-
| get_view_url()
| Returns the URL for particular section, it can be either anchor on course view page or separate page. See parent function PHPdocs for more details
| 2.3 only: callback_FORMATNAME_get_section_url(). Prior to Moodle 2.3 sections could not have separate URLs
|-
| is_section_current()
| Specifies if the section is current, for example current week or highlighted topic. This function is only used if your renderer uses it for example if your renderer extends format_section_renderer_base. This function is not called from anywhere else in Moodle core.
| format_section_renderer_base::is_section_current()
|}

==AJAX support in course format==

There are features in core that course format may use or ban, for example modchooser (activity chooser), inline edit of module title, drag and drop of sections, activities and blocks on the page, drag and drop files to the course page to create activities.

There is also a global setting $CFG->enableajax that admin can disable via config.php or in Settings block that will disable AJAX even if course format allows it.

If you have additional AJAX functionality in course format plugin, you must check course_ajax_enabled() before including it.

{| class="nicetable"
|-
! format_base method in 2.4+
! description
! Moodle 2.3-
|-
| supports_ajax()
| returns the minimum versions for browsers that support AJAX. Usually it is enough to copy the function code from format_topics
| callback_FORMATNAME_ajax_support()
|-
| ajax_section_move()
| code executed after sections were rearranged using drag and drop. See example in format_topics where sections have automatic names depending on their sequence number
| callback_FORMATNAME_ajax_section_move()
|}

==Default blocks==

Course format can specify which blocks should be added to the course page when course is created in this format.

If course format is changed during course edit, blocks are not changed.

Whatever course format specifies in the method, site admin can override it with $CFG->defaultblocks_override or $CFG->defaultblocks_FORMATNAME

{| class="nicetable"
|-
! format_base method in 2.4+
! description
! Moodle 2.3-
|-
| get_default_blocks()
| see PHPdocs in format_base class
| file config.php with $format['defaultblocks'] in it
|}

==Extending course navigation==

Node for the course will be created in navigationlib for you and all standard available branches like 'Participants' or 'Reports' will be added to it. After that course format can add nodes for sections and modules. There is a default implementation that adds branches for course sections and modules under them. Or if course format does not use sections, all modules will just be placed under course mode. Course format is able to override the default navigation tree building.

Note that if navigationlib can not find the node for the current course module, the node will be added automatically (after this callback).

The breadcrumb that appears on the top of the page also reads navigation tree.

You can see examples of overriding course navigation in [https://moodle.org/plugins/view.php?plugin=format_singleactivity format_singleactivity] and [https://moodle.org/plugins/view.php?plugin=format_flexsections format_flexsections]. In Single activity we pretend that course node is the activity node and in Flexible sections the sections are added to the navigation tree hierarchically.

{| class="nicetable"
|-
! format_base method in 2.4+
! description
! Moodle 2.3-
|-
| extend_course_navigation()
| See PHPdocs in format_base class. This function is called when navigation tree is built on the page and also when user expands non-active node in navigation via AJAX request. Only the node with active section should be expanded, do not add children nodes to not expanded nodes (for example do not add nodes for modules in collapsed sections)
| callback_FORMATNAME_display_content(), callback_FORMATNAME_load_content()
|}

==Course format options==
The core table '''{course_format_options}''' in Moodle database is designed to store additional options for course formats. This may be options for the whole course or options for course section.

Course format options must not have the same names as fields in database table {course}, section options must not have the same names as fields in {course_sections}. Also make sure names do not duplicate completion and conditional fields in edit forms.

Some facts about course format options in core classes:

* Core formats ''format_weeks'' and ''format_topics'' have options: ''numsections'', ''hiddensections'', ''coursedisplay''. They are also defined as default in class ''format_legacy'' because prior to 2.4 they were fields in {course} table and were part of course edit form.
* Class ''format_base'' by default does not define any options.
* Core formats ''format_social'' and ''format_scorm'' do not have have any options.
* Neither core course format uses additional section options. [https://moodle.org/plugins/view.php?plugin=format_flexsections Flexible sections format] has a section option "display collapsed/expanded" and it is also defined as cached because it affects often-called function get_view_url()

When teacher '''changes the course format''' in the course edit form AND the old and the new course formats share the same option name, the value of this option is copied from one format to another. For example, if course had format Topics and had 8 sections in it and teacher changes format to weeks, the course will have 8 weeks in it.

During '''backup''' the course format options are stored as if they were additional fields in {course} table. Therefore courses in topics and weeks formats that were backed up in Moodle 2.3 will be restored in 2.4 without data loss even though the values of numsections, hiddensections and coursedisplay will be stored in another table. '''Do not store IDs of elements''' (courses, sections, etc.) in course format options because they will not be backed up and restored properly. You can use section numbers because they are relative inside the course. If absolute ids are necessary you can create your own backup/restore scripts, see [[Backup API]].

'''Webservices''' expect course format options to be passed in additional entity but for backward compartibility numsections, hiddensections and coursedisplay can also be passed as if they were fields in {course} table.

{| class="nicetable"
|-
! format_base method in 2.4+
! Description
|-
| get_course()
| (no need to override) returns object with all fields from db table {course} AND all course format options
|-
| get_section()
| (no need to override) returns instance of section_info. It will contain all fields from table {course_sections} AND all course format options for this section
|-
| course_format_options()
| By overriding this method course format specifies which additional options it has for course
|-
| section_format_options()
| By overriding this method course format specifies which additional options it has for course section. Note that since section information is cached you may want to cache some additional options as well. See PHPdocs for more information
|-
| get_format_options()
| (usually no need to override) low level function to retrieve course format options values. It is more convenient to use methods get_course() and get_section()
|-
| create_edit_form_elements()
| This function is called to alter course edit form and standard section edit form. The default implementation creates simple form elements for each option defined in either course_format_options() or section_format_options(). Overwrite it if you want to have more comprehensive form elements or if you do not want options to appear in edit forms, etc.
|-
| edit_form_validation()
| Overwrite if course format plugin needs additional validation for it's option in course edit form
|-
| update_format_options()
| (usually no need to override) low level function to insert/update records in db table {course_format_options}
|-
| update_course_format_options()
| updates course format options with the data from the edit course form. Plugin can override for example to include calculated options fields, especially when course format is being changed. For example format_topics and format_weeks automatically fill field numsections when user switches from other format
|-
| update_section_format_options()
| updates course format options for the section with the data from edit section form
|-
| editsection_form()
| Return an instance of moodleform to edit a specified section. Default implementation returns instance of editsection_form that automatically adds additional fields defined in section_format_options()
|}

==Executing code before output==

It is often needed to execute some code before output started. You may want to
* redirect from one page to another. Examples are format_scorm format_singleactivity that don't have course view page and redirect /course/view.php to module view page
* perform an action that results in changes in navigation tree or other output. Example is when /course/view.php has a parameter in query that tells to change section visibility
* include additional JS or CSS files in the page head rather than body

File format.php is included after the output is started and the above cases can not be solved inside it.

Every module or page inside a course must call require_login() or $PAGE->set_cm() or $PAGE->set_course(). As soon as page knows the current module and/or course, the callbacks from current course format are invoked.

{| class="nicetable"
|-
! format_base method in 2.4+
! description
|-
| page_set_cm()
| Override if you want to execute some code when course module is set for the page
|-
| page_set_course()
| Override if you want to execute some code when course is set for the page. This function is always invoked on any course page
|}

==Additional footer or header on any page inside the course==

Course format may add content header and footer to any page inside the course (including modules pages). They will be displayed right above or below the page main content, right or left from side blocks. Also course formats may add course header and footer. They will be displayed above or below both content and blocks. Typical usages may be:
* course navigation (prev/next/back)
* course custom menu
* disclaimer information or other text in the bottom of each course page
* etc

This is a new feature in Moodle 2.4, you have to make sure that if the site uses the custom theme, it supports it. Refer to theme/upgrade.txt. Also theme may specify that some pagelayouts (report, print, etc) do NOT display the course header/footer.

Using this functionality REQUIRES use of renderers. '''Example''' of using the course headers/footers you can find in tracker issue MDL-36048

{| class="nicetable"
|-
! format_base method in 2.4+
! description
|-
| course_content_header()
| Returns content to be displayed immediately above the page content in the main area (between side blocks)
|-
| course_content_footer()
| Returns content to be displayed immediately below the page content in the main area (between side blocks)
|-
| course_header()
| Returns content to be displayed above all content, usually below heading and above breadcrumb but it depends on the theme
|-
| course_footer()
| Returns content to be displayed below content and blocks, usually above the page footer, exact poisition depends on the theme
|}

==Handling events==

As any other plugin types course formats can listen to system events. See [[Events API]]. Examples of events that format may listen to:

* '''course_created''' - when course is created. Usually not necessary because format_FORMATNAME::update_course_format_options() is called with null as second argument
* '''course_updated''' - when course is updated. Again format_FORMATNAME::update_course_format_options() is called. But if user changed format from A to B the function from format B is invoked. In this case if format A wants to remove some data it should listen to event;
* '''course_deleted''' - when course is deleted. Format may want to remove some data (all data from course_format_options is removed automatically)
* '''mod_created''' - course module created
* '''mod_updated''' - course module updated
* '''mod_deleted''' - course module deleted

[[Category:Plugins]]

Course format ideas

2012-08-16T19:54:53Z

Gb2048: /* Good section to section navigation */

This is a page set up in response to comments in this forum post: http://moodle.org/mod/forum/discuss.php?d=208789#p910726 It may take a number of iterations to get to where was want.

Former discussions:
#Possibility of getting Folderview into Moodle: http://moodle.org/mod/forum/discuss.php?d=175758#p772469
#Martin's post, prior to 2.3: http://moodle.org/mod/forum/discuss.php?d=200470#p874588
#Marty's 2008 post: http://moodle.org/mod/forum/discuss.php?d=102680
#Course formats at present: a summary from Moodle News http://www.moodlenews.com/course-formats/

There are several factors.
#Legacy issues
#Getting a nice solution into the core. As Mary says, we don't all have the benefit of an IT department, and hosted solutions cost a lot to customise.
#Creating flexibility fo plugin writers.
#??

----

==Navigation Issues==
1.9 to version 2 brought the navigation menu. In some respects this attempts to do everything. We have site navigation, course navigation and section navigation in one block. Almost an alternative scroll of death.

2.2 to 2.3 brought us a course level choice of a new layout option. Single sections and All sections on one page. Somehow the drop down list of sections was removed, whether this is a feature or an ommission is unclear. As an immediate fix in 2.3.x I'd like to see it back. Much like in this post. http://moodle.org/mod/forum/discuss.php?d=208789#p910618

==Contributed Formats==
#Folder view - see http://moodle.org/plugins/view.php?plugin=format_folderview
#Flexpage (Now back on the scene for 2.2 but not 2.3, see http://moodle.org/mod/forum/discuss.php?d=208789#p911219)
#Collapsed Topics - see http://moodle.org/plugins/view.php?plugin=format_topcoll
#Grid - see http://moodle.org/plugins/view.php?plugin=format_grid and http://tracker.moodle.org/browse/CONTRIB-3769
#Onetopic - see http://moodle.org/plugins/view.php?plugin=format_onetopic
#Easypost - see http://moodle.org/plugins/view.php?plugin=format_easypost
#Topics (colours) - see http://moodle.org/plugins/view.php?plugin=format_colours
#Weekly reversed - see http://moodle.org/plugins/view.php?plugin=format_weeksrev

See: https://docs.moodle.org/dev/Talk:Paged_course_formats

==General principles==
ie what are the ways we should be thinking about this?
===Good section to section navigation===
Consistently available ie there, in general, without having to scroll (as is the case regularly with inside course navigation in the Nav menu).

One option: a menu at the top left.
*examples: http://moodle.org/mod/forum/discuss.php?d=175758#p873291
http://moodle.org/pluginfile.php/554/mod_forum/post/873291/Pic1.png
*a plugin: http://moodle.org/mod/forum/discuss.php?d=169107
*Itamars version: http://moodle.org/mod/forum/discuss.php?d=208789#p910618 and his comments: http://moodle.org/mod/forum/discuss.php?d=200470#p874588 (from an old post)
http://moodle.org/pluginfile.php/155/mod_forum/post/910639/sections-vav.png
*Another version from Itamar http://moodle.org/pluginfile.php/155/mod_forum/post/910618/itamarsectionformat.png

IMO, this simple section<>section navigation as and option in core is essential. It takes care of the basic/simple course course, makes navigation in your face and intuitive. I don't like personally having too much in this. I like it really clean. Comments? --[[User:Derek Chirnside|Derek Chirnside]] 12:01, 16 August 2012 (WST) Note: I have done the code patch for this for core, see http://tracker.moodle.org/browse/MDL-34917 - [[User:Gareth Barnard|Gareth Barnard]] 03:54, 17 August 2012 (WST)

===Ability to tag the current section as current===
This is needed especially for the courses done on a week by week basis. You may have a navigation scrolling, but who cares in this case? Highlight this week, with a previous and next and I think it works OK. Then there is the problem of too much content for one week. The subpage module maybe of use here? --[[User:Derek Chirnside|Derek Chirnside]] 12:01, 16 August 2012 (WST)

===No scrolling to see the section to section navigation===
ie the Navigation menu option isn't enough.

Comments: "Regarding the SoD in the Navigation block, I think a very easy improvement to the in-course navigation would be to simply break out that navigation from the My Courses tree into its own tree. That way users can easily navigate within the course as well as between courses, but aren't hit with too much information with large course lists." from Kris Stokking http://moodle.org/mod/forum/discuss.php?d=208789#p911219

IMO there are too many levels in the Navigation Menu: Site, (Course), Sectionns, Section content. I'd like to see Course > Sections only. I don't mind scrolling within a well defined, sell structured section. --[[User:Derek Chirnside|Derek Chirnside]] 12:01, 16 August 2012 (WST)

==Other approaches==

===Comments on Grid idea===

===Comments on Collapsed sections approadh===

===Horizontal, in section navigation===
Basically, my suggestion. http://moodle.org/mod/forum/discuss.php?d=208789#p910650 --[[User:Derek Chirnside|Derek Chirnside]] 12:01, 16 August 2012 (WST)
http://moodle.org/pluginfile.php/155/mod_forum/post/910650/Ideal%20Navigation.jpg

===What else?===

Course format ideas

2012-08-16T19:50:37Z

Gb2048: /* Contributed Formats */

This is a page set up in response to comments in this forum post: http://moodle.org/mod/forum/discuss.php?d=208789#p910726 It may take a number of iterations to get to where was want.

Former discussions:
#Possibility of getting Folderview into Moodle: http://moodle.org/mod/forum/discuss.php?d=175758#p772469
#Martin's post, prior to 2.3: http://moodle.org/mod/forum/discuss.php?d=200470#p874588
#Marty's 2008 post: http://moodle.org/mod/forum/discuss.php?d=102680
#Course formats at present: a summary from Moodle News http://www.moodlenews.com/course-formats/

There are several factors.
#Legacy issues
#Getting a nice solution into the core. As Mary says, we don't all have the benefit of an IT department, and hosted solutions cost a lot to customise.
#Creating flexibility fo plugin writers.
#??

----

==Navigation Issues==
1.9 to version 2 brought the navigation menu. In some respects this attempts to do everything. We have site navigation, course navigation and section navigation in one block. Almost an alternative scroll of death.

2.2 to 2.3 brought us a course level choice of a new layout option. Single sections and All sections on one page. Somehow the drop down list of sections was removed, whether this is a feature or an ommission is unclear. As an immediate fix in 2.3.x I'd like to see it back. Much like in this post. http://moodle.org/mod/forum/discuss.php?d=208789#p910618

==Contributed Formats==
#Folder view - see http://moodle.org/plugins/view.php?plugin=format_folderview
#Flexpage (Now back on the scene for 2.2 but not 2.3, see http://moodle.org/mod/forum/discuss.php?d=208789#p911219)
#Collapsed Topics - see http://moodle.org/plugins/view.php?plugin=format_topcoll
#Grid - see http://moodle.org/plugins/view.php?plugin=format_grid and http://tracker.moodle.org/browse/CONTRIB-3769
#Onetopic - see http://moodle.org/plugins/view.php?plugin=format_onetopic
#Easypost - see http://moodle.org/plugins/view.php?plugin=format_easypost
#Topics (colours) - see http://moodle.org/plugins/view.php?plugin=format_colours
#Weekly reversed - see http://moodle.org/plugins/view.php?plugin=format_weeksrev

See: https://docs.moodle.org/dev/Talk:Paged_course_formats

==General principles==
ie what are the ways we should be thinking about this?
===Good section to section navigation===
Consistently available ie there, in general, without having to scroll (as is the case regularly with inside course navigation in the Nav menu).

One option: a menu at the top left.
*examples: http://moodle.org/mod/forum/discuss.php?d=175758#p873291
http://moodle.org/pluginfile.php/554/mod_forum/post/873291/Pic1.png
*a plugin: http://moodle.org/mod/forum/discuss.php?d=169107
*Itamars version: http://moodle.org/mod/forum/discuss.php?d=208789#p910618 and his comments: http://moodle.org/mod/forum/discuss.php?d=200470#p874588 (from an old post)
http://moodle.org/pluginfile.php/155/mod_forum/post/910639/sections-vav.png
*Another version from Itamar http://moodle.org/pluginfile.php/155/mod_forum/post/910618/itamarsectionformat.png

IMO, this simple section<>section navigation as and option in core is essential. It takes care of the basic/simple course course, makes navigation in your face and intuitive. I don't like personally having too much in this. I like it really clean. Comments? --[[User:Derek Chirnside|Derek Chirnside]] 12:01, 16 August 2012 (WST)

===Ability to tag the current section as current===
This is needed especially for the courses done on a week by week basis. You may have a navigation scrolling, but who cares in this case? Highlight this week, with a previous and next and I think it works OK. Then there is the problem of too much content for one week. The subpage module maybe of use here? --[[User:Derek Chirnside|Derek Chirnside]] 12:01, 16 August 2012 (WST)

===No scrolling to see the section to section navigation===
ie the Navigation menu option isn't enough.

Comments: "Regarding the SoD in the Navigation block, I think a very easy improvement to the in-course navigation would be to simply break out that navigation from the My Courses tree into its own tree. That way users can easily navigate within the course as well as between courses, but aren't hit with too much information with large course lists." from Kris Stokking http://moodle.org/mod/forum/discuss.php?d=208789#p911219

IMO there are too many levels in the Navigation Menu: Site, (Course), Sectionns, Section content. I'd like to see Course > Sections only. I don't mind scrolling within a well defined, sell structured section. --[[User:Derek Chirnside|Derek Chirnside]] 12:01, 16 August 2012 (WST)

==Other approaches==

===Comments on Grid idea===

===Comments on Collapsed sections approadh===

===Horizontal, in section navigation===
Basically, my suggestion. http://moodle.org/mod/forum/discuss.php?d=208789#p910650 --[[User:Derek Chirnside|Derek Chirnside]] 12:01, 16 August 2012 (WST)
http://moodle.org/pluginfile.php/155/mod_forum/post/910650/Ideal%20Navigation.jpg

===What else?===

User:Gareth Barnard

2012-04-12T13:22:47Z

Gb2048: Created page with "Please see my [http://moodle.org/user/profile.php?id=442195 Moodle user profile] for full details."

Please see my [http://moodle.org/user/profile.php?id=442195 Moodle user profile] for full details.

Talk:Paged course formats

2012-04-12T13:20:26Z

Gb2048: /* Some thoughts */

==Introduction==
What is the general idea of 'Paged course formats'? - Will it be that you get to see the section name as a list, then if you wish to view it opens in a new tab within the browser?

==Discussions around this==
http://moodle.org/mod/forum/discuss.php?d=175758#p770737

==Some of the options currently around for alternative formats==
Representing several different approaches.
#http://server3.moodle.com/browse/MDL-28555

===FOLDERVIEW===
Doed much more than just offer page view. Eiting magic as well.
#Folderview Blog post: http://thinkingdistance.org/post/6486856003/folderview-course-format
#Comments by Michael: http://server3.moodle.com/browse/MDL-27646 Including Folderview in Moodle 2

Paul's comment: "Paul Chapin added a comment - 07/Jun/11 3:20 AM : The folder view format doesn't really do it. Basically, that's just a topic format with a different interface. It doesn't deal with the situation of the instructor who wants to make a large amount of reference information, usually files and web links, available as part of a topic or week without visually overwhelming the students. By allowing for a hierarchical structuring of material using folders the amount of information the student is presented with at any given time can be limited and organized logically. It's really files and links that we want, but if that's implemented, adding the rest of the resource types should be fairly straight forward" MDL-27646

===FLEXPAGE===
Unsure of status for 2.
#Flexipage and Moodle 2.0: http://moodle.org/mod/forum/discuss.php?d=83817#p74318

===COLLAPSED===
Three forms: Topics, Weeks and Latest First
#http://moodle.org/plugins/view.php?plugin=format_topcoll - Same as Topic's format but with a 'toggle' and a cookie to remember state per user per course that can be persistent. Developed much further - see CONTRIB-3378 below.
#http://moodle.org/plugins/view.php?plugin=format_weekcoll - Same as Week's format but with a 'toggle' as above.
#https://github.com/gjb2048/moodle-format_latfirst - Same as above but current week is displayed first and preceding weeks after for the user. In 'editing' mode it is the same as Collapsed Weeks.

Combined into one:
#CONTRIB-3378
Which has four forms: Topics, Weeks, Latest Week First and Current Topic First. Available from [http://moodle.org/plugins/view.php?plugin=format_topcoll Modules & Plugin's Database] and documented on [https://docs.moodle.org/22/en/Collapsed_Topics_course_format Collapsed Topics Course Format]

Above collapsed forms developed by [http://moodle.org/user/profile.php?id=442195 Gareth J Barnard].

===BLOCK===
Experimental jQuery Masonry (#http://masonry.desandro.com/) format for Moodle 2.1:
#https://github.com/gjb2048/moodle-format_topmas - Uses the jQuery Masonry plugin to arrange sections as close together as possible. Resizes automatically depending on content.

===GRID===
Not strictly a "paged format" But getting very good reviews. Looks classy.
#http://moodle.org/plugins/view.php?plugin=format_grid Seems a good option

"The Grid Format was originally contributed by Paul Krix. It has since been updated and is now maintained ny Pukunui Technology. This format adds a more graphical interface to viewing Moodle topics and also avoids the "scroll of death" issue by using placeholder graphics to represent each topic. When clicked upon, these graphics launch the topics in ajax windows" from https://github.com/moodleman/moodle-courseformat_grid

===COURSE MENU===
There are at least two in plugins:
#
#
Plus Lei Zhang (and Awesome Moodle) bar

Catalyst have coded two options included in Moodle in Schools package.

==Section Menu Option==

==OU format option==

== Some thoughts ==

1. For weekly courses, one page per section is not necessarily ideal. Instead the OU course format (studyplanner) by default just shows the current week (highlighted) with +- n weeks either side. There is then a link 'Show entire study planner' if you need to find something else. Section 0 is always visible. I think this is a good model (speaking as an OU student here). However, the 'mdl_course.coursedisplay' proposal, with just two settings, does nothing to make this easier. Therefore, I am skeptical about the value of hard-coding that into Moodle core.--[[User:Tim Hunt|Tim Hunt]] 20:09, 12 April 2012 (WST)

2. Even if you press on with your plan, it seems silly to just list the weeks on the course front page in weekly format. Surely it is worth displaying the current week in full there. It will save students one click almost every time they visit the course.--[[User:Tim Hunt|Tim Hunt]] 20:09, 12 April 2012 (WST)

3. Has anyone at HQ actually downloaded and installed the OU's subpage module? I know it solves a separate problem, but please spend some time looking at it now for two reasons. A. When you do the "Check for regressions in modules caused by course assumptions" bit, you should try to ensure that they benefit modules like subpage, as well as your course format changes. B. Subpage functionality might be worth adding to Moodle too, and the code already exists and works.--[[User:Tim Hunt|Tim Hunt]] 20:09, 12 April 2012 (WST)

4. Be very careful when defining format_renderer_base. If you have format_weekly_renderer extends format_renderer_base, and format_renderer_base generates output for something, then a theme cannot do theme_mytheme_format_renderer cannot usefully extend format_renderer_base to change the output, because format_weekly_renderer still extends format_renderer_base, and not theme_mytheme_format_renderer. (I made this mistake in a few small ways with question_type_renderer base, e.g. the feedback_image mehthod, although I mostly got it right by creating core_question_renderer to output the common parts of questions.) Basically, prefer composition over inheritance (http://c2.com/cgi/wiki?CompositionInsteadOfInheritance).--[[User:Tim Hunt|Tim Hunt]] 20:09, 12 April 2012 (WST)

5. I am worried that you are trying to do this in a rush before the 2.3 deadline, particularly if you are not going to delay mdl_course.coursedisplay until 2.4. It occurs to me that a lot of this could be done initially in third-party course-format plugins. Then, once everyone can see it working, and has been bowled over by how amazing it is (assuming you are right, and I am wrong) you can then refactor the code into Moodle core.--[[User:Tim Hunt|Tim Hunt]] 20:09, 12 April 2012 (WST)

5.1 I disagree with Tim over implementing initially in third-party course-format plugins. As this is a 'core' functionality change it should be implemented there as 'gospel' way of implementing the functionality so that there is no confusion over interpretation of how it should work. Because if each contrib developer takes their 'view' then we will have a mismash that will have to be sorted and then the contrib developers have to refactor back to the HQ defined standard. I don't live and breathe PHP or Moodle (sacrilege I know) so tend to follow and adapt the 'guru' written code in the core formats as a basis of learning and implementing the correct functionality, hence I consider a core 'guru gospel' implementation to be the better solution. [[User:Gareth Barnard|Gareth Barnard]] 21:20, 12 April 2012 (WST)

5.2 I do agree with the thought of it being rushed as although I consider a lot of users have been screaming for this for ages, it would be better to get it right first time even if this takes a little longer. As a bodge job could put users off Moodle completely and cause them to lose faith in the quality of the product. [[User:Gareth Barnard|Gareth Barnard]] 21:20, 12 April 2012 (WST)

6. We have not yet published the Moodle 2.x code for the studyplanner course format, but if anyone want to see it, we can probably share it. Just ask.--[[User:Tim Hunt|Tim Hunt]] 20:11, 12 April 2012 (WST)

7. Do we really want the course format options to be part of the already very long and complex course settings form. Whey not have a separate link in the settings block for 'Weekly format options', or something like that. Much simpler all round.--[[User:Tim Hunt|Tim Hunt]] 20:13, 12 April 2012 (WST)

8. I override the function 'section_class.prototype.swap_with_section' in '/lib/ajax/section_classes.js' in the contributed 'Collapsed Topics' course format because I use a table for my layout and hence two table rows per section. Therefore, will I still be able to do this? Before I get blamed for using a 'table' tag instead of a 'div' tag and a set of 'ul' tags, tables work for me because the layout is tabular and conceptually is a table in the Object Orientated sense (bar the three/four/more legs), and indeed the W3C specification of a '[http://www.w3.org/TR/html4/struct/tables.html table]' states 'The HTML table model allows authors to arrange data -- text, preformatted text, images, links, forms, form fields, other tables, etc. -- into rows and columns of cells.' and that is exactly what I am doing as an arrangement of the sections as rows and columnar subdivision of content / section information. It also works better with Internet Explorer and manipulating the Document Object Model with JavaScript at the client end. [[User:Gareth Barnard|Gareth Barnard]] 21:20, 12 April 2012 (WST)

Talk:Paged course formats

2012-03-22T18:17:38Z

Gb2048: /* COLLAPSED */

Talk:Paged course formats

2012-02-28T10:39:31Z

Gb2048:

Talk:Paged course formats

2012-02-25T22:01:30Z

Gb2048: /* BLOCK */

What is the general idea of 'Paged course formats'? - Will it be that you get to see the section name as a list, then if you wish to view it opens in a new tab within the browser? I now have extensive course format development skills (and I hope enough Git knowledge) - can I help with writing the code for Moodle core? I'm [http://moodle.org/user/profile.php?id=442195 Gareth J Barnard] - developer of the Collapsed Topics / Weeks course formats.

==Discussions around this==
http://moodle.org/mod/forum/discuss.php?d=175758#p770737

==Some of the options currently around for alternative formats==
Representing several different approaches.
#http://server3.moodle.com/browse/MDL-28555

===FOLDERVIEW===
Doed much more than just offer page view. Eiting magic as well.
#Folderview Blog post: http://thinkingdistance.org/post/6486856003/folderview-course-format
#Comments by Michael: http://server3.moodle.com/browse/MDL-27646 Including Folderview in Moodle 2

Paul's comment: "Paul Chapin added a comment - 07/Jun/11 3:20 AM : The folder view format doesn't really do it. Basically, that's just a topic format with a different interface. It doesn't deal with the situation of the instructor who wants to make a large amount of reference information, usually files and web links, available as part of a topic or week without visually overwhelming the students. By allowing for a hierarchical structuring of material using folders the amount of information the student is presented with at any given time can be limited and organized logically. It's really files and links that we want, but if that's implemented, adding the rest of the resource types should be fairly straight forward" MDL-27646

===FLEXPAGE===
Unsure of status for 2.
#Flexipage and Moodle 2.0: http://moodle.org/mod/forum/discuss.php?d=83817#p74318

===COLLAPSED===
Three forms: Topics, Weeks and Latest First
#http://moodle.org/plugins/view.php?plugin=format_topcoll - Same as Topic's format but with a 'toggle' and a cookie to remember state per user per course that can be persistent.
#http://moodle.org/plugins/view.php?plugin=format_weekcoll - Same as Week's format but with a 'toggle' as above.
#https://github.com/gjb2048/moodle-format_latfirst - Same as above but current week is displayed first and preceding weeks after for the user. In 'editing' mode it is the same as Collapsed Weeks.

Soon all to be combined into one:
#http://tracker.moodle.org/browse/CONTRIB-3378

===BLOCK===
Experimental jQuery Masonry (#http://masonry.desandro.com/) format for Moodle 2.1:
#https://github.com/gjb2048/moodle-format_topmas - Uses the jQuery Masonry plugin to arrange sections as close together as possible. Resizes automatically depending on content.

===GRID===
Not strictly a "paged format" But getting very good reviews. Looks classy.
#http://moodle.org/plugins/view.php?plugin=format_grid Seems a good option

"The Grid Format was originally contributed by Paul Krix. It has since been updated and is now maintained ny Pukunui Technology. This format adds a more graphical interface to viewing Moodle topics and also avoids the "scroll of death" issue by using placeholder graphics to represent each topic. When clicked upon, these graphics launch the topics in ajax windows" from https://github.com/moodleman/moodle-courseformat_grid

===COURSE MENU===
There are at least two in plugins:
#
#
Plus Lei Zhang (and Awesome Moodle) bar

Catalyst have coded two options included in Moodle in Schools package.

==Section Menu Option==

==OU format option==

Talk:Paged course formats

2012-02-25T22:00:25Z

Gb2048: /* COLLAPSED */

What is the general idea of 'Paged course formats'? - Will it be that you get to see the section name as a list, then if you wish to view it opens in a new tab within the browser? I now have extensive course format development skills (and I hope enough Git knowledge) - can I help with writing the code for Moodle core? I'm [http://moodle.org/user/profile.php?id=442195 Gareth J Barnard] - developer of the Collapsed Topics / Weeks course formats.

==Discussions around this==
http://moodle.org/mod/forum/discuss.php?d=175758#p770737

==Some of the options currently around for alternative formats==
Representing several different approaches.
#http://server3.moodle.com/browse/MDL-28555

===FOLDERVIEW===
Doed much more than just offer page view. Eiting magic as well.
#Folderview Blog post: http://thinkingdistance.org/post/6486856003/folderview-course-format
#Comments by Michael: http://server3.moodle.com/browse/MDL-27646 Including Folderview in Moodle 2

Paul's comment: "Paul Chapin added a comment - 07/Jun/11 3:20 AM : The folder view format doesn't really do it. Basically, that's just a topic format with a different interface. It doesn't deal with the situation of the instructor who wants to make a large amount of reference information, usually files and web links, available as part of a topic or week without visually overwhelming the students. By allowing for a hierarchical structuring of material using folders the amount of information the student is presented with at any given time can be limited and organized logically. It's really files and links that we want, but if that's implemented, adding the rest of the resource types should be fairly straight forward" MDL-27646

===FLEXPAGE===
Unsure of status for 2.
#Flexipage and Moodle 2.0: http://moodle.org/mod/forum/discuss.php?d=83817#p74318

===COLLAPSED===
Three forms: Topics, Weeks and Latest First
#http://moodle.org/plugins/view.php?plugin=format_topcoll - Same as Topic's format but with a 'toggle' and a cookie to remember state per user per course that can be persistent.
#http://moodle.org/plugins/view.php?plugin=format_weekcoll - Same as Week's format but with a 'toggle' as above.
#https://github.com/gjb2048/moodle-format_latfirst - Same as above but current week is displayed first and preceding weeks after for the user. In 'editing' mode it is the same as Collapsed Weeks.

Soon all to be combined into one:
#http://tracker.moodle.org/browse/CONTRIB-3378

===BLOCK===
Experimental jQuery Masonry (#http://masonry.desandro.com/) format for Moodle 2.1:
#https://github.com/gjb2048/moodle-format_topmas

===GRID===
Not strictly a "paged format" But getting very good reviews. Looks classy.
#http://moodle.org/plugins/view.php?plugin=format_grid Seems a good option

"The Grid Format was originally contributed by Paul Krix. It has since been updated and is now maintained ny Pukunui Technology. This format adds a more graphical interface to viewing Moodle topics and also avoids the "scroll of death" issue by using placeholder graphics to represent each topic. When clicked upon, these graphics launch the topics in ajax windows" from https://github.com/moodleman/moodle-courseformat_grid

===COURSE MENU===
There are at least two in plugins:
#
#
Plus Lei Zhang (and Awesome Moodle) bar

Catalyst have coded two options included in Moodle in Schools package.

==Section Menu Option==

==OU format option==

Talk:Paged course formats

2012-02-25T21:53:59Z

Gb2048: /* COLLAPSED */

What is the general idea of 'Paged course formats'? - Will it be that you get to see the section name as a list, then if you wish to view it opens in a new tab within the browser? I now have extensive course format development skills (and I hope enough Git knowledge) - can I help with writing the code for Moodle core? I'm [http://moodle.org/user/profile.php?id=442195 Gareth J Barnard] - developer of the Collapsed Topics / Weeks course formats.

==Discussions around this==
http://moodle.org/mod/forum/discuss.php?d=175758#p770737

==Some of the options currently around for alternative formats==
Representing several different approaches.
#http://server3.moodle.com/browse/MDL-28555

===FOLDERVIEW===
Doed much more than just offer page view. Eiting magic as well.
#Folderview Blog post: http://thinkingdistance.org/post/6486856003/folderview-course-format
#Comments by Michael: http://server3.moodle.com/browse/MDL-27646 Including Folderview in Moodle 2

Paul's comment: "Paul Chapin added a comment - 07/Jun/11 3:20 AM : The folder view format doesn't really do it. Basically, that's just a topic format with a different interface. It doesn't deal with the situation of the instructor who wants to make a large amount of reference information, usually files and web links, available as part of a topic or week without visually overwhelming the students. By allowing for a hierarchical structuring of material using folders the amount of information the student is presented with at any given time can be limited and organized logically. It's really files and links that we want, but if that's implemented, adding the rest of the resource types should be fairly straight forward" MDL-27646

===FLEXPAGE===
Unsure of status for 2.
#Flexipage and Moodle 2.0: http://moodle.org/mod/forum/discuss.php?d=83817#p74318

===COLLAPSED===
Three forms: Topics, Weeks and Latest First
#http://moodle.org/plugins/view.php?plugin=format_topcoll
#http://moodle.org/plugins/view.php?plugin=format_weekcoll
#https://github.com/gjb2048/moodle-format_latfirst

Soon all to be combined into one:
#http://tracker.moodle.org/browse/CONTRIB-3378

===BLOCK===
Experimental jQuery Masonry (#http://masonry.desandro.com/) format for Moodle 2.1:
#https://github.com/gjb2048/moodle-format_topmas

===GRID===
Not strictly a "paged format" But getting very good reviews. Looks classy.
#http://moodle.org/plugins/view.php?plugin=format_grid Seems a good option

"The Grid Format was originally contributed by Paul Krix. It has since been updated and is now maintained ny Pukunui Technology. This format adds a more graphical interface to viewing Moodle topics and also avoids the "scroll of death" issue by using placeholder graphics to represent each topic. When clicked upon, these graphics launch the topics in ajax windows" from https://github.com/moodleman/moodle-courseformat_grid

===COURSE MENU===
There are at least two in plugins:
#
#
Plus Lei Zhang (and Awesome Moodle) bar

Catalyst have coded two options included in Moodle in Schools package.

==Section Menu Option==

==OU format option==

Talk:Paged course formats

2012-02-25T21:50:48Z

Gb2048: /* COLLAPSED */

What is the general idea of 'Paged course formats'? - Will it be that you get to see the section name as a list, then if you wish to view it opens in a new tab within the browser? I now have extensive course format development skills (and I hope enough Git knowledge) - can I help with writing the code for Moodle core? I'm [http://moodle.org/user/profile.php?id=442195 Gareth J Barnard] - developer of the Collapsed Topics / Weeks course formats.

==Discussions around this==
http://moodle.org/mod/forum/discuss.php?d=175758#p770737

==Some of the options currently around for alternative formats==
Representing several different approaches.
#http://server3.moodle.com/browse/MDL-28555

===FOLDERVIEW===
Doed much more than just offer page view. Eiting magic as well.
#Folderview Blog post: http://thinkingdistance.org/post/6486856003/folderview-course-format
#Comments by Michael: http://server3.moodle.com/browse/MDL-27646 Including Folderview in Moodle 2

Paul's comment: "Paul Chapin added a comment - 07/Jun/11 3:20 AM : The folder view format doesn't really do it. Basically, that's just a topic format with a different interface. It doesn't deal with the situation of the instructor who wants to make a large amount of reference information, usually files and web links, available as part of a topic or week without visually overwhelming the students. By allowing for a hierarchical structuring of material using folders the amount of information the student is presented with at any given time can be limited and organized logically. It's really files and links that we want, but if that's implemented, adding the rest of the resource types should be fairly straight forward" MDL-27646

===FLEXPAGE===
Unsure of status for 2.
#Flexipage and Moodle 2.0: http://moodle.org/mod/forum/discuss.php?d=83817#p74318

===COLLAPSED===
Three forms: Topics, Weeks and Latest First
#http://moodle.org/plugins/view.php?plugin=format_topcoll
#http://moodle.org/plugins/view.php?plugin=format_weekcoll
#https://github.com/gjb2048/moodle-format_latfirst

Soon all to be combined into one:
#http://tracker.moodle.org/browse/CONTRIB-3378

===GRID===
Not strictly a "paged format" But getting very good reviews. Looks classy.
#http://moodle.org/plugins/view.php?plugin=format_grid Seems a good option

"The Grid Format was originally contributed by Paul Krix. It has since been updated and is now maintained ny Pukunui Technology. This format adds a more graphical interface to viewing Moodle topics and also avoids the "scroll of death" issue by using placeholder graphics to represent each topic. When clicked upon, these graphics launch the topics in ajax windows" from https://github.com/moodleman/moodle-courseformat_grid

===COURSE MENU===
There are at least two in plugins:
#
#
Plus Lei Zhang (and Awesome Moodle) bar

Catalyst have coded two options included in Moodle in Schools package.

==Section Menu Option==

==OU format option==

Talk:Paged course formats

2012-02-17T22:59:45Z

Gb2048: Created page with "What is the general idea of 'Paged course formats'? - Will it be that you get to see the section name as a list, then if you wish to view it opens in a new tab within the browser..."

Talk:Creating a theme

2010-06-01T08:38:47Z

Gb2048: /* Broken :-( */

Wow! Is the code for this theme available in a file, say in Modules and Plugins? Or did I miss it in my quick look. I can see my next project at work. --[[User:chris collman|chris collman]] 12:07, 6 April 2010 (UTC)

Hi Chris, the code in this tutorial isn't available anywhere the reason being that it is entirely based on the base theme :) check out ''theme/base/*'' you'll notice that what is in there is very close to the code I wrote for this tutorial. --[[User:Sam Hemelryk|Sam Hemelryk]] 01:33, 7 April 2010 (UTC)
::Hi Sam, I did not look, why get confused by reality and numb about :) I sort of got here by creating a 1.9.8 localhost that I could do screenshots for [[Standard themes]] and then tried my first complete install package of 2.0 in 3 months. My primary goal is to revamp the 'navigation' and organization of Category:Themes pages, your instructions are going to help me. Thanks for all your time and efforts. --[[User:chris collman|chris collman]] 11:26, 7 April 2010 (UTC)

Good crisp documentation!! Thank you Sam for this :) You ve made our lives easier with 2.0 themes!! ;)

Cheers!! --[[User:Navin Dutta|Navin Dutta]] 03:12, 13 April 2010 (UTC)

==Question about instruction==
Sam, your instructions say there will only be one layout php file called standard.php. What is the general.php file pointer doing in config.php under base? If I understand things, it should be pointed to the theme base (which has a general.php) or the file should be called standard.php. Is that correct?

It is snowing, so I thought I would see if I could follow your instructions and do something like standardlogo in 1.9 for fun. No doubt will crash and burn with this part time project over the next 2 years :) Thanks --[[User:chris collman|chris collman]] 13:12, 16 April 2010 (UTC)

== Broken :-( ==

Hello,

Thanks for the tutorial, but with - Moodle 2.0 Preview 2 (Build: 20100531) - I get the error 'Coding error detected, it must be fixed by a programmer: Trying to reference an unknown block region side-post' when trying to select the theme for modern browsers.

Update: I've made the changes required to solve the problem after reading: http://moodle.org/mod/forum/discuss.php?d=150190

Cheers,

Gareth

Talk:Creating a theme

2010-06-01T08:37:58Z

Gb2048: /* Broken :-( */

Creating a theme

2010-06-01T08:36:36Z

Gb2048: /* The page footer */

{{Template:Themes}}{{Moodle 2.0}}This document describes how to create a theme for Moodle 2.0. 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 its '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.

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:
<div style="height:400px;overflow:auto;">
<code php>
$THEME->layouts = array(
'base' => array(
'file' => 'standard.php',
'regions' => array(),
),
'standard' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'course' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post'
),
'coursecategory' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'incourse' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'frontpage' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'admin' => array(
'file' => 'standard.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
'mydashboard' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'mypublic' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'login' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('langmenu'=>true),
),
'popup' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
'frametop' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
'maintenance' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true),
),
);

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

</code>
</div>

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

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

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 echo $PAGE->bodyid; ?>" class="<?php echo $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 echo $PAGE->bodyid; ?>" class="<?php echo $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 shown on the page.

In both cases we can choose to wrap them in a div to make our life as a themer easier.

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.

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

<div style="height:400px;overflow:auto;">
<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 echo $PAGE->bodyid; ?>" class="<?php echo $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>
</div>

==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]] 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:400px;">
<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.

==See also==
* [[Themes 2.0]]
* [[Themes 2.0 overriding a renderer]]

[[Category:Themes]]

Creating a theme

2010-06-01T08:34:38Z

Gb2048: /* The page content */

{{Template:Themes}}{{Moodle 2.0}}This document describes how to create a theme for Moodle 2.0. 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 its '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.

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:
<div style="height:400px;overflow:auto;">
<code php>
$THEME->layouts = array(
'base' => array(
'file' => 'standard.php',
'regions' => array(),
),
'standard' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'course' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post'
),
'coursecategory' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'incourse' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'frontpage' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'admin' => array(
'file' => 'standard.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
'mydashboard' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'mypublic' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'login' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('langmenu'=>true),
),
'popup' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
'frametop' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
'maintenance' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true),
),
);

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

</code>
</div>

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

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

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 echo $PAGE->bodyid; ?>" class="<?php echo $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 echo $PAGE->bodyid; ?>" class="<?php echo $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 shown on the page.

In both cases we can choose to wrap them in a div to make our life as a themer easier.

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.

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

<div style="height:400px;overflow:auto;">
<code php>
<?php
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 echo $PAGE->bodyid; ?>" class="<?php echo $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>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
</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>
</div>

==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]] 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:400px;">
<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.

==See also==
* [[Themes 2.0]]
* [[Themes 2.0 overriding a renderer]]

[[Category:Themes]]

Creating a theme

2010-06-01T08:33:41Z

Gb2048: /* The top of the layout file */

{{Template:Themes}}{{Moodle 2.0}}This document describes how to create a theme for Moodle 2.0. 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 its '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.

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:
<div style="height:400px;overflow:auto;">
<code php>
$THEME->layouts = array(
'base' => array(
'file' => 'standard.php',
'regions' => array(),
),
'standard' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'course' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post'
),
'coursecategory' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'incourse' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'frontpage' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'admin' => array(
'file' => 'standard.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
'mydashboard' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'mypublic' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'login' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('langmenu'=>true),
),
'popup' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
'frametop' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
'maintenance' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true),
),
);

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

</code>
</div>

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

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

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 echo $PAGE->bodyid; ?>" class="<?php echo $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 echo $PAGE->bodyid; ?>" class="<?php echo $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 shown on the page.

In both cases we can choose to wrap them in a div to make our life as a themer easier.

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>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
</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.

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

<div style="height:400px;overflow:auto;">
<code php>
<?php
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 echo $PAGE->bodyid; ?>" class="<?php echo $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>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
</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>
</div>

==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]] 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:400px;">
<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.

==See also==
* [[Themes 2.0]]
* [[Themes 2.0 overriding a renderer]]

[[Category:Themes]]

Talk:Creating a theme

2010-05-31T08:37:43Z

Gb2048: /* Borken :-( */

Talk:Creating a theme

2010-05-31T08:37:31Z

Gb2048: /* Borken :-( */

Wow! Is the code for this theme available in a file, say in Modules and Plugins? Or did I miss it in my quick look. I can see my next project at work. --[[User:chris collman|chris collman]] 12:07, 6 April 2010 (UTC)

Hi Chris, the code in this tutorial isn't available anywhere the reason being that it is entirely based on the base theme :) check out ''theme/base/*'' you'll notice that what is in there is very close to the code I wrote for this tutorial. --[[User:Sam Hemelryk|Sam Hemelryk]] 01:33, 7 April 2010 (UTC)
::Hi Sam, I did not look, why get confused by reality and numb about :) I sort of got here by creating a 1.9.8 localhost that I could do screenshots for [[Standard themes]] and then tried my first complete install package of 2.0 in 3 months. My primary goal is to revamp the 'navigation' and organization of Category:Themes pages, your instructions are going to help me. Thanks for all your time and efforts. --[[User:chris collman|chris collman]] 11:26, 7 April 2010 (UTC)

Good crisp documentation!! Thank you Sam for this :) You ve made our lives easier with 2.0 themes!! ;)

Cheers!! --[[User:Navin Dutta|Navin Dutta]] 03:12, 13 April 2010 (UTC)

==Question about instruction==
Sam, your instructions say there will only be one layout php file called standard.php. What is the general.php file pointer doing in config.php under base? If I understand things, it should be pointed to the theme base (which has a general.php) or the file should be called standard.php. Is that correct?

It is snowing, so I thought I would see if I could follow your instructions and do something like standardlogo in 1.9 for fun. No doubt will crash and burn with this part time project over the next 2 years :) Thanks --[[User:chris collman|chris collman]] 13:12, 16 April 2010 (UTC)

== Borken :-( ==

Hello,

Thanks for the tutorial, but with - Moodle 2.0 Preview 2 (Build: 20100531) - I get the error 'Coding error detected, it must be fixed by a programmer: Trying to reference an unknown block region side-post' when trying to select the theme for modern browsers.

Cheers,

Gareth

Talk:Creating a theme

2010-05-31T08:36:40Z

Gb2048: /* Borken :-( */ new section

Wow! Is the code for this theme available in a file, say in Modules and Plugins? Or did I miss it in my quick look. I can see my next project at work. --[[User:chris collman|chris collman]] 12:07, 6 April 2010 (UTC)

Hi Chris, the code in this tutorial isn't available anywhere the reason being that it is entirely based on the base theme :) check out ''theme/base/*'' you'll notice that what is in there is very close to the code I wrote for this tutorial. --[[User:Sam Hemelryk|Sam Hemelryk]] 01:33, 7 April 2010 (UTC)
::Hi Sam, I did not look, why get confused by reality and numb about :) I sort of got here by creating a 1.9.8 localhost that I could do screenshots for [[Standard themes]] and then tried my first complete install package of 2.0 in 3 months. My primary goal is to revamp the 'navigation' and organization of Category:Themes pages, your instructions are going to help me. Thanks for all your time and efforts. --[[User:chris collman|chris collman]] 11:26, 7 April 2010 (UTC)

Good crisp documentation!! Thank you Sam for this :) You ve made our lives easier with 2.0 themes!! ;)

Cheers!! --[[User:Navin Dutta|Navin Dutta]] 03:12, 13 April 2010 (UTC)

==Question about instruction==
Sam, your instructions say there will only be one layout php file called standard.php. What is the general.php file pointer doing in config.php under base? If I understand things, it should be pointed to the theme base (which has a general.php) or the file should be called standard.php. Is that correct?

It is snowing, so I thought I would see if I could follow your instructions and do something like standardlogo in 1.9 for fun. No doubt will crash and burn with this part time project over the next 2 years :) Thanks --[[User:chris collman|chris collman]] 13:12, 16 April 2010 (UTC)

== Borken :-( ==

Hello,

Thanks for the tutorial, but with - Moodle 2.0 Preview 2 (Build: 20100531) - I get the error 'Coding error detected, it must be fixed by a programmer: Trying to reference an unknown block region side-post' when tring to select the theme for modern browsers.

Cheers,

Gareth

Talk:Creating a theme

2010-05-31T08:36:09Z

Gb2048: /* Question about instruction */