MoodleDocs - User contributions [en]

Upgrade API

2012-07-07T17:04:33Z

Stephenla: Corrected typo "does" to "goes"

The Upgrade API is how your module installs and upgrades itself, by keeping track of its own version.

==Introduction==
By implementing this API in your plugin, Moodle will automatically create your database tables for you when you visit the Admin notifications page (.../admin/index.php).

This process is controlled by three files within your plugin (there are other optional files you can use for various things. These are covered at the end of this document):
;[[version.php]] : This records the version of the plugin code ('''Please note:''' In Moodle installations below v2.0, this is not required for blocks, which use the version number returned by the block's init() method - see [[Blocks#Ready.2C_Set.2C_Go.21|the blocks development page]]). You must increase version in version.php after any change in /db/ folder, any change in javascript code and also after any change in language pack because new version triggers upgrade upgrade procedure and resets all caches.
;db/install.xml : This is used when someone installs your plugin for the first time.
;db/upgrade.php : This is used when someone who had an older version of your plugin installed upgrades to the latest version.

In addition, Moodle also stores in the database the currently installed version of each plugin.

In Moodle 1.x, this is stored in the mdl_config table, in a row with the name ''plugintype''_''pluginname''_version. For example qtype_myqtype_version. The exception to this rule are modules and blocks. Installed module version numbers are stored in the mdl_modules table. Block version numbers are in mdl_block.

In Moodle 2.x, plugin version numbers are stored in the mdl_config_plugins table, with ''plugintype''_''pluginname'' in the plugin column, and 'version' in the name column - with the same exception for modules and blocks.

==A specific example==

For the rest of this document, I will use a particular example, because it should make the explanation easier. You should be able to see how to generalise it.

We will suppose you that you are making a new question type myqtype. This is plugin type qtype, and the code will be in the question/type/myqtype folder. The currently installed version number will be stored in the ('qtype_myqtype', 'version') row of the mdl_config_plugins table.

In addition, we will just consider the first two releases of the plugin. The first release will have version number 2008080100, and will just use one database table mdl_myqtype_options, with two columns col1 and col2. Then we will suppose that the second release is 2008080200, and that requires an extra column, newcol, to be added to the mdl_myqtype_options table.

==The files you need for the first release==

In what follows, the bits of code you need to replace are '''in bold'''.

;version.php
$plugin->version = 2008080100; // Today's date in YYYYMMDD format, plus two additional digits
$plugin->requires = '''XXXXXXXXXX; // Moodle version - copy from $version in the top-level version.php file.'''
:Version numbers normally consist of the day's date in YYYYMMDD format, followed by two additional digits to allow for multiple versions in the same day, e.g. Sept 15, 2010 could have versions 2010091500, 2010091501, 2010091502, etc.

;db/install.xml
:This file, which you should [[XMLDB editor|create with the XMLDB editor]], should contain the definition for your mdl_myqtype_options table, with the two columns col1 and col2.

At this stage, you do not need a db/upgrade.php file.

==The files you need for the second release==

;version.php
$plugin->version = 2008080200;
$plugin->requires = '''XXXXXXXXXX; // Copy the current value from the top-level version.php file.'''
;db/install.xml : This file should now contain the updated definition for your mdl_myqtype_options table, with three columns col1, col2 and newcol. You modify this file using the XMLDB editor.
;db/upgrade.php
:This file should contain the code that people need to run to upgrade from version 2008080100 of your plugin. That is, the code to add a column newcol to the mdl_myqtype_options table. You don't have to write this code yourself as the XMLDB editor will generate it for you. The upgrade.php file should contain a single function xmldb_qtype_myqtype_upgrade that looks a bit like:
function xmldb_qtype_myqtype_upgrade($oldversion = 0) {
global $DB;
$dbman = $DB->get_manager();

$result = true;

/// Add a new column newcol to the mdl_myqtype_options
if ($result && $oldversion < 2008080200) {
'''// Code to add the column, generated by the 'View PHP Code' option of the XMLDB editor.'''
}

return $result;
}

''Hint: If you are modifying or adding a field/table, get the XMLDB editor to generate the PHP update code for you '''after''' making the changes in the editor. If you are deleting one, you need to generate the PHP code '''before''' making the change - or you won't be able to select the field/table to write the code for, because it no longer exists.''

==What happens when a user installs or upgrades your plugin==

The process is triggered when an administrator goes to the Admin notifications page (.../admin/index.php). The code that does the work is the upgrade_plugins function in lib/adminlib.php and reading this code is the best way to find out exactly what happens. In pseudo-code, what it does is:

For each plugin of this type (e.g. all qtype plugins) {
// For the body of this loop, suppose the current plugin being processed is myqtype.

Check that question/type/myqtype/version.php, .../db/upgrade.php and .../db/install.xml exist.

if (get_config('qtype_myqtype', 'version') exists, and is less than the number in version.php) {
Call the upgrade function xmldb_qtype_myqtype_upgrade from upgrade.php,
passing the old version number that says what is currently installed
set_config('version', ''latest number from version.php'', 'qtype_myqtype')
to record what is currently installed

} else if (get_config('qtype_myqtype', 'version') does not exist) {
Create the tables from the definitions in install.xml
set_config('version', ''latest number from version.php'', 'qtype_myqtype')
to record what is currently installed
}
}

Of course, it is a bit more complex that than. However, the code in the upgrade_plugins is quite clear, and I encourage you to go and have a look at it so you can see all the details of how it works.

Let us now look at some worked examples:

===User installs version 2008080100 of myqtype===

To start with, the mdl_myqtype_options does not exist, and there will not be a ('qtype_myqtype', 'version') row in the mdl_config_plugins table.

# The user will unzip myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for the qtype_myqtype plugin is now present, but there is no trace of it in the database, so it will install the plugin from the install.xml file.

At the end of this process, the mdl_myqtype_options table will exist with the two columns col1 and col2; and the ('qtype_myqtype', 'version') row in the mdl_config_plugins table will contain 2008080100.

===User upgrades from version 2008080100 to version 2008080200 of myqtype===

To start with, the mdl_myqtype_options table will exist with the two columns col1 and col2; and the ('qtype_myqtype', 'version') row in the mdl_config_plugins table will contain 2008080100.

# The user will delete the old question/type/myqtype folder.
# The user will unzip the new myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for version 2008080200 the qtype_myqtype plugin is now present, but the installed version of the the database tables ('qtype_myqtype', 'version') is 2008080100. Therefore, it will call xmldb_qtype_myqtype_upgrade from upgrade.php, passing 2008080100 as the $oldversion argument.

At the end of this process, the mdl_myqtype_options table will now have three columns col1, col2 and newcol; and the ('qtype_myqtype', 'version') row in the mdl_config_plugins table will contain 2008080200.

===User installs version 2008080200 of myqtype into a clean Moodle install===

To start with, the mdl_myqtype_options does not exist, and there will not be a ('qtype_myqtype', 'version') row in the mdl_config_plugins table.

# The user will unzip the 2008080200 version of myqtype.zip into the question/type folder.
# The user will visit the Admin notifications page.
# This will trigger Moodle to search for plugings to upgrade. It will find that the code for the qtype_myqtype plugin is now present, but there is no trace of it in the database, so it will install the plugin from the install.xml file.

At the end of this process, the mdl_myqtype_options table will exist with three columns col1, col2 and newcol; and the ('qtype_myqtype', 'version') row in the mdl_config_plugins table will contain 2008080200.

== Upgrade code restrictions ==

Within an upgrade, there are restrictions on the functions your code should call, because the system has not been fully updated.

* All upgrade code can use the basic database API ($DB->... functions).
* In a '''plugin''', upgrade code should not call '''any plugin functions'''. (For example, if your plugin has a function that changes frog settings to 'green', and you need to do this during upgrade, then you should not call this function; instead, manually update the database rows so that the frog settings become green.) However, you should call core functions rather than making core changes in database.
* In '''core''', upgrade code should not even call '''any core functions'''. (For example, if you need to add a calendar event, this should be done by inserting into a database table rather than calling a function to add the event.)

The reason for this is the state of the system during upgrade.

During core upgrade the state is as follows:

* Core data: '''Old'''.
* Plugin data: '''Old'''.

Core functions expect core data to be in the Current state, so it is not safe to call them.

During plugin upgrade the state is as follows:

* Core data: '''Current'''. (Because core upgrade runs before plugin upgrade.)
* Plugin data: '''Old'''.

Core functions are now safe to call because the core data is in Current state. But plugin functions, which expect data to be in the Current state, are not safe.

==Summary==

The first time a user installs any version of your plugin, the install.xml file will be used to create all the required database tables. Therefore install.xml should always contain the definition of the up-to-date database structure. Moodle recognises this situation because there is a version.php file on disc, but there is no (''plugintype''_''pluginname'', version) value in the mdl_config_plugins table.

If the user already had a version of your plugin installed, and then upgrades to a newer version, Moodle will detect this because the version.php file will contain a newer version number than the (''plugintype''_''pluginname'', version) value in the mdl_config_plugins table. In this case, Moodle will run the code in the upgrade.php file, passing in the old version number, so that the correct bits of upgrade can be run, as controlled by the if ($oldversion < XXXXXXXXXX) blocks of code.

The contents of the install.xml and upgrade.php files should be generated using the XMLDB editor.

==Other things that can be in the db folder==

Of these, only install.php relates to creating the necessary database structure. The other files are mainly about providing the other meta-data that is required when the plugin is installed. I have tried to link to other documentation that goes into detail where possible.

===install.php===

(Moodle 2.0 and later)

If you define a function like xmldb_qtype_myqtype_install(), this PHP code will be executed when your plugin is installed. This is an opportunity to do things that you cannot do with install.xml. It's executed immediately after the DB schema associated with the component (install.xml) is created.

(Moodle 1.9)

An install function can be defined in lib.php in the root directory of your module. The install function must have the name qtype_install() and takes no arguments (n.b. this is called from lib/adminlib.php after install.xml is parsed)

===uninstall.php===

(Moodle 2.0 and later)

Balancing the previous feature, it's also possible to define one function like xmldb_qtype_myqtype_uninstall(), that will be executed when your plugin is uninstalled, before dropping its DB schema.

===access.php===

(Moodle 1.7 and later)

Use to define the [[Roles#Capabilities|capabilities]] that this plugin handles with the [[Access API]]. You must increase version in version.php after adding new capabilities.

===events.php===

(Moodle 1.9(?) and later)

Used to define the events this plugin sends to the [[Events_API|Events API]]. You must increase version in version.php after modifying or adding new events.

===log.php===

(Moodle 2.0 and later)

Used to describe the type of log entries that this plugin creates. See the [[Logging API#Mod/*/db/log.php Files| log.php section]] of the [[Logging API]] for more information. You must increase version in version.php after any change.

===messages.php===

(Moodle 2.0 and later)

Used to define the messages this plugin sends through the [[Message API|Messaging API]]. You must increase version in version.php after any change.

===services.php===

(Moodle 2.0 and later)

Used to define the functions and services this plugin publishes through the [[Web services API]]. Usually all those functions are part of the [[External functions API]]. You must increase version in version.php after any change.

===upgradelib.php===

Optional file where upgrade code can be grouped under some '''helper functions''' to be used in the upgrade.php file. If needed, this file must be '''manually required''' once from upgrade.php. Its main goal is to keep the upgrade.php scripts reduced and clear (this cannot contain any function themselves apart from the xmldb_xxx_upgrade() one).

It's '''important''' to note that the upgradelib.php files should always be performing any task using raw - low level - database access exclusively, '''avoiding any use of the Moodle APIs'''.

===mod/.../db/subplugins.php===

(Moodle 2.0 and later)

This only applies to activity modules, not other types of plugin. It is a way to allow an activity module to have its own sorts of plugins. For example workshop allocation schemes, or quiz reports.

==Language packs==

Do not forget to increase version number after modifying lang/en/type_yourplugin.php language file. See [[Languages/AMOS]] section AMOS script for more information.

==Upgrade API Cheatsheet==

The Upgrade API is '''related with a lot''' of different files and APIs (access, event, log, webservice...) as far as it's the API used to install/upgrade all those artifacts. The previous sections have tried to list all those dependencies when possible.

Also, the Upgrade API '''does a very intensive use''' of other APIs ([[Data definition API|ddl]], [[Data manipulation API|dml]]) and tools (the XMLDB editor...) in order to proceed with the modifications of the Moodle system.

Once stated the above, we could summarise the API as the '''collection of a few files and functions''', here they are:

'''The files''': For each component we can have, under its "db" directory.
* '''version.php''': Where the $version is specified and, if bumped, the upgrade machinery will be launched and all caches reset. Bump up version after changing /db/, /lang/, theme or JavaScript.
* '''install.xml''': XMLDB definition of the DB schema. generated with the XMLDB Editor.
* '''install.php''': Post-install file executed once the schema has been created.
* '''uninstall.php''': Pre-uninstall file executed before the schema is dropped.
* '''upgrade.php''': Ordered list of upgrade steps, each one performing a well-defined task.
* '''upgradelib.php''': Library files composed of helper functions to be used by upgrade.php.

'''The functions''': With different names for different components, but available to all them:
* '''xmldb_[main|[[Frankenstyle|frankenstyle]]]_install()''': to be used in install.php files.
* '''xmldb_[main|frankenstyle]_uninstall()''': to be used in uninstall.php files.
* '''xmldb_[main|frankenstyle]_upgrade()''': to be used in upgrade.php files.
* '''upgrade_set_timeout()''': to be used within the upgrade steps in upgrade.php files, in order to grant more time to the step.
* '''upgrade_[main|mod|block|plugin]_savepoint()''': to consider one upgrade step completed and reset timeouts. Avoids double executions.

Of course, for practical examples of the use of this API it's '''highly recommended to examine and understand current code'''. Everything is out there.

==Database upgrades and stable branches==

The simple rule is, never make any database changes on a stable branch. You only need to read this section in the rare situations where a database change on the stable branch is unavoidable.

'''Warning!!! advanced material follows.'''

Suppose, in order to fix a bug, you need to make a database change in Moodle 1.9.3+ (which must also be merged into HEAD). The root of the problem is that people may upgrade their Moodle in three different ways, which

* Upgrade from <=1.9.3 to 1.9.4 - this executes the ugprade script on the 1.9 branch.
* Upgrade from <=1.9.3 directly to >=2.0 - this executes the upgrade script on the HEAD branch.
* Upgrade from 1.9.4 to >=2.0 - in this case, you must ensure that the upgrade on HEAD is not executed.

The normal way to do this is ensure that your database upgrade is idempotent. That is, it does not matter if you do it twice. So for example, instead of doing

$dbman->create_table($table);

you should do

if (!$dbman->table_exists($table)) {
$dbman->create_table($table);
}

You should also think about what version numbers to put in your version.php file on each branch. Above all, test carefully.

==See also==

* [[Core APIs]]
* [[XMLDB_Documentation|XMLDB_Documentation]]
* [[Coding|Coding guidelines]]
* [[DDL functions|DDL functions]]
* [[XMLDB defining an XML structure|install.xml file documentation]]

[[Category:XMLDB]]
[[Category:Installation]]
[[Category:Plugins]]
[[Category:API]]

Themes overview

2010-06-15T01:38:35Z

Stephenla: /* Layouts */ just fixed minor punctuation in text

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

This document explains how themes work in Moodle and is intended to help you create or modify most themes for Moodle 2.0.

==Introduction==

Moodle themes are responsible for much of the "look" of a Moodle site. They provide the CSS for colours, layouts, fonts and so on, and can also change the structural XHTML code below that.

A theme can either contain all the definitions (completely stand alone) or it can extend an existing theme with one or more customizations.

Most theme developers use the second method and simply add a few new CSS or layout definitions to their new theme. If a definition or element is not found in the new theme, it looks to the "parent" (or up the hierarchy of themes) to find one. It an easy way to achieve just about any look you want for a theme.

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

The first setting, $THEME->name 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 defines the themes that the theme will extend. In this case it is extending only the base theme.

After this is the $THEME->sheets 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.

Next we see the $THEME->layouts definition. 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.

The final setting is to include a JavaScript file, as $THEME->javascripts_footer. 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 start out theming, 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\styles\*.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 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 themes styles 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 an 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 put more emphasis on developers for using classes more appropriately.

====The body tag====
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====
The best use of body ids and classes and writing selectors will reduce problems.

There are many specific classes used within Moodle. We try to put them everywhere where anyone may want to apply their own styles. It is important to recognise that no one developer can be aware of the all of the class names that have been used all throughout Moodle, let alone within all of the different contributed bits and pieces available for Moodle. It is up to the theme developer to write good rules and minimise the chances of a collision between rules because in this case good CSS is FAR more effective.

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 orange;)</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 orange;}</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==
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. For both situations these layouts should be defined within config.php.

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.

So layouts... 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.
; file : is the name of the layout file this layout wants to use.
; regions : is the different block regions (places you can put blocks) within the theme.
; defaultregion : is the default location when adding new blocks.
; options : an array of layout specific options described in detail below.

The first four settings are required by each layout definition however 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 infact 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 is 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 VERY simple PHP calls to get bits and pieces including content.

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 echo $PAGE->bodyid ?>" class="<?php echo $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>

Lets assume you know a enough HTML to understand the basic structure above, what you probably don't understand are the PHP calls so lets look at them.
<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 themer 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 echo $PAGE->bodyid; ?>" class="<?php echo $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.

==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 there 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>
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/moodlelogo.gif
# /theme/themename/pix/i/user.gif
How easy is that!

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/moodlelogo.png
# /theme/themename/pix/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]]

==Appendix A==
===Theme options as of April 28th, 2010===
{| 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.
|}
===The different layouts as of March 29th, 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.
|}

==See also==
* [[Themes 2.0 creating your first theme]] - A quick step by step guide to creating your first theme.
* [[Themes 2.0 overriding a renderer]] - A tutorial on creating a custom renderer and changing the HTML Moodle produces.
* [[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.
* [[Styling_and_customising_the_dock]] - How to style and customise the dock.
* [[Theme changes in 2.0]]
* [[Using jQuery with Moodle 2.0]]