2011-04-17T06:22:45Z

Tqr: /* Re-naming some elements */

{{Template:Themes}}{{Moodle 2.0}}This document describes how to clone a theme from an existing Moodle 2.0. theme. It assumes you have some understanding of how themes work within Moodle, as well as a basic understanding of HTML and CSS.

==Getting started==

The first thing to create is a copy of the theme folder, of the theme, you want to clone. For the purpose of this tutorial, we will be cloning '''Boxxie''', which is one of several Moodle '''core''' themes.

From your Moodle '''theme''' directory '''right click''' on '''boxxie''' and then '''''copy''' and '''paste''''' back into your Moodle '''theme''' directory. You should now have a folder called '''Copy of boxxie'''. If you '''right click''' this folder you are given the option to '''Rename''' it. So let's rename this folder to '''foxxie''' (or to whatever name you want to call your '''cloned''' theme).

If you open the '''foxxie''' directory you will find several directories, sub-directories and files within it. One of these sub-directories '''''lang/en/''''' contain a file '''theme_boxxie.php''' which will need to be re-named. But we shall address this later. For now just familiarise yourself with what you find in the '''foxxie''' directory.

These are:
; config.php : Where all the theme settings are.
; /lang/ : This directory contains all language sub-directories.
; /lang/en/ : This sub-directory contains your language files, in this case ''English''.
; /lang/en/theme_boxxie.php : This file contains all the language strings for your theme.
; /layout/ : This directory contains all the layout files for this theme.
; /layout/frontpage.php : Layout file for front page.
; /layout/general.php : Layout file for general pages.
; /layout/embedded.php : Layout file for embedded pages.
; /style/ : This directory contains all the CSS files for this theme.
; /style/core.css : Contains all the CSS rules for this theme.
; /style/boilerplate.css : Contains all the ''reset'' CSS rules for this theme.
; /pix/ : This directory contains a screen shot of this theme as well as a favicon and any images used in the theme.
; /pix/tabs : This contains all the tab images for this theme.

==Re-naming some elements==

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

////////////////////////////////////////////////////
// Name of the theme. Most likely the name of
// the directory in which this file resides.
////////////////////////////////////////////////////
</code>
The next place to look, as mentioned above, is '''lang/en/theme_boxxie.php'''. This file, as well as needing to be renamed, also needs some of its content renaming too. So before we forget, let's '''right click''' on this file and '''rename''' it '''theme_foxxie.php''' before we open it.

== Language Strings ==

When you open this file you will see lots of language $strings (''see below'') which are used for any customised words or phrases used in this theme. Because this is in the '''foxxie/lang/en/''' directory all the $strings are in English. But if you wanted to add some foreign words and phrases for whenever a user switched languages, you just need to create a new sub-directory in the '''foxxie/lang/''' directory for the language files you need to add there, and then copy and paste this file to that new sub-directory. For example: '''foxxie/lang/it/theme_foxxie.php''' (where '''it''' is the code which represents the Italian language). We will explore the Language aspect of themes in another Moodle Doc. So let's just concentrate on the changes we need to make to the contents of '''theme_foxxie.php'''.
<code php>
/**
* Strings for component 'theme_boxxie', language 'en', branch 'MOODLE_20_STABLE'
*
* @package moodlecore
* @copyright 2010 Patrick Malley
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

$string['pluginname'] = 'Boxxie';
$string['region-side-post'] = 'Right';
$string['region-side-pre'] = 'Left';
$string['choosereadme'] = '<div class="clearfix"><div class="theme_screenshot"><h2>Boxxie</h2><img src="boxxie/pix/screenshot.jpg" /><h3>Theme Discussion Forum:</h3><p><a href="http://moodle.org/mod/forum/view.php?id=46">http://moodle.org/mod/forum/view.php?id=46</a></p><h3>Theme Credits</h3><p><a href="https://docs.moodle.org/en/Theme_credits">https://docs.moodle.org/en/Theme_credits</a></p><h3>Theme Documentation:</h3><p><a href="https://docs.moodle.org/en/Themes">https://docs.moodle.org/en/Themes</a></p><h3>Report a bug:</h3><p><a href="http://tracker.moodle.org">http://tracker.moodle.org</a></p></div><div class="theme_description"><h2>About</h2><p>Boxxie is a fluid-width, three-column theme for Moodle 2.0.<h2>Tweaks</h2><p>This theme is built upon both Base and Canvas, two parent themes included in the Moodle core. If you want to modify this theme, we recommend that you first duplicate it then rename it before making your changes. This will prevent your customized theme from being overwritten by future Moodle upgrades, and you\'ll still have the original files if you make a mess. More information on modifying themes can be found in the <a href="https://docs.moodle.org/en/Theme">MoodleDocs</a>.</p><h2>Credits</h2><p>This theme was coded and is maintained by Patrick Malley. He can be contacted by email at contact@newschoollearning.com. </p>
<h3>License</h3><p>This, and all other themes included in the Moodle core, are licensed under the <a href="http://www.gnu.org/licenses/gpl.html">GNU General Public License</a>.</div></div>';</code>

==See also==
* [[Development:Themes 2.0 FAQ]]

[[Category:Themes]]

Development:Themes 2.0 how to clone a Moodle 2.0 theme

2011-04-17T06:11:32Z

Tqr: /* Re-naming some elements */

Development:Themes 2.0 how to clone a Moodle 2.0 theme

2011-04-17T06:07:43Z

Tqr: /* Re-naming some elements */

Development:Themes 2.0 how to clone a Moodle 2.0 theme

2011-04-17T06:05:29Z

Tqr: /* Re-naming some elements */

Development:Themes 2.0 how to clone a Moodle 2.0 theme

2011-04-17T06:03:49Z

Tqr: /* Getting started */

Development:Themes 2.0 how to clone a Moodle 2.0 theme

2011-04-17T06:02:46Z

Tqr: /* Getting started */

Development:Themes 2.0 how to clone a Moodle 2.0 theme

2011-04-17T06:00:49Z

Tqr: /* Re-naming some elements */

Development:Themes 2.0 how to clone a Moodle 2.0 theme

2011-04-17T05:58:39Z

Tqr:

Development:Themes 2.0 how to clone a Moodle 2.0 theme

2011-04-17T05:52:49Z

Tqr: /* Re-naming some elements */

Development:Themes 2.0 how to clone a Moodle 2.0 theme

2011-04-17T05:46:51Z

Tqr: /* Re-naming some elements */

Development:Themes 2.0 how to clone a Moodle 2.0 theme

2011-04-17T05:42:46Z

Tqr: Created page with "{{Template:Themes}}{{Moodle 2.0}}This document describes how to clone a theme from an existing Moodle 2.0. theme. It assumes you have some understanding of how themes work within..."

Development:Themes 2.0

2011-04-17T03:47:17Z

Tqr: added new page to list

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

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

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

'''$OUTPUT''' is an instance of the '''core_renderer''' 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 '''moodle_page''' 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, some magic is going on, and 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.)

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

'''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/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 [[Development: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 /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.

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

* [[Development:Themes 2.0 creating your first theme]] - A quick step by step guide to creating your first theme.
* [[Development:Themes 2.0 overriding a renderer]] - A tutorial on creating a custom renderer and changing the HTML Moodle produces.
* [[Development:Themes 2.0 How to use images within your theme]] - Explains how to use and override images within your theme.
* [[Development:Themes 2.0 adding a settings page]] - Looks at how to add a setting page making your theme easily customisable.
* [[Development:Themes 2.0 extending the custom menu]] - Customising the custom menu.
* [[Development:Themes 2.0 how to make the dock horizontal]] - Modifying the dock to make it horizontal.
* [[Development:Themes 2.0 adding upgrade code]]
* [[Development:Styling and customising the dock]] - How to style and customise the dock.
* [[Development:Theme changes in 2.0]]
* [[Development:Using jQuery with Moodle 2.0]]
* [[Development:Themes 2.0 how to clone a Moodle 2.0 theme]]
* [http://www.youtube.com/watch?v=OvaU54uh-qA New themes in Moodle 2.0 video]

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

Development:Using jQuery with Moodle 2.0

2011-04-07T20:50:20Z

Tqr: /* Themes */

{{Moodle 2.0}}Having just been helping someone with a jQuery integration I thought I would document the simple process of including the jQuery library within a theme, block, or module and how to make use of it.

==Before we begin==
Moodle has officially chosen to use the YUI JavaScript library and it is encouraged to use that wherever possible. That being said, jQuery is very popular, and for what ever reason, it may be required.

I can't guarantee what you are doing will work nicely next to YUI, but hopefully it will!

So first up, make sure you get the latest jQuery files from http://docs.jquery.com/Downloading_jQuery. For the purposes of this document I have downloaded jquery-1.4.2.min.js.

You will also need to decide where to load the JavaScript. Moodle can load JavaScript into either the pages head, or at the bottom of the page (footer). Loading it into the footer is what Moodle does by default and is certainly the preferable solution if possible. It ensures that the page loads and renderers faster. However, if you need code immediately within the page WHILE it is loading, then you will want to include it in the head.

==Including jQuery within a plugin==
===Themes===
Themes are not the easiest type of plugin to include jQuery, but if you are working on an installation that will be using a lot of customised code, then probably it is the best place.

# Open the theme you want to add jQuery to in a file browser and if there isn't already a '''javascript''' directory create one.
# Copy the jQuery files you want to make use of into the javascript directory of the theme.
# Open the themes config.php in your favourite editor (Notepad)
#* If you want to load your jQuery into the footer [recommended] then locate '''$THEME->javascripts_footer...'''
#* If you want to load it into the header then located '''$THEME->javascripts...'''
#* If the one you want doesn't exist create it now at the bottom of the config.php file: $THEME->javascripts_footer = array();
# Add the names of the jQuery files you've just copied into the javascript folder to the config option you just found/created. The names should be in single quotes and separated by commas. You do *NOT* need to put the file extension just the name.

You should end up with the following directory structure:

* moodle/theme/standard/javascript/jquery-1.4.2.min.js
* moodle/theme/standard/javascript/another.file.js

And the following entry in your themes config.php file:
<code php>
// Remember we don't put the file extension so no .js at the end
$THEME->javascripts_footer = array('jquery-1.4.2.min', 'another.file');
</code>

And with that jQuery is now being loaded within your theme!

However you won't see it immediately, first you need to clear Moodles theme cache. This can be done is two ways when logged in as an Admin:

# Site Administration > Appearance > Themes > Theme selector. At the top of the page will be a button to invalidate the theme cache.
# Site Administration > Appearance > Themes > Theme settings. Turn on Theme Designer Mode.

I would highly recommend turning theme designer mode on if you are going to making lots of changes to your themes CSS or JavaScript otherwise you will need to invalidate your theme caches after every change. Do note however that turning it on will reduce your performance as nothing will be cached.

You should also note that Moodle combines all of the JavaScript for a theme into a single file for the header and a single file for the footer. This file is all of the JavaScript files for the section combined into a single file and minified. If you use a tool such as Firebug to view the JavaScript look for a file with a URL pointing to '''theme/javascript.php?...type=footer'''. All of the JavaScript will be in there.

When adding files to the $THEME->javascripts array the files are added in the order you specify, so the first file gets included first.

===Blocks and modules===
This is much simplier than including jQuery from within a theme.

# Create a '''javascript''' directory within your Module, this is where we will put the jQuery files (and probably any other JavaScript files you need)
# Copy the jQuery files into the javascript folder.
# Add the following lines of php into every file which will make use of jQuery.

<code php>
$PAGE->requires->js('path/to/plugin/javascript/jquery-1.4.2.min.js');
// $PAGE->requires->js('mod/modname/javascript/jquery-1.4.2.min.js');
// $PAGE->requires->js('blocks/blockname/javascript/jquery-1.4.2.min.js');
</code>

And that's it, it is served within the footer of those pages.

If you want to include jQuery within the page header however you will need to specify true as the second argument.
<code php>
$PAGE->requires->js('path/to/plugin/javascript/jquery-1.4.2.min.js', true);
</code>

==Potential problems==
You should be aware that jQuery is only designed to be included within a page once, unfortunately you are the controller of this and will need to ensure it complies.

If you are writing customisations for your own site then it is not a problem, you can either include it within your theme once (and know it will be everywhere), or you can move the files to a central location (e.g. moodle/lib/jquery/*) and then include them from there using the block and module syntax.

If however you are using third party plugins, where more than one is making use of jQuery, you may find VERY strange things happening. You will either need to remove the modules or move the jQuery files to a central location, as above, edit the plugins to find the files there.

Note: A file within one location will only be included once within a page.

For these reasons it is '''HIGHLY''' recommended to use YUI for everything possible.

==More information==
For more information on how to use JavaScript within Moodle 2.0 please see [[Development:JavaScript guidelines]]

* [[Development:JavaScript guidelines]]
* [[Development:Themes 2.0]]

* [[Javascript FAQ]]

Development:Using jQuery with Moodle 2.0

2011-04-07T20:42:40Z

Tqr: /* Before we begin */

{{Moodle 2.0}}Having just been helping someone with a jQuery integration I thought I would document the simple process of including the jQuery library within a theme, block, or module and how to make use of it.

==Before we begin==
Moodle has officially chosen to use the YUI JavaScript library and it is encouraged to use that wherever possible. That being said, jQuery is very popular, and for what ever reason, it may be required.

I can't guarantee what you are doing will work nicely next to YUI, but hopefully it will!

So first up, make sure you get the latest jQuery files from http://docs.jquery.com/Downloading_jQuery. For the purposes of this document I have downloaded jquery-1.4.2.min.js.

You will also need to decide where to load the JavaScript. Moodle can load JavaScript into either the pages head, or at the bottom of the page (footer). Loading it into the footer is what Moodle does by default and is certainly the preferable solution if possible. It ensures that the page loads and renderers faster. However, if you need code immediately within the page WHILE it is loading, then you will want to include it in the head.

==Including jQuery within a plugin==
===Themes===
This isn't the easiest type of plugin to include jQuery within but if you are working on an installation that will be using a lot of customised code then probably the best place.

# Open the theme you want to add jQuery to in a file browser and if there isn't already a '''javascript''' directory create one.
# Copy the jQuery files you want to make use of into the javascript directory of the theme.
# Open the themes config.php in your favourite editor
#* If you want to load your jQuery into the footer [recommended] then locate '''$THEME->javascripts_footer...'''
#* If you want to load it into the header then located '''$THEME->javascripts...'''
#* If the one you want doesn't exist create it now at the bottom of the config.php file: $THEME->javascripts_footer = array();
# Add the names of the jQuery files you've just copied into the javascript folder to the config option you just found/created. The names should be in single quotes and separated by commas. You do *NOT* need to put the file extension just the name.

You should end up with the following directory structure:

* moodle/theme/standard/javascript/jquery-1.4.2.min.js
* moodle/theme/standard/javascript/another.file.js

And the following entry in your themes config.php file:
<code php>
// Remember we don't put the file extension so no .js at the end
$THEME->javascripts_footer = array('jquery-1.4.2.min', 'another.file');
</code>

And with that jQuery is now being loaded within your theme!

However you won't see it immediately, first you need to clear Moodles theme cache. This can be done is two ways when logged in as an Admin:

# Site Administration > Appearance > Themes > Theme selector. At the top of the page will be a button to invalidate the theme cache.
# Site Administration > Appearance > Themes > Theme settings. Turn on Theme Designer Mode.

I would highly recommend turning theme designer mode on if you are going to making lots of changes to your themes CSS or JavaScript otherwise you will need to invalidate your theme caches after every change. Do note however that turning it on will reduce your performance as nothing will be cached.

You should also note that Moodle combines all of the JavaScript for a theme into a single file for the header and a single file for the footer. This file is all of the JavaScript files for the section combined into a single file and minified. If you use a tool such as Firebug to view the JavaScript look for a file with a URL pointing to '''theme/javascript.php?...type=footer'''. All of the JavaScript will be in there.

When adding files to the $THEME->javascripts array the files are added in the order you specify, so the first file gets included first.

===Blocks and modules===
This is much simplier than including jQuery from within a theme.

# Create a '''javascript''' directory within your Module, this is where we will put the jQuery files (and probably any other JavaScript files you need)
# Copy the jQuery files into the javascript folder.
# Add the following lines of php into every file which will make use of jQuery.

<code php>
$PAGE->requires->js('path/to/plugin/javascript/jquery-1.4.2.min.js');
// $PAGE->requires->js('mod/modname/javascript/jquery-1.4.2.min.js');
// $PAGE->requires->js('blocks/blockname/javascript/jquery-1.4.2.min.js');
</code>

And that's it, it is served within the footer of those pages.

If you want to include jQuery within the page header however you will need to specify true as the second argument.
<code php>
$PAGE->requires->js('path/to/plugin/javascript/jquery-1.4.2.min.js', true);
</code>

==Potential problems==
You should be aware that jQuery is only designed to be included within a page once, unfortunately you are the controller of this and will need to ensure it complies.

If you are writing customisations for your own site then it is not a problem, you can either include it within your theme once (and know it will be everywhere), or you can move the files to a central location (e.g. moodle/lib/jquery/*) and then include them from there using the block and module syntax.

If however you are using third party plugins, where more than one is making use of jQuery, you may find VERY strange things happening. You will either need to remove the modules or move the jQuery files to a central location, as above, edit the plugins to find the files there.

Note: A file within one location will only be included once within a page.

For these reasons it is '''HIGHLY''' recommended to use YUI for everything possible.

==More information==
For more information on how to use JavaScript within Moodle 2.0 please see [[Development:JavaScript guidelines]]

* [[Development:JavaScript guidelines]]
* [[Development:Themes 2.0]]

* [[Javascript FAQ]]

Development:Using jQuery with Moodle 2.0

2011-04-07T20:40:59Z

Tqr: /* Before we begin */

{{Moodle 2.0}}Having just been helping someone with a jQuery integration I thought I would document the simple process of including the jQuery library within a theme, block, or module and how to make use of it.

==Before we begin==
Moodle has officially chosen to use the YUI JavaScript library and it is encouraged to use that wherever possible. That being said, jQuery is very popular, and for what ever reason, it may be required.

I can't guarantee what you are doing will work nicely next to YUI, but hopefully it will!

So first up, make sure you get the latest jQuery files from http://docs.jquery.com/Downloading_jQuery. For the purposes of this document I have downloaded jquery-1.4.2.min.js.

You will also need to decide where to load the JavaScript, Moodle can load JavaScript into either the pages head, or at the bottom of the page (footer). Loading it into the footer is what Moodle does by default and is certainly the preferable solution if possible. It ensures that the page loads and renderers faster. However, if you need code immediately within the page WHILE it is loading, then you will want to include it in the head.

==Including jQuery within a plugin==
===Themes===
This isn't the easiest type of plugin to include jQuery within but if you are working on an installation that will be using a lot of customised code then probably the best place.

# Open the theme you want to add jQuery to in a file browser and if there isn't already a '''javascript''' directory create one.
# Copy the jQuery files you want to make use of into the javascript directory of the theme.
# Open the themes config.php in your favourite editor
#* If you want to load your jQuery into the footer [recommended] then locate '''$THEME->javascripts_footer...'''
#* If you want to load it into the header then located '''$THEME->javascripts...'''
#* If the one you want doesn't exist create it now at the bottom of the config.php file: $THEME->javascripts_footer = array();
# Add the names of the jQuery files you've just copied into the javascript folder to the config option you just found/created. The names should be in single quotes and separated by commas. You do *NOT* need to put the file extension just the name.

You should end up with the following directory structure:

* moodle/theme/standard/javascript/jquery-1.4.2.min.js
* moodle/theme/standard/javascript/another.file.js

And the following entry in your themes config.php file:
<code php>
// Remember we don't put the file extension so no .js at the end
$THEME->javascripts_footer = array('jquery-1.4.2.min', 'another.file');
</code>

And with that jQuery is now being loaded within your theme!

However you won't see it immediately, first you need to clear Moodles theme cache. This can be done is two ways when logged in as an Admin:

# Site Administration > Appearance > Themes > Theme selector. At the top of the page will be a button to invalidate the theme cache.
# Site Administration > Appearance > Themes > Theme settings. Turn on Theme Designer Mode.

I would highly recommend turning theme designer mode on if you are going to making lots of changes to your themes CSS or JavaScript otherwise you will need to invalidate your theme caches after every change. Do note however that turning it on will reduce your performance as nothing will be cached.

You should also note that Moodle combines all of the JavaScript for a theme into a single file for the header and a single file for the footer. This file is all of the JavaScript files for the section combined into a single file and minified. If you use a tool such as Firebug to view the JavaScript look for a file with a URL pointing to '''theme/javascript.php?...type=footer'''. All of the JavaScript will be in there.

When adding files to the $THEME->javascripts array the files are added in the order you specify, so the first file gets included first.

===Blocks and modules===
This is much simplier than including jQuery from within a theme.

# Create a '''javascript''' directory within your Module, this is where we will put the jQuery files (and probably any other JavaScript files you need)
# Copy the jQuery files into the javascript folder.
# Add the following lines of php into every file which will make use of jQuery.

<code php>
$PAGE->requires->js('path/to/plugin/javascript/jquery-1.4.2.min.js');
// $PAGE->requires->js('mod/modname/javascript/jquery-1.4.2.min.js');
// $PAGE->requires->js('blocks/blockname/javascript/jquery-1.4.2.min.js');
</code>

And that's it, it is served within the footer of those pages.

If you want to include jQuery within the page header however you will need to specify true as the second argument.
<code php>
$PAGE->requires->js('path/to/plugin/javascript/jquery-1.4.2.min.js', true);
</code>

==Potential problems==
You should be aware that jQuery is only designed to be included within a page once, unfortunately you are the controller of this and will need to ensure it complies.

If you are writing customisations for your own site then it is not a problem, you can either include it within your theme once (and know it will be everywhere), or you can move the files to a central location (e.g. moodle/lib/jquery/*) and then include them from there using the block and module syntax.

If however you are using third party plugins, where more than one is making use of jQuery, you may find VERY strange things happening. You will either need to remove the modules or move the jQuery files to a central location, as above, edit the plugins to find the files there.

Note: A file within one location will only be included once within a page.

For these reasons it is '''HIGHLY''' recommended to use YUI for everything possible.

==More information==
For more information on how to use JavaScript within Moodle 2.0 please see [[Development:JavaScript guidelines]]

* [[Development:JavaScript guidelines]]
* [[Development:Themes 2.0]]

* [[Javascript FAQ]]

Development:Using jQuery with Moodle 2.0

2011-04-07T20:35:39Z

Tqr: /* Potential problems */

{{Moodle 2.0}}Having just been helping someone with a jQuery integration I thought I would document the simple process of including the jQuery library within a theme, block, or module and how to make use of it.

==Before we begin==
Moodle has officially chosen to use the YUI JavaScript library and it is encouraged to use that wherever possible. That being said jQuery is very popular and for what ever reason it may be required.

I can't guarantee what you are doing will work nicely next to YUI but hopefully it will!

So first up make sure you get the latest jQuery files from http://docs.jquery.com/Downloading_jQuery. For the purposes of this document I have downloaded jquery-1.4.2.min.js.

You will also need to decide where to load the JavaScript, Moodle can load JavaScript into either the pages head, or at the bottom of the page. Loading it into the footer is what Moodle does by default and is certainly the preferable solution if possible. It ensures that the page loads and renderers faster. However if you need code immediately within the page WHILE it is loading then you will want to include it in the head.

==Including jQuery within a plugin==
===Themes===
This isn't the easiest type of plugin to include jQuery within but if you are working on an installation that will be using a lot of customised code then probably the best place.

# Open the theme you want to add jQuery to in a file browser and if there isn't already a '''javascript''' directory create one.
# Copy the jQuery files you want to make use of into the javascript directory of the theme.
# Open the themes config.php in your favourite editor
#* If you want to load your jQuery into the footer [recommended] then locate '''$THEME->javascripts_footer...'''
#* If you want to load it into the header then located '''$THEME->javascripts...'''
#* If the one you want doesn't exist create it now at the bottom of the config.php file: $THEME->javascripts_footer = array();
# Add the names of the jQuery files you've just copied into the javascript folder to the config option you just found/created. The names should be in single quotes and separated by commas. You do *NOT* need to put the file extension just the name.

You should end up with the following directory structure:

* moodle/theme/standard/javascript/jquery-1.4.2.min.js
* moodle/theme/standard/javascript/another.file.js

And the following entry in your themes config.php file:
<code php>
// Remember we don't put the file extension so no .js at the end
$THEME->javascripts_footer = array('jquery-1.4.2.min', 'another.file');
</code>

And with that jQuery is now being loaded within your theme!

However you won't see it immediately, first you need to clear Moodles theme cache. This can be done is two ways when logged in as an Admin:

# Site Administration > Appearance > Themes > Theme selector. At the top of the page will be a button to invalidate the theme cache.
# Site Administration > Appearance > Themes > Theme settings. Turn on Theme Designer Mode.

I would highly recommend turning theme designer mode on if you are going to making lots of changes to your themes CSS or JavaScript otherwise you will need to invalidate your theme caches after every change. Do note however that turning it on will reduce your performance as nothing will be cached.

You should also note that Moodle combines all of the JavaScript for a theme into a single file for the header and a single file for the footer. This file is all of the JavaScript files for the section combined into a single file and minified. If you use a tool such as Firebug to view the JavaScript look for a file with a URL pointing to '''theme/javascript.php?...type=footer'''. All of the JavaScript will be in there.

When adding files to the $THEME->javascripts array the files are added in the order you specify, so the first file gets included first.

===Blocks and modules===
This is much simplier than including jQuery from within a theme.

# Create a '''javascript''' directory within your Module, this is where we will put the jQuery files (and probably any other JavaScript files you need)
# Copy the jQuery files into the javascript folder.
# Add the following lines of php into every file which will make use of jQuery.

<code php>
$PAGE->requires->js('path/to/plugin/javascript/jquery-1.4.2.min.js');
// $PAGE->requires->js('mod/modname/javascript/jquery-1.4.2.min.js');
// $PAGE->requires->js('blocks/blockname/javascript/jquery-1.4.2.min.js');
</code>

And that's it, it is served within the footer of those pages.

If you want to include jQuery within the page header however you will need to specify true as the second argument.
<code php>
$PAGE->requires->js('path/to/plugin/javascript/jquery-1.4.2.min.js', true);
</code>

==Potential problems==
You should be aware that jQuery is only designed to be included within a page once, unfortunately you are the controller of this and will need to ensure it complies.

If you are writing customisations for your own site then it is not a problem, you can either include it within your theme once (and know it will be everywhere), or you can move the files to a central location (e.g. moodle/lib/jquery/*) and then include them from there using the block and module syntax.

If however you are using third party plugins, where more than one is making use of jQuery, you may find VERY strange things happening. You will either need to remove the modules or move the jQuery files to a central location, as above, edit the plugins to find the files there.

Note: A file within one location will only be included once within a page.

For these reasons it is '''HIGHLY''' recommended to use YUI for everything possible.

==More information==
For more information on how to use JavaScript within Moodle 2.0 please see [[Development:JavaScript guidelines]]

* [[Development:JavaScript guidelines]]
* [[Development:Themes 2.0]]

* [[Javascript FAQ]]

Development:Using jQuery with Moodle 2.0

2011-04-07T20:33:49Z

Tqr: /* Potential problems */

{{Moodle 2.0}}Having just been helping someone with a jQuery integration I thought I would document the simple process of including the jQuery library within a theme, block, or module and how to make use of it.

==Before we begin==
Moodle has officially chosen to use the YUI JavaScript library and it is encouraged to use that wherever possible. That being said jQuery is very popular and for what ever reason it may be required.

I can't guarantee what you are doing will work nicely next to YUI but hopefully it will!

So first up make sure you get the latest jQuery files from http://docs.jquery.com/Downloading_jQuery. For the purposes of this document I have downloaded jquery-1.4.2.min.js.

You will also need to decide where to load the JavaScript, Moodle can load JavaScript into either the pages head, or at the bottom of the page. Loading it into the footer is what Moodle does by default and is certainly the preferable solution if possible. It ensures that the page loads and renderers faster. However if you need code immediately within the page WHILE it is loading then you will want to include it in the head.

==Including jQuery within a plugin==
===Themes===
This isn't the easiest type of plugin to include jQuery within but if you are working on an installation that will be using a lot of customised code then probably the best place.

# Open the theme you want to add jQuery to in a file browser and if there isn't already a '''javascript''' directory create one.
# Copy the jQuery files you want to make use of into the javascript directory of the theme.
# Open the themes config.php in your favourite editor
#* If you want to load your jQuery into the footer [recommended] then locate '''$THEME->javascripts_footer...'''
#* If you want to load it into the header then located '''$THEME->javascripts...'''
#* If the one you want doesn't exist create it now at the bottom of the config.php file: $THEME->javascripts_footer = array();
# Add the names of the jQuery files you've just copied into the javascript folder to the config option you just found/created. The names should be in single quotes and separated by commas. You do *NOT* need to put the file extension just the name.

You should end up with the following directory structure:

* moodle/theme/standard/javascript/jquery-1.4.2.min.js
* moodle/theme/standard/javascript/another.file.js

And the following entry in your themes config.php file:
<code php>
// Remember we don't put the file extension so no .js at the end
$THEME->javascripts_footer = array('jquery-1.4.2.min', 'another.file');
</code>

And with that jQuery is now being loaded within your theme!

However you won't see it immediately, first you need to clear Moodles theme cache. This can be done is two ways when logged in as an Admin:

# Site Administration > Appearance > Themes > Theme selector. At the top of the page will be a button to invalidate the theme cache.
# Site Administration > Appearance > Themes > Theme settings. Turn on Theme Designer Mode.

I would highly recommend turning theme designer mode on if you are going to making lots of changes to your themes CSS or JavaScript otherwise you will need to invalidate your theme caches after every change. Do note however that turning it on will reduce your performance as nothing will be cached.

You should also note that Moodle combines all of the JavaScript for a theme into a single file for the header and a single file for the footer. This file is all of the JavaScript files for the section combined into a single file and minified. If you use a tool such as Firebug to view the JavaScript look for a file with a URL pointing to '''theme/javascript.php?...type=footer'''. All of the JavaScript will be in there.

When adding files to the $THEME->javascripts array the files are added in the order you specify, so the first file gets included first.

===Blocks and modules===
This is much simplier than including jQuery from within a theme.

# Create a '''javascript''' directory within your Module, this is where we will put the jQuery files (and probably any other JavaScript files you need)
# Copy the jQuery files into the javascript folder.
# Add the following lines of php into every file which will make use of jQuery.

<code php>
$PAGE->requires->js('path/to/plugin/javascript/jquery-1.4.2.min.js');
// $PAGE->requires->js('mod/modname/javascript/jquery-1.4.2.min.js');
// $PAGE->requires->js('blocks/blockname/javascript/jquery-1.4.2.min.js');
</code>

And that's it, it is served within the footer of those pages.

If you want to include jQuery within the page header however you will need to specify true as the second argument.
<code php>
$PAGE->requires->js('path/to/plugin/javascript/jquery-1.4.2.min.js', true);
</code>

==Potential problems==
You should be aware that jQuery is only designed to be included within a page once, unfortunately you are the controller of this and will need to ensure.

If you are writing customisations for your own site then it is not a problem, you can either include it within your theme once (and know it will be everywhere), or you can move the files to a central location (e.g. moodle/lib/jquery/*) and then include them from there using the block and module syntax.

If however you are using third party plugins, where more than one is making use of jQuery, you may find VERY strange things happening. You will either need to remove the modules or move the jQuery files to a central location, as above, edit the plugins to find the files there.

Note: A file within one location will only be included once within a page.

For these reasons it is '''HIGHLY''' recommended to use YUI for everything possible.

==More information==
For more information on how to use JavaScript within Moodle 2.0 please see [[Development:JavaScript guidelines]]

* [[Development:JavaScript guidelines]]
* [[Development:Themes 2.0]]

* [[Javascript FAQ]]

setting:regionwidthdouble

2011-03-21T01:44:22Z

Tqr:

Used in theme settings to denote double the width of a particular region, usually #region-pre or #region-post, which translates to left column and right column respectively.

setting:regionwidth

2011-03-21T01:43:39Z

Tqr: New page: Used in theme settings to denote the width of a particular region, usually #region-pre or #region-post, which translates to left column and right column respectively.

Used in theme settings to denote the width of a particular region, usually #region-pre or #region-post, which translates to left column and right column respectively.

setting:regionwidthdouble

2011-03-21T01:40:32Z

Tqr: New page: Used in theme settings to denote double the width of a particular region, usually #region-pre or #region-post, which translate to left column and right column respectively.

Used in theme settings to denote double the width of a particular region, usually #region-pre or #region-post, which translate to left column and right column respectively.

Development:Git for developers

2011-03-14T17:40:21Z

Tqr: /* Working on 2.0 */

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

== Set-up ==

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

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

3. Install Git on your computer. If you are on Mac, [http://code.google.com/p/git-osx-installer/ git-osx-installer] installs it in few click.

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

== Working on 2.0 ==

1. Create a local clone repository of your github repository. In a terminal:
<code bash>
git clone git@github.com:YOUR_GITHUB_USERNAME/moodle.git ./YOUR_LOCAL_MOODLE_FOLDER/
</code>
In Debian Lenny (git version 1.5) you may want to use the following command:
<code bash>
git clone git@github.com:YOUR_GITHUB_USERNAME/moodle.git YOUR_LOCAL_MOODLE_FOLDER
</code>
Before making commits, it is useful to add your name and email:
<code bash>
git config --global user.name "Your Name"
git config --global user.email yourmail@domain.tld
</code>
2. You will need to create an update script in order to update your github and local repository from git.moodle.org. Add a reference to this Moodle.org Git repository and make your local master branch track it:
<code bash>
cd ./YOUR_LOCAL_MOODLE_FOLDER/
git remote add upstream git://git.moodle.org/moodle.git
git fetch upstream
git branch --set-upstream master upstream/master
</code>

3. Create the update script (name it "update_github")

<code bash>
cd YOUR_LOCAL_MOODLE_FOLDER
git checkout master
git pull
git push origin refs/remotes/upstream/master:master
</code>

4. Run the./update_github script. Your local repository ("master" branch) and your github repository ("master" branch) will be updated from git.moodle.org.

5. Now you can work on a new issue. You can use a Git UI tool like SmartGit for these steps:
* Run the update script (the script will switch to "master" branch, so take care to stash/commit the changes of your current branch). To check the current branch:
<code bash>
git branch -a
</code>
* Create a new branch and switch to it. You should never work in your local master branch:
<code bash>
cd YOUR_LOCAL_MOODLE_FOLDER
git branch BRANCH_NAME
git checkout BRANCH_NAME
</code>
* Fix your issue with your favorite IDE. Check updated files:
<code bash>
cd YOUR_LOCAL_MOODLE_FOLDER
git status
</code>
* Commit, push and do a pull request (FILE_NAME can be either a single file or a folder, for a folder the "add" command will be performed recursively)
<code bash>
git add FILE_NAME
git commit
git push origin BRANCH_NAME
</code>

== Working on 1.9 or earlier branches ==
This is just a tiny little bit more complicated that working on 2.0. Even though you could work in the same folder as for 2.0, you should create another folder for working on 1.9. It will make things less messy and easier to understand.

1. In a terminal
<code bash>
git clone git@github.com:YOUR_GITHUB_USERNAME/moodle.git ./YOUR_LOCAL_MOODLE_19_FOLDER/
</code>

2. Add the remote upstream. You want to update your local MOODLE_19_STABLE branch and your github (called "origin") MOODLE_19_STABLE branch from the official Moodle upstream.
<code bash>
cd ./YOUR_LOCAL_MOODLE_19_FOLDER/
git remote add upstream git://git.moodle.org/moodle.git
git fetch upstream
</code>

3. Now you are going to create a local 1.9 branch. You will keep this branch updated (the branch will track upstream) and you are never going to work in it.
<code bash>
git checkout -b MOODLE_19_STABLE upstream/MOODLE_19_STABLE
</code>

4. Create the update script in ./update_github
<code bash>
cd YOUR_LOCAL_MOODLE_19_FOLDER
git checkout MOODLE_19_STABLE
git pull
git push origin refs/remotes/upstream/MOODLE_19_STABLE:MOODLE_19_STABLE
</code>

5. Run the script. Your github MOODLE_19_STABLE branch and your local MOODLE_19_STABLE branch are now updated.

6. You can now work on an issue. You can use a Git UI tool like SmartGit for these steps:
* Run the update script (don't forget to stash/commit the change of your current local branch, you are going to switch to MOODLE_19_STABLE local branch)
* Create a new branch for your issue and switch to it
* Fix your issue with your favorite IDE
* Commit, push and do a pull request

== Peer review some code ==
You need to review someone else work, They must have pushed their work into github:
* github repository url: git://github.com/PEER_USERNAME/moodle.git
* branch name: MDL-XXXXX

1. Run the update script (it will switch to your local master branch and update the code)

2. Add the remote repository (only first time ever, then skip this step)
<code bash>
git remote add PEER_USERNAME git://github.com/PEER_USERNAME/moodle.git
</code>

3. Fetch the repository, so Git knows about the last changes in it
<code bash>
git fetch PEER_USERNAME
</code>

4. Switch to a new local 'testing' branch
<code bash>
git checkout -b PEER_USERNAME-MDL-XXXXX
</code>

5. Import the remote change into this local branch (but not marked as 'committed' so you can see the changes into your IDE)
<code bash>
git merge --squash PEER_USERNAME/MDL-XXXXX
</code>

6. You can now test in your favorite IDE. If it supports Git you should see the difference with your local master.

7. Finally you are going to delete this testing branch:
<code bash>
# Warning: if you didn't switch, you should still be on testing branch.
# the first command revert all the changes to the 'master' state.
git reset --hard
git checkout master
git branch -d PEER_USERNAME-MDL-XXXXX
</code>
== Update a branch before pushing your changes ==
To make diff easy on github for weekly pull request review, you want to update your branch before to push it to github. First commit your changes, then run the update script. You have been switched on master branch, so first thing is to go back to your working branch
<code bash>
git checkout MLD-XXXX
git rebase master
</code>
At this moment either it worked fine and your branch is updated, either you had some conflicts with one of your previous branch commits.
Fix all your conflicts in your editor (like you will fo with CVS) and add the files with 'git add' command.
<code bash>
git add file1 file2 file3 ...
</code>
Now continue the rebasing.
<code bash>
git rebase --continue
</code>
Either it worked and your branch is updated, either one of your other commit created again some other conflicts. Restart the ''Fix, add, continue rebase'' steps until you have no conflict. Your branch is updated.

== Troubleshooting ==
* setup your name for every repository
<code bash>
git config --global user.name "Firstname Lastname"
</code>
* do not push your file permission to any repository
<code bash>
git config --global core.filemode false
</code>
* If you want to delete a remote branch on github:
<code bash>
git push origin :CONFLICTING_REMOTE_BRANCH_NAME
</code>
* PHPStorm (beta version) named your 'origin' => 'master' when you cloned your github repository. It is better to rename it as 'origin'.
<code bash>
git remote rename master origin
</code>
* You've been working with Git in the early stages when Moodle HQ were experimenting with it. They now changed 'cvshead' to 'master' into upstream (moodle.org Git). You need to rename all your 'cvshead' github and local branches as 'master'. There what you should do (this is not a script to run, execute the command one at the time following the instructions):
<code bash>
#go to your root git folder

git fetch origin
git fetch upstream
git remote prune upstream
git remote prune origin

/// FIRST TIME YOU RUN THIS SCRIPT
git checkout -b master upstream/master
git push origin master

#on github, in your repository administration, change the default to 'master'

git push origin :cvshead
git branch -d cvshead
/// END OF FIRST TIME

git remote set-head origin -a
git remote set-head upstream -a

/// OTHER TIME - FOR YOUR OTHER GIT MOODLE FOLDERS
git checkout -b master upstream/master
git branch -d cvshead
/// END OF OTHER TIME

#check .git/config that there is no references to 'cvshead', if there are replace with 'master'

#optional:
#update your update script ('cvshead' => 'master')
</code>
* To know about your branches (the current branch is marked with an asterix)
<code bash>
git branch -a
</code>
*For any help
<code bash>
git any_command --help
</code>

==See also==

* [[Development:Tutorial_on_using_git_in_Moodle_development]]

[[Category:Git]]

Development:Themes 2.0

2010-12-07T21:11:20Z

Tqr: /* Locations of CSS files */

{{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 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 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 [[Development: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 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==

* [http://www.youtube.com/watch?v=OvaU54uh-qA New themes in Moodle 2.0 video]
* [[Development:Themes 2.0 creating your first theme]] - A quick step by step guide to creating your first theme.
* [[Development:Themes 2.0 overriding a renderer]] - A tutorial on creating a custom renderer and changing the HTML Moodle produces.
* [[Development:Themes 2.0 How to use images within your theme]] - Explains how to use and override images within your theme.
* [[Development:Themes 2.0 adding a settings page]] - Looks at how to add a setting page making your theme easily customisable.
* [[Development:Themes 2.0 extending the custom menu]] - Customising the custom menu.
* [[Development:Styling and customising the dock]] - How to style and customise the dock.
* [[Development:Theme changes in 2.0]]
* [[Development:Using jQuery with Moodle 2.0]]

[[de:Designs 2.0]]

Themes FAQ

2010-11-05T10:31:53Z

Tqr: /* Why is the new theme I uploaded not showing up in Theme Selector? */

{{Themes}}
==How do I install a new theme?==

# Unzip the .zip file to an empty local directory.
# Upload folder to your web server to the /moodle/theme/[Theme Name]. (Replace [Theme Name] with the name of the theme you have downloaded.) Ensure the new theme folder and its contents are readable by the webserver. Change Read and Write permissions (CHMOD) for the files and folder to 755 - Owner read/write/execute, Group read/execute, Everyone read/execute. Incorrect permissions may prevent display of the newly installed theme.
# Choose your new theme from within Moodle via ''Administration > Appearance > Themes > Theme selector'' (or ''Administration > Configuration > Themes'' in versions of Moodle prior to 1.7).

=== How do I install a new theme when using cPanel? ===

# Upload your new theme .zip file to your web server via cPanel.
# Then using cPanel install the new theme to your Moodle theme's folder. The new theme will be installed into its own folder at /moodle/theme/[mytheme] (where [mytheme] is the name of your new theme.
# Ensure the new theme folder and its contents are readable by the webserver. If necessary change Read and Write permissions (CHMOD) for the files and folder to 755 - Owner read/write/execute, Group read/execute, Everyone read/execute. Incorrect permissions may prevent display of the newly installed theme.
# Choose your new theme from within Moodle via ''Administration > Appearance > Themes > Theme selector'' (or ''Administration > Configuration > Themes'' in versions of Moodle prior to 1.7).

=== Why is the new theme I uploaded not showing up in Theme Selector? ===

# There could be a number of problems with the theme you uploaded, but one major problem reported in the Themes Forum all point to the way in which the theme is uploaded on certain servers. Using the cPanel method, as described in the previous section 1.1 [[How do I install a new theme when using cPanel?]] (see above) will, in most cases, cure the problem.

==How do I create a custom theme?==

See [[Creating a custom theme]] and/or [[Make your own theme]].

==Can I assign a specific theme to a course?==

Yes. In the course settings, use the "Force theme" dropdown box.

== Where shall I put my custom CSS code? ==

Instead of modifying the theme's CSS files you better put your own code in a separate CSS file and make your theme aware of that file by modifying its config.php file (be sure add your own CSS file as the last one in the list so that you will override all prior settings). See this posting for [http://moodle.org/mod/forum/discuss.php?d=128599#p564055 detailed instructions].

See also the instructions on creating your own theme mentioned above.

==How can I get the New Moodle2 theme for my site?==
Not til Moodle 2.x comes out and it will be a "sort of". The new look (refered to as "Moodle2") for Moodle.org was made public just before the close of 2008. The Moodle2 look has various things hard coded into its fabric. The good news is that many pieces of the look are available.

==Will I lose my courses, language files, logo, etc. if I switch my theme?==
Switching themes only changes the appearance of your site, not the content within it. The logo is a part of the theme and will be lost when you switch.

Follow these instructions to [[Creating_a_custom_theme#Adding_a_Logo|add a logo]] to a theme.

== Are there tools which help me creating and editing themes? ==

=== Clear Cache Button ===
This useful Firefox add-on let's you add a button to your tool bar for easily clearing your cache while working on your theme: https://addons.mozilla.org/de/firefox/addon/1801

<p class="note">Please note that the following tools are only for development. They only change the way ''you'' see your Moodle site, not the Moodle site itself. Any changes you make using these tools will not be visible to anyone else who uses your site. For this you will have to make those changes permanent by changing your theme's CSS files for example.</p>

=== Firebug ===
The single most useful tool is the [[Development:Firebug|Firebug]] add-on for the [[Firefox]] web browser. Firebug integrates with Firefox to put a wealth of development tools at your fingertips while you browse. You can edit, debug, and monitor CSS, HTML, and JavaScript live in any web page... And there are additional add-ons for making Firebug an even more powerful tool.

==== Firebug enhancements ====
You can enhance Firebug even further. See [[Firebug]] for more information.

=== Web Developer Toolbar ===
Another great tool for any web developer is the [[Web developer extension]], another Firefox add-on. One very useful feature is the option to '''disable your browser's cache''' while working on your theme. That way you are sure you're always presented with your latest modifications and not with an older, cached version.

Now also available for Google's Chrome browser: [http://www.sitepoint.com/blogs/2010/03/23/chrome-web-developer-toolbar/ "The Web Developer Toolbar Comes to Chrome"]

=== Stylish ===
Modifications made with Firebug are lost when refreshing your page. If you want your CSS changes to be a bit more permanent, for example to try them with different pages of your Moodle installation, you can use another Firefox plugin: [https://addons.mozilla.org/en-US/firefox/addon/2108 Stylish]. That way you can change your site's CSS with a simple mouse click without having to change Moodle code.

See [[Stylish]] for detailed instructions and examples.

== How do I check for cross-browser compatibility? ==
There are some tools (standalone and online) which can show you how your site looks in different browsers. See this [http://moodle.org/mod/forum/discuss.php?d=127746 forum discussion] for details.

== Concrete examples for modifying Moodle themes ==
<p class="note">
The following examples were taken from the former ''Theme Scrapbook'':
<br />
"The Moodle '''Theme Scrapbook''' is a collection of small how-to descriptions. You theme designers and Moodle users working with themes add your knowledge here to help new Moodle users with tips and tricks for their theme work.
<br />
Feel free to add to this list! Don't know how? Read our [[MoodleDocs:Guidelines_for_contributors|Guidelines for contributors]]."
</p>

=== Changing things ===

==== Colors ====
* [[Forcing the colour of the chat discussion pane (pop-up mode)]]
* [http://moodle.org/mod/forum/discuss.php?d=142765 Changing background colour of a topic box]
* [http://moodle.org/mod/forum/discuss.php?d=152357 How to change the colour of the popup event's header and background]

==== Logo and icons ====
* [[Alternate Icon Set|Using an alternate icon set in Moodle]]
* [[Favicon|Change the favicon that shows in front of the web address]]
* [[Footer replacement|Replace the logo in the footer with your web address and/or or own logo]]
*[[Header logo|Replace the logo in the header]]

==== Layout ====
* [http://moodle.org/mod/forum/discuss.php?d=136546 Overriding the $menu / $button variables] using PHP regular expressions in header.html
* [http://moodle.org/mod/forum/discuss.php?d=143411 Changing the view of course categories] - work in progress
* [http://moodle.org/mod/forum/discuss.php?d=145077 Sub categories and courses layout] - work in progress
* [http://moodle.org/mod/forum/discuss.php?d=151370 Tracker 'components' list too small]

=== Adding things ===
* [[Header logo|Adding a logo to the theme header]]
* [http://moodle.org/mod/forum/discuss.php?d=157935 How to add a different img-bullet to each category?]

=== Hiding things ===
* Hiding an element with CSS is generally achieved using the [http://reference.sitepoint.com/css/display display: none;] property on the element.
* See [[Print style]] and [[Stylish#Print style for Database records]] for an example how to hide parts of a page not meant for printing.

=== Moving things ===
* [[Center Forum Posts|Centre smaller forum posts on the page]]
* [[Footer positioning|Positioning the page footer]]
* [[Left-align quiz|Left align quiz questions and answers]]
* [http://moodle.org/mod/forum/discuss.php?d=121847 Indentation for nested categories]
* [http://moodle.org/mod/forum/discuss.php?d=128599 Positioning login and choose language field]
* [http://moodle.org/mod/forum/discuss.php?d=145179 Match question type - position answers nearer to the questions]

=== Miscellaneous ===
* [[Fixed-width theme|Creating a fixed-width theme]]
* [[Homepage design|Homepage design of moodle.org]]
* [http://moodle.org/mod/forum/discuss.php?d=146763 Is there a way to fix oversized HTML Editor using CSS?]

==How can I see theme changes when using the Windows Complete Installer package==
In the [http://download.moodle.org/windows/ Windows Complete Installer package], the eAccelerator in the XAMPP install can cause some issues with changes to your theme's CSS and HTML files from showing.

Open the php.ini file inside of the server\php folder from your install in notepad and search for "eAccelerator" you should see a line that reads:
extension=eaccelerator.dll

Insert a semi-colon (turns the line into a comment) at the start of this line so it now reads:
;extension=eaccelerator.dll

Restart the Moodle server using the "stop moodle" and then the "start moodle" programs in your server folder. You should now find that all of your changes to your CSS are reflected as soon as you save the file and refresh your browser cache (usually you can refresh your cache by pressing F5). This FAQ from a discussion at [http://moodle.org/mod/forum/discuss.php?d=151562#p663950 Deactivating caching with XAMPP installations]

== See also ==

* Using Moodle [http://moodle.org/mod/forum/view.php?f=29 Themes forum]
* [[CSS FAQ]]
* [http://learn.open.ac.uk/mod/oublog/view.php?user=155976 "Understanding Moodle Themes"] - Blog post by [http://moodle.org/user/view.php?id=78896&course=5 Christopher Douce] (Open University)
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=149534 Testing 2.0. Use for modern vs old browsers] forum discussion

[[Category:FAQ]]
[[de:Designs_FAQ]]

Themes FAQ

2010-11-05T10:31:26Z

Tqr: /* Why is the new theme I uploaded not showing up in Theme Selector? */

{{Themes}}
==How do I install a new theme?==

# Unzip the .zip file to an empty local directory.
# Upload folder to your web server to the /moodle/theme/[Theme Name]. (Replace [Theme Name] with the name of the theme you have downloaded.) Ensure the new theme folder and its contents are readable by the webserver. Change Read and Write permissions (CHMOD) for the files and folder to 755 - Owner read/write/execute, Group read/execute, Everyone read/execute. Incorrect permissions may prevent display of the newly installed theme.
# Choose your new theme from within Moodle via ''Administration > Appearance > Themes > Theme selector'' (or ''Administration > Configuration > Themes'' in versions of Moodle prior to 1.7).

=== How do I install a new theme when using cPanel? ===

# Upload your new theme .zip file to your web server via cPanel.
# Then using cPanel install the new theme to your Moodle theme's folder. The new theme will be installed into its own folder at /moodle/theme/[mytheme] (where [mytheme] is the name of your new theme.
# Ensure the new theme folder and its contents are readable by the webserver. If necessary change Read and Write permissions (CHMOD) for the files and folder to 755 - Owner read/write/execute, Group read/execute, Everyone read/execute. Incorrect permissions may prevent display of the newly installed theme.
# Choose your new theme from within Moodle via ''Administration > Appearance > Themes > Theme selector'' (or ''Administration > Configuration > Themes'' in versions of Moodle prior to 1.7).

=== Why is the new theme I uploaded not showing up in Theme Selector? ===

# There could be a number of problems with the theme you uploaded, but one major problem reported in the Themes Forum all point to the way in which the theme is uploaded on certain servers. Using the cPanel method, as described in the previous section 1.1 [[How do I install a new theme when using cPanel?]](see above) will, in most cases, cure the problem.

==How do I create a custom theme?==

See [[Creating a custom theme]] and/or [[Make your own theme]].

==Can I assign a specific theme to a course?==

Yes. In the course settings, use the "Force theme" dropdown box.

== Where shall I put my custom CSS code? ==

Instead of modifying the theme's CSS files you better put your own code in a separate CSS file and make your theme aware of that file by modifying its config.php file (be sure add your own CSS file as the last one in the list so that you will override all prior settings). See this posting for [http://moodle.org/mod/forum/discuss.php?d=128599#p564055 detailed instructions].

See also the instructions on creating your own theme mentioned above.

==How can I get the New Moodle2 theme for my site?==
Not til Moodle 2.x comes out and it will be a "sort of". The new look (refered to as "Moodle2") for Moodle.org was made public just before the close of 2008. The Moodle2 look has various things hard coded into its fabric. The good news is that many pieces of the look are available.

==Will I lose my courses, language files, logo, etc. if I switch my theme?==
Switching themes only changes the appearance of your site, not the content within it. The logo is a part of the theme and will be lost when you switch.

Follow these instructions to [[Creating_a_custom_theme#Adding_a_Logo|add a logo]] to a theme.

== Are there tools which help me creating and editing themes? ==

=== Clear Cache Button ===
This useful Firefox add-on let's you add a button to your tool bar for easily clearing your cache while working on your theme: https://addons.mozilla.org/de/firefox/addon/1801

<p class="note">Please note that the following tools are only for development. They only change the way ''you'' see your Moodle site, not the Moodle site itself. Any changes you make using these tools will not be visible to anyone else who uses your site. For this you will have to make those changes permanent by changing your theme's CSS files for example.</p>

=== Firebug ===
The single most useful tool is the [[Development:Firebug|Firebug]] add-on for the [[Firefox]] web browser. Firebug integrates with Firefox to put a wealth of development tools at your fingertips while you browse. You can edit, debug, and monitor CSS, HTML, and JavaScript live in any web page... And there are additional add-ons for making Firebug an even more powerful tool.

==== Firebug enhancements ====
You can enhance Firebug even further. See [[Firebug]] for more information.

=== Web Developer Toolbar ===
Another great tool for any web developer is the [[Web developer extension]], another Firefox add-on. One very useful feature is the option to '''disable your browser's cache''' while working on your theme. That way you are sure you're always presented with your latest modifications and not with an older, cached version.

Now also available for Google's Chrome browser: [http://www.sitepoint.com/blogs/2010/03/23/chrome-web-developer-toolbar/ "The Web Developer Toolbar Comes to Chrome"]

=== Stylish ===
Modifications made with Firebug are lost when refreshing your page. If you want your CSS changes to be a bit more permanent, for example to try them with different pages of your Moodle installation, you can use another Firefox plugin: [https://addons.mozilla.org/en-US/firefox/addon/2108 Stylish]. That way you can change your site's CSS with a simple mouse click without having to change Moodle code.

See [[Stylish]] for detailed instructions and examples.

== How do I check for cross-browser compatibility? ==
There are some tools (standalone and online) which can show you how your site looks in different browsers. See this [http://moodle.org/mod/forum/discuss.php?d=127746 forum discussion] for details.

== Concrete examples for modifying Moodle themes ==
<p class="note">
The following examples were taken from the former ''Theme Scrapbook'':
<br />
"The Moodle '''Theme Scrapbook''' is a collection of small how-to descriptions. You theme designers and Moodle users working with themes add your knowledge here to help new Moodle users with tips and tricks for their theme work.
<br />
Feel free to add to this list! Don't know how? Read our [[MoodleDocs:Guidelines_for_contributors|Guidelines for contributors]]."
</p>

=== Changing things ===

==== Colors ====
* [[Forcing the colour of the chat discussion pane (pop-up mode)]]
* [http://moodle.org/mod/forum/discuss.php?d=142765 Changing background colour of a topic box]
* [http://moodle.org/mod/forum/discuss.php?d=152357 How to change the colour of the popup event's header and background]

==== Logo and icons ====
* [[Alternate Icon Set|Using an alternate icon set in Moodle]]
* [[Favicon|Change the favicon that shows in front of the web address]]
* [[Footer replacement|Replace the logo in the footer with your web address and/or or own logo]]
*[[Header logo|Replace the logo in the header]]

==== Layout ====
* [http://moodle.org/mod/forum/discuss.php?d=136546 Overriding the $menu / $button variables] using PHP regular expressions in header.html
* [http://moodle.org/mod/forum/discuss.php?d=143411 Changing the view of course categories] - work in progress
* [http://moodle.org/mod/forum/discuss.php?d=145077 Sub categories and courses layout] - work in progress
* [http://moodle.org/mod/forum/discuss.php?d=151370 Tracker 'components' list too small]

=== Adding things ===
* [[Header logo|Adding a logo to the theme header]]
* [http://moodle.org/mod/forum/discuss.php?d=157935 How to add a different img-bullet to each category?]

=== Hiding things ===
* Hiding an element with CSS is generally achieved using the [http://reference.sitepoint.com/css/display display: none;] property on the element.
* See [[Print style]] and [[Stylish#Print style for Database records]] for an example how to hide parts of a page not meant for printing.

=== Moving things ===
* [[Center Forum Posts|Centre smaller forum posts on the page]]
* [[Footer positioning|Positioning the page footer]]
* [[Left-align quiz|Left align quiz questions and answers]]
* [http://moodle.org/mod/forum/discuss.php?d=121847 Indentation for nested categories]
* [http://moodle.org/mod/forum/discuss.php?d=128599 Positioning login and choose language field]
* [http://moodle.org/mod/forum/discuss.php?d=145179 Match question type - position answers nearer to the questions]

=== Miscellaneous ===
* [[Fixed-width theme|Creating a fixed-width theme]]
* [[Homepage design|Homepage design of moodle.org]]
* [http://moodle.org/mod/forum/discuss.php?d=146763 Is there a way to fix oversized HTML Editor using CSS?]

==How can I see theme changes when using the Windows Complete Installer package==
In the [http://download.moodle.org/windows/ Windows Complete Installer package], the eAccelerator in the XAMPP install can cause some issues with changes to your theme's CSS and HTML files from showing.

Open the php.ini file inside of the server\php folder from your install in notepad and search for "eAccelerator" you should see a line that reads:
extension=eaccelerator.dll

Insert a semi-colon (turns the line into a comment) at the start of this line so it now reads:
;extension=eaccelerator.dll

Restart the Moodle server using the "stop moodle" and then the "start moodle" programs in your server folder. You should now find that all of your changes to your CSS are reflected as soon as you save the file and refresh your browser cache (usually you can refresh your cache by pressing F5). This FAQ from a discussion at [http://moodle.org/mod/forum/discuss.php?d=151562#p663950 Deactivating caching with XAMPP installations]

== See also ==

* Using Moodle [http://moodle.org/mod/forum/view.php?f=29 Themes forum]
* [[CSS FAQ]]
* [http://learn.open.ac.uk/mod/oublog/view.php?user=155976 "Understanding Moodle Themes"] - Blog post by [http://moodle.org/user/view.php?id=78896&course=5 Christopher Douce] (Open University)
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=149534 Testing 2.0. Use for modern vs old browsers] forum discussion

[[Category:FAQ]]
[[de:Designs_FAQ]]

Themes FAQ

2010-11-05T10:27:39Z

Tqr: /* How do I install a new theme when using cPanel? */

{{Themes}}
==How do I install a new theme?==

# Unzip the .zip file to an empty local directory.
# Upload folder to your web server to the /moodle/theme/[Theme Name]. (Replace [Theme Name] with the name of the theme you have downloaded.) Ensure the new theme folder and its contents are readable by the webserver. Change Read and Write permissions (CHMOD) for the files and folder to 755 - Owner read/write/execute, Group read/execute, Everyone read/execute. Incorrect permissions may prevent display of the newly installed theme.
# Choose your new theme from within Moodle via ''Administration > Appearance > Themes > Theme selector'' (or ''Administration > Configuration > Themes'' in versions of Moodle prior to 1.7).

=== How do I install a new theme when using cPanel? ===

# Upload your new theme .zip file to your web server via cPanel.
# Then using cPanel install the new theme to your Moodle theme's folder. The new theme will be installed into its own folder at /moodle/theme/[mytheme] (where [mytheme] is the name of your new theme.
# Ensure the new theme folder and its contents are readable by the webserver. If necessary change Read and Write permissions (CHMOD) for the files and folder to 755 - Owner read/write/execute, Group read/execute, Everyone read/execute. Incorrect permissions may prevent display of the newly installed theme.
# Choose your new theme from within Moodle via ''Administration > Appearance > Themes > Theme selector'' (or ''Administration > Configuration > Themes'' in versions of Moodle prior to 1.7).

=== Why is the new theme I uploaded not showing up in Theme Selector? ===

# There could be a number of problems with the theme you uploaded, but one major problem reported in the Themes Forum all point to the way in which the theme is uploaded on certain servers. Using the cPanel method, as described in the previous section 1.1 (above) will, in most cases, cure the problem.

==How do I create a custom theme?==

See [[Creating a custom theme]] and/or [[Make your own theme]].

==Can I assign a specific theme to a course?==

Yes. In the course settings, use the "Force theme" dropdown box.

== Where shall I put my custom CSS code? ==

Instead of modifying the theme's CSS files you better put your own code in a separate CSS file and make your theme aware of that file by modifying its config.php file (be sure add your own CSS file as the last one in the list so that you will override all prior settings). See this posting for [http://moodle.org/mod/forum/discuss.php?d=128599#p564055 detailed instructions].

See also the instructions on creating your own theme mentioned above.

==How can I get the New Moodle2 theme for my site?==
Not til Moodle 2.x comes out and it will be a "sort of". The new look (refered to as "Moodle2") for Moodle.org was made public just before the close of 2008. The Moodle2 look has various things hard coded into its fabric. The good news is that many pieces of the look are available.

==Will I lose my courses, language files, logo, etc. if I switch my theme?==
Switching themes only changes the appearance of your site, not the content within it. The logo is a part of the theme and will be lost when you switch.

Follow these instructions to [[Creating_a_custom_theme#Adding_a_Logo|add a logo]] to a theme.

== Are there tools which help me creating and editing themes? ==

=== Clear Cache Button ===
This useful Firefox add-on let's you add a button to your tool bar for easily clearing your cache while working on your theme: https://addons.mozilla.org/de/firefox/addon/1801

<p class="note">Please note that the following tools are only for development. They only change the way ''you'' see your Moodle site, not the Moodle site itself. Any changes you make using these tools will not be visible to anyone else who uses your site. For this you will have to make those changes permanent by changing your theme's CSS files for example.</p>

=== Firebug ===
The single most useful tool is the [[Development:Firebug|Firebug]] add-on for the [[Firefox]] web browser. Firebug integrates with Firefox to put a wealth of development tools at your fingertips while you browse. You can edit, debug, and monitor CSS, HTML, and JavaScript live in any web page... And there are additional add-ons for making Firebug an even more powerful tool.

==== Firebug enhancements ====
You can enhance Firebug even further. See [[Firebug]] for more information.

=== Web Developer Toolbar ===
Another great tool for any web developer is the [[Web developer extension]], another Firefox add-on. One very useful feature is the option to '''disable your browser's cache''' while working on your theme. That way you are sure you're always presented with your latest modifications and not with an older, cached version.

Now also available for Google's Chrome browser: [http://www.sitepoint.com/blogs/2010/03/23/chrome-web-developer-toolbar/ "The Web Developer Toolbar Comes to Chrome"]

=== Stylish ===
Modifications made with Firebug are lost when refreshing your page. If you want your CSS changes to be a bit more permanent, for example to try them with different pages of your Moodle installation, you can use another Firefox plugin: [https://addons.mozilla.org/en-US/firefox/addon/2108 Stylish]. That way you can change your site's CSS with a simple mouse click without having to change Moodle code.

See [[Stylish]] for detailed instructions and examples.

== How do I check for cross-browser compatibility? ==
There are some tools (standalone and online) which can show you how your site looks in different browsers. See this [http://moodle.org/mod/forum/discuss.php?d=127746 forum discussion] for details.

== Concrete examples for modifying Moodle themes ==
<p class="note">
The following examples were taken from the former ''Theme Scrapbook'':
<br />
"The Moodle '''Theme Scrapbook''' is a collection of small how-to descriptions. You theme designers and Moodle users working with themes add your knowledge here to help new Moodle users with tips and tricks for their theme work.
<br />
Feel free to add to this list! Don't know how? Read our [[MoodleDocs:Guidelines_for_contributors|Guidelines for contributors]]."
</p>

=== Changing things ===

==== Colors ====
* [[Forcing the colour of the chat discussion pane (pop-up mode)]]
* [http://moodle.org/mod/forum/discuss.php?d=142765 Changing background colour of a topic box]
* [http://moodle.org/mod/forum/discuss.php?d=152357 How to change the colour of the popup event's header and background]

==== Logo and icons ====
* [[Alternate Icon Set|Using an alternate icon set in Moodle]]
* [[Favicon|Change the favicon that shows in front of the web address]]
* [[Footer replacement|Replace the logo in the footer with your web address and/or or own logo]]
*[[Header logo|Replace the logo in the header]]

==== Layout ====
* [http://moodle.org/mod/forum/discuss.php?d=136546 Overriding the $menu / $button variables] using PHP regular expressions in header.html
* [http://moodle.org/mod/forum/discuss.php?d=143411 Changing the view of course categories] - work in progress
* [http://moodle.org/mod/forum/discuss.php?d=145077 Sub categories and courses layout] - work in progress
* [http://moodle.org/mod/forum/discuss.php?d=151370 Tracker 'components' list too small]

=== Adding things ===
* [[Header logo|Adding a logo to the theme header]]
* [http://moodle.org/mod/forum/discuss.php?d=157935 How to add a different img-bullet to each category?]

=== Hiding things ===
* Hiding an element with CSS is generally achieved using the [http://reference.sitepoint.com/css/display display: none;] property on the element.
* See [[Print style]] and [[Stylish#Print style for Database records]] for an example how to hide parts of a page not meant for printing.

=== Moving things ===
* [[Center Forum Posts|Centre smaller forum posts on the page]]
* [[Footer positioning|Positioning the page footer]]
* [[Left-align quiz|Left align quiz questions and answers]]
* [http://moodle.org/mod/forum/discuss.php?d=121847 Indentation for nested categories]
* [http://moodle.org/mod/forum/discuss.php?d=128599 Positioning login and choose language field]
* [http://moodle.org/mod/forum/discuss.php?d=145179 Match question type - position answers nearer to the questions]

=== Miscellaneous ===
* [[Fixed-width theme|Creating a fixed-width theme]]
* [[Homepage design|Homepage design of moodle.org]]
* [http://moodle.org/mod/forum/discuss.php?d=146763 Is there a way to fix oversized HTML Editor using CSS?]

==How can I see theme changes when using the Windows Complete Installer package==
In the [http://download.moodle.org/windows/ Windows Complete Installer package], the eAccelerator in the XAMPP install can cause some issues with changes to your theme's CSS and HTML files from showing.

Open the php.ini file inside of the server\php folder from your install in notepad and search for "eAccelerator" you should see a line that reads:
extension=eaccelerator.dll

Insert a semi-colon (turns the line into a comment) at the start of this line so it now reads:
;extension=eaccelerator.dll

Restart the Moodle server using the "stop moodle" and then the "start moodle" programs in your server folder. You should now find that all of your changes to your CSS are reflected as soon as you save the file and refresh your browser cache (usually you can refresh your cache by pressing F5). This FAQ from a discussion at [http://moodle.org/mod/forum/discuss.php?d=151562#p663950 Deactivating caching with XAMPP installations]

== See also ==

* Using Moodle [http://moodle.org/mod/forum/view.php?f=29 Themes forum]
* [[CSS FAQ]]
* [http://learn.open.ac.uk/mod/oublog/view.php?user=155976 "Understanding Moodle Themes"] - Blog post by [http://moodle.org/user/view.php?id=78896&course=5 Christopher Douce] (Open University)
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=149534 Testing 2.0. Use for modern vs old browsers] forum discussion

[[Category:FAQ]]
[[de:Designs_FAQ]]

Themes FAQ

2010-11-05T10:26:00Z

Tqr: /* How do I install a new theme? */

{{Themes}}
==How do I install a new theme?==

# Unzip the .zip file to an empty local directory.
# Upload folder to your web server to the /moodle/theme/[Theme Name]. (Replace [Theme Name] with the name of the theme you have downloaded.) Ensure the new theme folder and its contents are readable by the webserver. Change Read and Write permissions (CHMOD) for the files and folder to 755 - Owner read/write/execute, Group read/execute, Everyone read/execute. Incorrect permissions may prevent display of the newly installed theme.
# Choose your new theme from within Moodle via ''Administration > Appearance > Themes > Theme selector'' (or ''Administration > Configuration > Themes'' in versions of Moodle prior to 1.7).

=== How do I install a new theme when using cPanel? ===

# Upload your new theme .zip file to your web server via cPanel.
# Then using cPanel install the new theme to your Moodle theme's folder. The new theme will be installed into its own folder at /moodle/theme/[mytheme] (where [mytheme] is the name of your new theme.
# Ensure the new theme folder and its contents are readable by the webserver. If necessary change Read and Write permissions (CHMOD) for the files and folder to 755 - Owner read/write/execute, Group read/execute, Everyone read/execute. Incorrect permissions may prevent display of the newly installed theme.
# Choose your new theme from within Moodle via ''Administration > Appearance > Themes > Theme selector'' (or ''Administration > Configuration > Themes'' in versions of Moodle prior to 1.7).

=== Why is the new theme I uploaded not showing up in Theme Selector?

# There could be a number of problems with the theme you uploaded, but one major problem reported in the Themes Forum all point to the way in which the theme is uploaded on certain servers. Using the cPanel method, as described in the previous section 1.1 (above) will, in most cases, cure the problem.

==How do I create a custom theme?==

See [[Creating a custom theme]] and/or [[Make your own theme]].

==Can I assign a specific theme to a course?==

Yes. In the course settings, use the "Force theme" dropdown box.

== Where shall I put my custom CSS code? ==

Instead of modifying the theme's CSS files you better put your own code in a separate CSS file and make your theme aware of that file by modifying its config.php file (be sure add your own CSS file as the last one in the list so that you will override all prior settings). See this posting for [http://moodle.org/mod/forum/discuss.php?d=128599#p564055 detailed instructions].

See also the instructions on creating your own theme mentioned above.

==How can I get the New Moodle2 theme for my site?==
Not til Moodle 2.x comes out and it will be a "sort of". The new look (refered to as "Moodle2") for Moodle.org was made public just before the close of 2008. The Moodle2 look has various things hard coded into its fabric. The good news is that many pieces of the look are available.

==Will I lose my courses, language files, logo, etc. if I switch my theme?==
Switching themes only changes the appearance of your site, not the content within it. The logo is a part of the theme and will be lost when you switch.

Follow these instructions to [[Creating_a_custom_theme#Adding_a_Logo|add a logo]] to a theme.

== Are there tools which help me creating and editing themes? ==

=== Clear Cache Button ===
This useful Firefox add-on let's you add a button to your tool bar for easily clearing your cache while working on your theme: https://addons.mozilla.org/de/firefox/addon/1801

<p class="note">Please note that the following tools are only for development. They only change the way ''you'' see your Moodle site, not the Moodle site itself. Any changes you make using these tools will not be visible to anyone else who uses your site. For this you will have to make those changes permanent by changing your theme's CSS files for example.</p>

=== Firebug ===
The single most useful tool is the [[Development:Firebug|Firebug]] add-on for the [[Firefox]] web browser. Firebug integrates with Firefox to put a wealth of development tools at your fingertips while you browse. You can edit, debug, and monitor CSS, HTML, and JavaScript live in any web page... And there are additional add-ons for making Firebug an even more powerful tool.

==== Firebug enhancements ====
You can enhance Firebug even further. See [[Firebug]] for more information.

=== Web Developer Toolbar ===
Another great tool for any web developer is the [[Web developer extension]], another Firefox add-on. One very useful feature is the option to '''disable your browser's cache''' while working on your theme. That way you are sure you're always presented with your latest modifications and not with an older, cached version.

Now also available for Google's Chrome browser: [http://www.sitepoint.com/blogs/2010/03/23/chrome-web-developer-toolbar/ "The Web Developer Toolbar Comes to Chrome"]

=== Stylish ===
Modifications made with Firebug are lost when refreshing your page. If you want your CSS changes to be a bit more permanent, for example to try them with different pages of your Moodle installation, you can use another Firefox plugin: [https://addons.mozilla.org/en-US/firefox/addon/2108 Stylish]. That way you can change your site's CSS with a simple mouse click without having to change Moodle code.

See [[Stylish]] for detailed instructions and examples.

== How do I check for cross-browser compatibility? ==
There are some tools (standalone and online) which can show you how your site looks in different browsers. See this [http://moodle.org/mod/forum/discuss.php?d=127746 forum discussion] for details.

== Concrete examples for modifying Moodle themes ==
<p class="note">
The following examples were taken from the former ''Theme Scrapbook'':
<br />
"The Moodle '''Theme Scrapbook''' is a collection of small how-to descriptions. You theme designers and Moodle users working with themes add your knowledge here to help new Moodle users with tips and tricks for their theme work.
<br />
Feel free to add to this list! Don't know how? Read our [[MoodleDocs:Guidelines_for_contributors|Guidelines for contributors]]."
</p>

=== Changing things ===

==== Colors ====
* [[Forcing the colour of the chat discussion pane (pop-up mode)]]
* [http://moodle.org/mod/forum/discuss.php?d=142765 Changing background colour of a topic box]
* [http://moodle.org/mod/forum/discuss.php?d=152357 How to change the colour of the popup event's header and background]

==== Logo and icons ====
* [[Alternate Icon Set|Using an alternate icon set in Moodle]]
* [[Favicon|Change the favicon that shows in front of the web address]]
* [[Footer replacement|Replace the logo in the footer with your web address and/or or own logo]]
*[[Header logo|Replace the logo in the header]]

==== Layout ====
* [http://moodle.org/mod/forum/discuss.php?d=136546 Overriding the $menu / $button variables] using PHP regular expressions in header.html
* [http://moodle.org/mod/forum/discuss.php?d=143411 Changing the view of course categories] - work in progress
* [http://moodle.org/mod/forum/discuss.php?d=145077 Sub categories and courses layout] - work in progress
* [http://moodle.org/mod/forum/discuss.php?d=151370 Tracker 'components' list too small]

=== Adding things ===
* [[Header logo|Adding a logo to the theme header]]
* [http://moodle.org/mod/forum/discuss.php?d=157935 How to add a different img-bullet to each category?]

=== Hiding things ===
* Hiding an element with CSS is generally achieved using the [http://reference.sitepoint.com/css/display display: none;] property on the element.
* See [[Print style]] and [[Stylish#Print style for Database records]] for an example how to hide parts of a page not meant for printing.

=== Moving things ===
* [[Center Forum Posts|Centre smaller forum posts on the page]]
* [[Footer positioning|Positioning the page footer]]
* [[Left-align quiz|Left align quiz questions and answers]]
* [http://moodle.org/mod/forum/discuss.php?d=121847 Indentation for nested categories]
* [http://moodle.org/mod/forum/discuss.php?d=128599 Positioning login and choose language field]
* [http://moodle.org/mod/forum/discuss.php?d=145179 Match question type - position answers nearer to the questions]

=== Miscellaneous ===
* [[Fixed-width theme|Creating a fixed-width theme]]
* [[Homepage design|Homepage design of moodle.org]]
* [http://moodle.org/mod/forum/discuss.php?d=146763 Is there a way to fix oversized HTML Editor using CSS?]

==How can I see theme changes when using the Windows Complete Installer package==
In the [http://download.moodle.org/windows/ Windows Complete Installer package], the eAccelerator in the XAMPP install can cause some issues with changes to your theme's CSS and HTML files from showing.

Open the php.ini file inside of the server\php folder from your install in notepad and search for "eAccelerator" you should see a line that reads:
extension=eaccelerator.dll

Insert a semi-colon (turns the line into a comment) at the start of this line so it now reads:
;extension=eaccelerator.dll

Restart the Moodle server using the "stop moodle" and then the "start moodle" programs in your server folder. You should now find that all of your changes to your CSS are reflected as soon as you save the file and refresh your browser cache (usually you can refresh your cache by pressing F5). This FAQ from a discussion at [http://moodle.org/mod/forum/discuss.php?d=151562#p663950 Deactivating caching with XAMPP installations]

== See also ==

* Using Moodle [http://moodle.org/mod/forum/view.php?f=29 Themes forum]
* [[CSS FAQ]]
* [http://learn.open.ac.uk/mod/oublog/view.php?user=155976 "Understanding Moodle Themes"] - Blog post by [http://moodle.org/user/view.php?id=78896&course=5 Christopher Douce] (Open University)
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=149534 Testing 2.0. Use for modern vs old browsers] forum discussion

[[Category:FAQ]]
[[de:Designs_FAQ]]

error/moodle/secretalreadyused

2010-09-07T19:48:35Z

Tqr:

I suppose you have arrive at this page from some area of Moodle where you dared to click the HELP button in the vain hope you would arrive at a page which would explain the cryptic message [[Change password confirmation link was already used, password was not changed.]]

Well you have...DON'T CLICK THE LINK!

error/moodle/secretalreadyused

2010-09-07T19:46:29Z

Tqr: New page: I suppose you have arrive at this page from some area of Moodle where you dared to click the HELP button in the vain hope you would arrive at a page which would explain the cryptic message...

Development:Themes 2.0 adding a settings page

2010-06-11T13:00:49Z

Tqr: /* Creating a language file and adding our strings */

{{Template:Themes}}{{Moodle 2.0}}This document looks at how to create a settings page for your theme and how to make use of those settings within the CSS and layout files for your theme.

This is a pretty advanced topic and will require that you have at least an intermediate knowledge of PHP, CSS, and development in general.

==Before we begin==
[[Image:Theme.settings.page.03.png|350px|thumb|Our end goal. The settings page.]]
[[Image:Theme.settings.page.10.png|350px|thumb|And what it can do.]]
There is a huge body of knowledge that we must cover in following through this document and as such I think the best way to write this is as a tutorial.

My intentions for this tutorial are to replicate the standard theme but with a settings page that allows the administrator to set a background colour, set a logo to use with the page, and probably several other minor settings to change the way in which the theme is displayed.

I will start this tutorial by creating a new theme which will be largely a copy/paste of the current standard theme. I expect that anyone working through this tutorial has previously read the tutorial I wrote on [[Development:Themes 2.0 creating your first theme|creating your first theme]]. If you haven't go read it now because I'm not going to go into much detail until we get to the actual process of customising the theme and introducing the settings page.

So before we finally get this started please ensure you can check off everything on the following requirements list.
* Have a Moodle installation that has already been installed and configured and is ready to use.
* Have full read/write access to that installation.
* Be prepared to delete that installation at the end of this... we will destroy it!
* Have a development environment prepared and ready to use. This includes:
** Your favourite editor installed, running, and pointed at the themes directory of your installation.
** Your browser open and your site visible.
** A bottomless coffee pot... decaf won't help you with this one.
* Have turned on theme designer mode, if you don't know what this is please read the [[Development:Themes 2.0 creating your first theme|creating your first theme]] tutorial.
* Have turned on allowthemechangeonurl. This setting allows you to change themes on the URL and is very handy when developing themes.
* And finally an insane ambition to create a customisable theme.

For those interested the theme that I create throughout this tutorial can be downloaded from the forum post in which I announce this document: http://moodle.org/mod/forum/discuss.php?d=152053
<br style="clear:right;" />

==Our goals for this tutorial==
The following is just a list goals that I hope to achieve during this tutorial. They are laid out here so that I can easily refer back to them and so that you can easily find them.
# Create a new theme called '''demystified''' based upon the standard theme within Moodle 2.0.
# Make some minor changes to that theme to allow us to more easily see what is going on.
# Create a settings page for the demystified theme.
# Add several settings to our settings page.
# Use some of those settings to alter our CSS.
# Use the rest of those settings within our layout file..
# Discuss the good, the bad, and limits of what we have just created.

So I can see you are all very excited about this point and that you would love to know what settings we are going to create; So here they are:

A setting to ...
* change the background colour (CSS).
* set the path to an image that we will use as a logo on all pages (Layout files).
* override the width of the block regions (CSS).
* allow a note to be added to the footer of all pages (Layout files).
* allow custom CSS to be written to do anything the user wants. (CSS)

==Creating the demystified theme==
Before we start here I want to remind you that I am going to look at this only briefly as I am making the assumption that you have read the [[Development:Themes 2.0 creating your first theme|creating your first theme]] tutorial.

Well lets get into it....

The first thing we need to do is create a directory for our theme which we will call demystified.

So within your Moodle directory create the following folder '''moodle/theme/demystified'''. At the same time you can also create the following files and folders which we will get to soon.
* The file '''moodle/theme/demystified/config.php''' for our config information.
* The directory '''moodle/theme/demystified/layout''' for our layout files.
* The directory '''moodle/theme/demystified/style''' for our css files.
* The file '''moodle/theme/demystified/style/core.css''' which will contain our special CSS.

Next we will copy the layout files from the base theme to our new theme demystified. We are basing the demystified theme on the standard theme however that doesn't use it's own layout files it uses the base theme's layout files so those are the ones we want.

The reason that we are coping these layout files is that later on in this tutorial we will be modifying them to make use of our new settings... so copy all of the layout files from '''moodle/theme/base/layout''' to '''moodle/theme/demystified/layout'''.

There should be three files that you just copied:
# embedded.php
# frontpage.php
# general.php

Now we need to populate demystified/config.php with the settings for our new theme. They are as follows:
<code php>
$THEME->name = 'demystified';
</code>
Simply sets the name of our theme.

<code php>
$THEME->parents = array('standard','base');
</code>
This theme is extending both the standard theme and the base theme. Remember when extending a theme you also need to extend its parents or things might not work correctly.

<code php>
$THEME->sheets = array('core');
</code>
This tells our theme that we want to use the file '''demystified/style/core.css''' with this theme.

<div style="height:300px;overflow-y:scroll;">
<code php>
$THEME->layouts = array(
// Most backwards compatible layout without the blocks - this is the layout used by default
'base' => array(
'file' => 'general.php',
'regions' => array(),
),
// Standard layout with blocks, this is recommended for most pages with general information
'standard' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// part of course, typical for modules - default page layout if $cm specified in require_login()
'incourse' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// Server administration scripts.
'admin' => array(
'file' => 'general.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
// My dashboard page
'mydashboard' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'login' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('langmenu'=>true),
),

// Pages that appear in pop-up windows - no navigation, no blocks, no header.
'popup' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
// Embeded pages, like iframe/object embeded in moodleform - it needs as much space as possible
'embedded' => array(
'file' => 'embedded.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
// Used during upgrade and install, and for the 'This site is undergoing maintenance' message.
// This must not have any blocks, and it is good idea if it does not have links to
// other places - for example there should not be a home link in the footer...
'maintenance' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('noblocks'=>true, 'nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
);
</code>
</div>
Now that all looks very complicated however its really not too bad as it is just copied from the base theme's config.php file. We can do this because we copied the layout files from the base theme to begin with and for the time being there are no changes that we wish to make. Simply open up '''theme/base/config.php''' and copy the layouts from there.

And that is it. The config.php file for our demystified theme is complete. The full source is shown below:
<div style="height:300px;overflow-y:scroll;">
<code php>
<?php

// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* The demystified theme config file
*
* This theme was created to document the process of adding a settings page to a theme
*
* @copyright 2010 Sam Hemelryk
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

// The name of our theme
$THEME->name = 'demystified';

// The other themes this theme extends
$THEME->parents = array('standard','base');

// The CSS files this theme uses (located in the style directory)
$THEME->sheets = array('core');

// The layout definitions for this theme
$THEME->layouts = array(
// Most backwards compatible layout without the blocks - this is the layout used by default
'base' => array(
'file' => 'general.php',
'regions' => array(),
),
// Standard layout with blocks, this is recommended for most pages with general information
'standard' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// part of course, typical for modules - default page layout if $cm specified in require_login()
'incourse' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// Server administration scripts.
'admin' => array(
'file' => 'general.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
// My dashboard page
'mydashboard' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'login' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('langmenu'=>true),
),

// Pages that appear in pop-up windows - no navigation, no blocks, no header.
'popup' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
// Embeded pages, like iframe/object embeded in moodleform - it needs as much space as possible
'embedded' => array(
'file' => 'embedded.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
// Used during upgrade and install, and for the 'This site is undergoing maintenance' message.
// This must not have any blocks, and it is good idea if it does not have links to
// other places - for example there should not be a home link in the footer...
'maintenance' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('noblocks'=>true, 'nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
);
</code>
</div>

The screenshot below shows both the directory structure we have now created and the theme presently.

[[Image:Theme.settings.page.01.png]]

To view the theme so far open you browser and enter the URL of your site followed by '''?theme=demystified'''. You should see the theme that we just created which will look exactly like the base standard theme.

The final thing that we want to do is add a little bit of CSS to the demystified theme that will both visually set this theme apart from the standard theme and second build a the base which our settings can later extend.

I added the following snippet of CSS to the file '''demystified/style/core.css'''.
<code css>
html {background-color:#DDD;}
body {margin:30px;padding:0;border:1px solid #333;border-width:0 10px 0 10px;background-color:#333;}
body #page {background-color:#FFF;position:relative;top:-10px;}
.block .header {background-image:none;background-color:#0C5CAC;border:1px solid #0C5CAC;color:#FFF;}
.block {border-color:#4BA7FF;background-color:#DDEEFF;}
.block .content {background-color:#F1F8FF;}
a:link,
a:visited {color:#0C5CAC;}
a:hover {color:#C77500;}
#page #page-header {background-color:#0C5CAC;margin:0;padding:0;width:100%;color:#fff;}
#page #page-header a:link, #page #page-header a:visited {color:#FFAC02}
#page #page-header .navbar, #page #page-header .navbar a:link, #page #page-header .navbar a:visited {color:#0C5CAC;}
</code>

The CSS that we have just added to our theme sets a couple of colours on the front page. Presently this is the only CSS I will add, I know it isn't complete by any means but it achieves it's purpose as the screenshot below illustrates.

[[Image:Theme.settings.page.02.png|715px|thumb|left|The newly styles demystified theme]]<br style="clear:both;" />

And with that I will move on to the real purpose of this tutorial, creating the settings page

==Setting up the settings page==
With the demystified theme set up it is time to create the settings page. This is where the real PHP fun begins.

For those of you who happen to be familiar with development of modules, blocks or other plugin types you have probably encountered settings pages before and this is not going to be any different.

However for those who haven't which I imagine is most of you this is going to be quite a challenge. I will try to walk through this step by step however if at any point you get stuck don't hesitate to ask in the forums as I imagine you will get a speedy response.

===How settings pages work in Moodle===
Settings pages can be used by nearly every plugin type, of which themes is of course one. The way in which it all works isn't too tricky to understand.

All of the settings for Moodle can be configured through the administrator interfaces when logged in. I am sure that everyone here has seen those pages and has changed a setting or two before so you will all know what I am talking about. Well the settings page for a theme is no different. It will be shown in the administration pages tree under '''Appearance > Themes''' and all we have to do is tell Moodle what settings there are.

This is done by creating a settings.php file within out theme into which we will add code that tells Moodle about the settings we want to add/use.

When telling Moodle about each setting we are simply creating a new ''admin_setting'' instance of the type we want and the properties we want and then adding it to our settings page.

There is really not much more too it at this level. Things can get very complex very fast so the best thing we can do now is start creating our settings.php file for the demystified theme and see where it leads us.

===Creating the settings page===
So as mentioned before we need a settings.php file which we will create now. To begin with create the file '''theme/demystified/settings.php''' and open it in your favourite editor so its ready to go.

Before we start adding code however lets just remember the settings that we want to create:
* change the background colour (CSS).
* set the path to an image that we will use as a logo on all pages (Layout files).
* override the width of the block regions (CSS).
* allow a note to be added to the footer of all pages (Layout files).
* allow custom CSS to be written to do anything the user wants. (CSS)

Alright.

Now thinking about this the first setting is as basic as it gets, all we need is a text box that the user can type a colour into.

The second is to allow a logo to be used in the header of each page. What we want here is a path but should it be a physical path e.g. C:/path/to/image.png or should it be a web path e.g. <nowiki>http://mysite.com/path/to/image.png</nowiki>?
For the purpose of this tutorial I am going to go with a web path because it is going to be easier to code and will hopefully be a little easier to understand to begin with.

The third setting is a little more complex. For this I want a drop down box with some specific widths that the administrator can select.

The forth and the fifth settings are both pretty straight forward, there we want a textarea into which the user can enter what ever they want and we will do something useful with it.

Now that we have an understanding about the settings we wish to define pull up your editor and lets start coding....

<code php>
<?php

/**
* Settings for the demystified theme
*/

$temp = new admin_settingpage('theme_demystified', get_string('configtitle','theme_demystified'));
</code>
This is the first bit of code we must enter, the first line is of course just the opening php tag, secondly we have a comment that describes this file, and then we get create a new '''admin_settingspage object'''.

This admin_settingspage object that we have just created is a representation of our settings page and is the what we add our new settings to. When creating it we give it two arguments, first the name of the page which is in this case '''theme_''themename''''' and the title for the page which we get with the get_string method.

At the moment I'm not going to worry about adding the string, we will get to that later once we have defined all of our settings.

====Background colour====

With the page now created as ''$temp'' lets add our first setting: Background colour.

<code php>
// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$setting = new admin_setting_configtext($name, $title, $description, $default, PARAM_CLEAN, 12);
$temp->add($setting);
</code>
Thankfully this isn't as difficult as it initially looks.

The first line of code is creating a variable for the name of the background colour setting. In this case it is '''theme_demystified/backgroundcolor'''.

The name is very important, for the setting to be usable we have to follow a strict naming convention. '''theme_''themename''/''settingname''''' where '''''themename''''' is the name of the theme the setting belongs to and '''''settingname''''' is the name for the setting by which we will use it.

The second line of code creates a variable that contains the title of the setting. This is what the user sees to the right of the setting on the settings page and should be a short description of the setting. Here we are again using the ''get_string'' method so we will need to remember to add that string later on.

The third line of code sets the description. This should describe what the setting does or how it works and again we will use the get_string method.

The fourth line creates a variable that will be used as the default value for the setting. Because this setting is a colour we want an HTML colour to be the default value.

The fifth line is where we put it all together. Here we create a new '''admin_setting_configtext''' object. This object will represent the background colour setting.

When we create it we need to give it 6 different things.
# The name of the setting. In this case we have a variable '''$name'''.
# The title for this setting. We used the variable '''$title'''.
# The description of the setting '''$description'''.
# The default value for the setting. '''$default''' is the variable this.
# The type of value we want the user to enter. For this we have used PARAM_CLEAN which tells Moodle to get rid of any nasties from what the user enters.
# The size of the field. In our case 12 characters will be plenty.

The sixth and final line of code adds our newly created setting to the administration page we created earlier.

That is it we have successfully created and added our first setting, however there are several more to settings to do, and there are a couple of important things that you need to be aware of before we move on.

First: There are several different types of settings that you can create and add to a page, and each one may differ in what they need you to give them. In this case it was name, title, description, default, type, and size. However other settings will likely require different things. Smart editors like Netbeans or Eclipse can tell you what is required, otherwise you will need to research it.

Second: Normally settings are declared on one line as follows:
<code php>
$temp->add(new admin_setting_configtext('theme_demystified/backgroundcolor', get_string('backgroundcolor','theme_demystified'), get_string('backgroundcolordesc', 'theme_demystified'), '#DDD', PARAM_CLEAN, 12));
</code>
While this is structurally identical as all we have done is move everything onto one line and do away with the variables it is a little harder to read when you are learning all of this.

====The logo file====
Time to create the second setting that will allow the user to enter a URL to an image they wish to use as the logo on their site.
<code php>
// Logo file setting
$name = 'theme_demystified/logo';
$title = get_string('logo','theme_demystified');
$description = get_string('logodesc', 'theme_demystified');
$setting = new admin_setting_configtext($name, $title, $description, '', PARAM_URL);
$temp->add($setting);
</code>
The first thing that you will notice about this setting that it is very similar to the first setting, in fact all we have changed is the name, title, description, and default value. We have however changed the value type from PARAM_CLEAN to PARAM_URL, this makes sure the user enters a URL. You will also notice that for this one we don't set a size for the field as we have no idea how long the URL will be.

====Block region width====
The third setting should allow the user to set a width for the block regions that will be used as columns.

For this setting I want to do something a little different from the previous two, here I want to use a select box so that the user selects a width for the column from a list I provide.
<code php>
// Block region width
$name = 'theme_demystified/regionwidth';
$title = get_string('regionwidth','theme_demystified');
$description = get_string('regionwidthdesc', 'theme_demystified');
$default = 200;
$choices = array(150=>'150px', 170=>'170px', 200=>'200px', 240=>'240px', 290=>'290px', 350=>'350px', 420=>'420px');
$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$temp->add($setting);
</code>
So looking at the code: The first four lines you will recognise. $name, $title, $description, and $default are all being set.

The fifth line of code however introduces something new. Of course in order to have a select box we have to have options, in this case we have an array of options stored in the variable $choices.

The array of options is constructed of a collection of '''''value''' => '''label''''' pairs. Notice how we don't add '''px''' to the value. This is is very intentional as later on I need to do a little bit of math with that value so we need it to be a number.

The lines after should look familiar again, the only difference being that instead of a ''admin_setting_configtext'' setting we have created a ''admin_setting_configselect'' for which we must give the choices for the select box as the fifth argument.

Woohoo, we've just created our first select box setting.

====Foot note====
Now to create the foot note setting. Here we want the user to be able to enter some arbitrary text that will be used in the footer of the page. For this I want the user to be able to enter some HTML so I will create an editor setting.
<code php>
// Foot note setting
$name = 'theme_demystified/footnote';
$title = get_string('footnote','theme_demystified');
$description = get_string('footnotedesc', 'theme_demystified');
$setting = new admin_setting_confightmleditor($name, $title, $description, '');
$temp->add($setting);
</code>
How simple is that!

It is just about identical to the first two settings except that for this we have created a ''admin_setting_confightmleditor'' setting rather than a text setting.

Note: You can also set the columns and rows for the editor setting using the fifth and sixth arguments.

====Custom CSS====
The final setting is to allow the user to add some custom CSS to the theme that will be used on every page. I want this to be a plain textarea into which the user can enter CSS.
<code php>
// Custom CSS file
$name = 'theme_demystified/customcss';
$title = get_string('customcss','theme_demystified');
$description = get_string('customcssdesc', 'theme_demystified');
$setting = new admin_setting_configtextarea($name, $title, $description, '');
$temp->add($setting);
</code>
Just like the editor or text settings. It's getting very easy now!

====Finishing settings.php====
With all of our settings defined and added to our page that we created right at the beginning it is time to finish it all off.
<code php>
// Add our page to the structure of the admin tree
$ADMIN->add('themes', $temp);
</code>
The above line of code is the final line for the page. It is adding the page that we have created '''$temp''' to the admin tree structure. In this case it is adding it to the themes branch.

The following is the completed source for our settings.php ..... for your copy/paste pleasure.
<div style='height:300px;overflow:auto;'>
<code php>
<?php

/**
* Settings for the demystified theme
*/

// Create our admin page
$temp = new admin_settingpage('theme_demystified', get_string('configtitle','theme_demystified'));

// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$setting = new admin_setting_configtext($name, $title, $description, $default, PARAM_CLEAN, 12);
$temp->add($setting);

// Logo file setting
$name = 'theme_demystified/logo';
$title = get_string('logo','theme_demystified');
$description = get_string('logodesc', 'theme_demystified');
$setting = new admin_setting_configtext($name, $title, $description, '', PARAM_URL);
$temp->add($setting);

// Block region width
$name = 'theme_demystified/regionwidth';
$title = get_string('regionwidth','theme_demystified');
$description = get_string('regionwidthdesc', 'theme_demystified');
$default = 200;
$choices = array(150, 170, 200, 240, 290, 350, 420);
$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$temp->add($setting);

// Foot note setting
$name = 'theme_demystified/footnote';
$title = get_string('footnote','theme_demystified');
$description = get_string('footnotedesc', 'theme_demystified');
$setting = new admin_setting_confightmleditor($name, $title, $description, '');
$temp->add($setting);

// Custom CSS file
$name = 'theme_demystified/customcss';
$title = get_string('customcss','theme_demystified');
$description = get_string('customcssdesc', 'theme_demystified');
$setting = new admin_setting_configtextarea($name, $title, $description, '');
$temp->add($setting);

// Add our page to the structure of the admin tree
$ADMIN->add('themes', $temp);
</code>
</div>

===Creating a language file and adding our strings===
As I'm sure none of you have forgotten, throughout the creation of the our settings.php page, we used a lot of strings that I mentioned we would set later on. Well now is the time to set those strings.

First up create the following directories and file for our language strings:
* Directory '''theme/demystified/lang'''
* Directory '''theme/demystified/lang/en'''
* File '''theme/demystified/lang/theme_demystified.php'''

What we have created here is the required structure for Moodle to start looking for language strings.

First Moodle locates the lang directory, once found it looks within that directory for another directory that uses the character code for the language the user has selected, by default this is '''en''' for English. Once that is found it looks for the appropriate language file, in this case '''theme_demystified.php''' from which it will load all language strings for our theme.

If English isn't your chosen language simply replace the ''en'' directory with one that uses your chosen languages character code (two letters).

We can now add our language strings to '''theme/demystified/lang/theme_demystified.php'''. Copy and paste the following lines of PHP into this file.
<code php>
<?php

/**
* This file contains the strings used by the demystified theme
*/

$string['backgroundcolor'] = 'Background colour';
$string['backgroundcolordesc'] = 'This sets the background colour for the theme.';
$string['configtitle'] = 'Demystified theme';
$string['customcss'] = 'Custom CSS';
$string['customcssdesc'] = 'Any CSS you enter here will be added to every page allowing your to easily customise this theme.';
$string['footnote'] = 'Footnote';
$string['footnotedesc'] = 'The content from this textarea will be displayed in the footer of every page.';
$string['logo'] = 'Logo';
$string['logodesc'] = 'Enter the URL to an image to use as the logo for this site. Should be http://www.yoursite.com/path/to/logo.png';
$string['regionwidth'] = 'Column width';
$string['regionwidthdesc'] = 'This sets the width of the two block regions that form the left and right columns.';
</code>

In the above lines of code I have added an entry for each language string we used within ''settings.php''. When adding language strings like this make sure you use single quotes and try to keep things alphabetical - it helps greatly when managing strings.

Now when we view the settings page there will not be any errors or strings missing.

===Having a look at what we have created===
Now that we have created our settings page (settings.php) and added all of the language strings it is time to have a look at things in your browser.

Open your browser and enter the URL to your site. When you arrive at your site login as an administrator.

If you are not redirected to view the new settings change your URL to <nowiki>http://www.yoursite.com/admin/</nowiki> and your will see a screen to set the new theme settings we have just created. This lets us know that everything has worked correctly.

At any point now you are able to log in as administrator and within the settings block browse to '''Site administration > Appearance > Themes > Demystified theme''' to change those settings.

The screenshot below shows you what you should see at this point:

[[Image:Theme.settings.page.03.png|715px|thumb|left|The settings page we just created]]
<br style="clear:both;" />

==Using the settings in CSS==
With the settings page now created and operational it is time to make use of our new settings. The settings that we want to use within our CSS is as follows:

; backgroundcolor : Will be used to set the background colour in CSS.
; regionwidth : Will be the width of the column for CSS.
; customcss : Will be some custom CSS to add to our stylesheet.

At this point those names are the names we used for our setting with the slash and everything before it having been removed.

Before we start tearing into some code it is important that we have a look at what we are going to do and how we are going to go about it.

===How it all works within Moodle===
The first thing to understand is that while Moodle allows you to create a settings page and automates it inclusion and management right into the administration interfaces there is no smart equivalent for using the settings. This is simply because there is no way to predict how people will want to use the settings.

However don't think of this as a disadvantage, in fact it is quite the contrary. Although we can't just ''use'' our settings we can take full control over how and where we use them. It means it will take a little more code but in the end that will work to our advantage as we can do anything we want.

Moodle does help us out a little but not in an obvious way. The first thing that Moodle does is look for a config variable '''csspostprocess''' that should be the name of a function which we want called to make any changes to the CSS after it has been prepared.

The second thing Moodle does is include a lib.php from the theme's directory if one exists (also for the themes the current theme extends.) which ensures that as long as we write our code within '''theme/demystified/lib.php''' it will be included and ready to be used.

The third and final thing Moodle does that will help us out here is ensure that by the time any of code is ready to execute the settings have been prepared and are ready to be used within a theme config object which is passed into our ''csspostprocess'' function.

===Our plan===
As you have already probably guessed we will need to create a function to make the changes to the CSS that we want. We will then set the theme config option '''$THEME->csspostprocess''' to the name of our function.

By doing this when Moodle builds the CSS file it will call our function afterwards with the CSS and the theme object that contains our setting.

Now we know that we will use the ''csspostprocess'' function but how are we going to change the CSS, we could get the function to add CSS, or we could get the function to replace something within the CSS. My personal preference is to replace something within the CSS, just like what is happening with images. If you want to use an image within CSS you would write <nowiki>[[pix:theme|imagename]]</nowiki>.

For settings I am going to use <nowiki>[[setting:settingname]]</nowiki>, this way it looks a bit like something you are already familiar with.

What we need to decide upon next is the best way in which to replace our settings tag with the settings that the user has set.

There are two immediate options available to us:
# Make the ''csspostprocess'' function do all the work.
# Make the ''csspostprocess'' function call a separate function for each setting.
Solution 1 might sound like the simplest however it is going to result in a '''VERY''' complex function. Remember the user might have left settings blank or entered something that wouldn't be valid so we would need to make the sure there is some validation and a good default.
Because of this I think that solution 2 is the better solution.

So we are going to need a ''csspostprocess'' function and then a function for each of the three settings we have that will do the replacements.
<code php>
// This is our css post process function
function demystified_process_css($css, $theme) {};
// This replaces [[setting:backgroundcolor]] with the background colour
function demystified_set_backgroundcolor($css, $backgroundcolor) {};
// This replaces [[setting:regionwidth]] with the correct region width
function demystified_set_regionwidth() {$css, $regionwidth};
// This replaces [[setting:customcss]] with the custom css
function demystified_set_customcss() {$css, $customcss};
</code>

What you should note about the above functions is that they all start with the theme's name. This is required to ensure that the functions are named uniquely as it is VERY unlikely that someone has already created these functions.

So with our plan set out lets start writing the code.

===Writing the code===
The very first thing that we need to do is create a lib.php for our theme into which our css processing functions are going to go. So please at this point create '''theme/demystified/lib.php''' and open it in your editor ready to go.

The first bit of code we have to write is the function that will be called by Moodle to do the processing '''demystified_process_css'''.

Before we start out please remember that the wonderful thing about coding is that there is any number of solutions to a problem. The solutions that you are seeing here in this tutorial are solutions that I have come up with to meet fulfil the needs of the tutorial without being so complex that they are hard to understand. This probably isn't how I would go about it normally but this is a little easier to understand for those who aren't overly familiar with PHP and object orientation.

====The function: demystified_process_css====

<code php>
function demystified_process_css($css, $theme) {

if (!empty($theme->settings->backgroundcolor)) {
$backgroundcolor = $theme->settings->backgroundcolor;
} else {
$backgroundcolor = null;
}
$css = demystified_set_backgroundcolor($css, $backgroundcolor);

if (!empty($theme->settings->regionwidth)) {
$regionwidth = $theme->settings->regionwidth;
} else {
$regionwidth = null;
}
$css = demystified_set_regionwidth($css, $regionwidth);

if (!empty($theme->settings->customcss)) {
$customcss = $theme->settings->customcss;
} else {
$customcss = null;
}
$css = demystified_set_customcss($css, $customcss);

return $css;
}
</code>

So lets look at the things that make up this function:

<code php>
function demystified_process_css($css, $theme) {
//.....
return $css
}
</code>

This of course is the function declaration.

The function gets given two variables, the first '''$css''' is a pile of CSS as one big string, and the second is the theme object '''$theme''' that contains all of the configuration, options, and settings for our theme.

It then returns the ''$css'' variable, essentially returning the modified CSS.

<code php>
//...
if (!empty($theme->settings->backgroundcolor)) {
$backgroundcolor = $theme->settings->backgroundcolor;
} else {
$backgroundcolor = null;
}
$css = demystified_set_backgroundcolor($css, $backgroundcolor);
//...
</code>

Here we are processing our first setting ''backgroundcolor''.

The first thing that we need to do is check whether it has been set and whether it has a value. If it has then we store that value in '''$backgroundcolor'''. It is doesn't have a value then we set ''$backgroundcolor'' to null. This ensures that ''$backgroundcolor'' is set because if it isn't then you are going to get a notice (if you have debugging on).

The final line of this block calls the function '''demystified_set_backgroundcolor'''. We haven't written this function yet but we will shortly. When we call it we give it the ''$css'' variable that contains all of the CSS and we give it the background colour variable ''$backgroundcolor''. Once this function is finished it returns the ''$css'' variable with all of the changes made much like how our css processing function works.

What you should also note about this code is this:
<code php>
$theme->settings->backgroundcolor
</code>
As mentioned earlier ''$theme'' is an object that contains all of the configuration and settings for our theme. The ''$theme'' object has a $settings property which contains all of the settings for our theme, and finally the settings property contains a variable backgroundcolor that is the value the user entered for that setting. That is how we get a settings value.

<code php>
if (!empty($theme->settings->regionwidth)) {
$regionwidth = $theme->settings->regionwidth;
} else {
$regionwidth = null;
}
$css = demystified_set_regionwidth($css, $regionwidth);

if (!empty($theme->settings->customcss)) {
$customcss = $theme->settings->customcss;
} else {
$customcss = null;
}
$css = demystified_set_customcss($css, $customcss);
</code>

These two routines are nearly identical to the routine above. For both the regionwidth and the customcss we make sure it has a value and then store it in a variable. We then call the relevant function to make the changes for that setting.

Now that we have the general processing function it is time to write the three functions we have used but not written, ''demystified_set_backgroundcolor'', ''demystified_set_regionwidth'', ''demystified_set_customcss''.

====The function: demystified_set_backgroundcolor====

First up demystified_set_backgroundcolor.

<code php>
/**
* Sets the background colour variable in CSS
*
* @param string $css
* @param mixed $backgroundcolor
* @return string
*/
function demystified_set_backgroundcolor($css, $backgroundcolor) {
$tag = '[[setting:backgroundcolor]]';
$replacement = $backgroundcolor;
if (is_null($replacement)) {
$replacement = '#DDDDDD';
}
$css = str_replace($tag, $replacement, $css);
return $css;
}
</code>

Ok so what is happening here?

First we need a variable '''$tag''' that contains the tag we are going to replace. As mentioned earlier we are going to use tags that look like the image tags you are already familiar with ''<nowiki>[[setting:settingname]]</nowiki>'', in this case ''<nowiki>[[setting:backgroundcolor]]</nowiki>''.

Next I am going to create a variable called '''$replacement''' into which I put '''$backgroundcolor'''.

The '''IF''' statement that comes next checks ''$replacement'' to make sure it is not null. If it is then we need to set it to a default value. In this case I have used ''#DDD'' as that was the default for the settings.

The line after the IF statement puts it all together. The ''str_replace'' function that we are calling takes three arguments in this order:
# The text to search for.
# The text to replace it with.
# The text to do the replacement in.
It then returns the text with all of the replacements made. So in this case we are replacing the tag with the background colour and it is returning the changed CSS.

The final thing is to return the ''$css'' variable which now contains the correct background colour.

====The function: demystified_set_regionwidth====

Next we have the demystified_set_regionwidth function.
<code php>
/**
* Sets the region width variable in CSS
*
* @param string $css
* @param mixed $regionwidth
* @return string
*/
function demystified_set_regionwidth($css, $regionwidth) {
$tag = '[[setting:regionwidth]]';
$doubletag = '[[setting:regionwidthdouble]]';
$replacement = $regionwidth;
if (is_null($replacement)) {
$replacement = 200;
}
$css = str_replace($tag, $replacement.'px', $css);
$css = str_replace($doubletag, ($replacement*2).'px', $css);
return $css;
}
</code>

This function is very similar to the above function however there is one key thing we are doing different. We are doing two replacements.

# The first replacement is for the width that the user selected. In this case I am replacing the tag ''<nowiki>[[setting:regionwidth]]</nowiki>'' with the width.
# The second replacement is for the width x 2. This is because the page layout requires that the width be doubled for some of the CSS. Here I will replace ''<nowiki>[[setting:regionwidthdouble]]</nowiki>'' with the doubled width.

Remember because it is still just a number we need to add '''px''' to the end of each before we do the replacement.

So the overall process of this function is:
# Define the two tags as '''$tag''' and '''$doubletag'''.
# Make '''$replacement''' the region width ''$regionwidth''.
# Set ''$replacement'' to a default value of 200 is it is null.
# Replace '''<nowiki>[[setting:regionwidth]]</nowiki>''' with the width.
# Replace '''<nowiki>[[setting:regionwidthdouble]]</nowiki>''' with the width x 2.
# Return the changed CSS.

====The function: demystified_set_customcss====

The final function that we need to write is the demystified_set_customcss function.
<code php>
/**
* Sets the custom css variable in CSS
*
* @param string $css
* @param mixed $customcss
* @return string
*/
function demystified_set_customcss($css, $customcss) {
$tag = '[[setting:customcss]]';
$replacement = $customcss;
if (is_null($replacement)) {
$replacement = '';
}
$css = str_replace($tag, $replacement, $css);
return $css;
}
</code>

This function is just like the first function. I'm going to let you work it out on your own.

And that is it no more PHP... Hallelujah I can hear you yelling. The final thing we need to do is tell our theme about the functions we have written and put the settings tags into the CSS.

===Finishing it all off===

So there are two things we have to do in order to complete this section and have our the settings page implemented and our settings being used.

First we need to tell our theme that we want to use the function ''demystified_process_css'' as the ''csspostprocess'' function. This is done very simply by adding the following line of PHP to the bottom of our theme's config.php file '''theme/demystified/config.php'''.

<code php>
$THEME->csspostprocess = 'demystified_process_css';
</code>

With that done the only thing left is to add the settings tag into the CSS. Remember those settings tags are:

; <nowiki>[[setting:backgroundcolor]]</nowiki> : We need to add this where ever we want the background colour setting to be used.
; <nowiki>[[setting:regionwidth]]</nowiki> : We need to add this where ever we want to set the width of the block regions.
; <nowiki>[[setting:regionwidthdouble]]</nowiki> : We need to add this where ever we want to set the doubled width of the block regions.
; <nowiki>[[setting:customcss]]</nowiki> : We need to add this to the bottom of the CSS file that we want the custom CSS added to.

So lets make those changes in CSS now, open up your ''core.css'' file and replace the CSS with the CSS below:
<code css>
/** Background color is a setting **/
html {background-color:[[setting:backgroundcolor]];}
body {margin:30px;padding:0;border:1px solid #333;border-width:0 10px 0 10px;background-color:#333;}
body #page {background-color:#FFF;position:relative;top:-10px;}
.block .header {background-image:none;background-color:#0C5CAC;border:1px solid #0C5CAC;color:#FFF;}
.block {border-color:#4BA7FF;background-color:#DDEEFF;}
.block .content {background-color:#F1F8FF;}
a:link,
a:visited {color:#0C5CAC;}
a:hover {color:#C77500;}
#page #page-header {background-color:#0C5CAC;margin:0;padding:0;width:100%;color:#fff;}
#page #page-header a:link, #page #page-header a:visited {color:#FFAC02}
#page #page-header .navbar, #page #page-header .navbar a:link, #page #page-header .navbar a:visited {color:#0C5CAC;}
/** Override the region width **/
#page-content #region-main-box {left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidthdouble]];}
#page-content #region-main-box #region-post-box #region-pre {width:[[setting:regionwidth]];left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-post {width:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidthdouble]];}
.side-pre-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-pre-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
/** Custom CSS **/
[[setting:customcss]]
</code>

You will notice that <nowiki>[[setting:backgroundcolor]]</nowiki> has been used for the html tags background colour:
<code css>
html {background-color:[[setting:backgroundcolor]];}
</code>

We have also set the width of the block regions by adding <nowiki>[[setting:regionwidth]]</nowiki> as the width for region-pre and region-post as shown below:
<code css>
#page-content #region-main-box {left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidthdouble]];}
#page-content #region-main-box #region-post-box #region-pre {width:[[setting:regionwidth]];left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-post {width:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidthdouble]];}
.side-pre-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-pre-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
</code>
You'll notice here that we have to set several different widths and margins using the regionwidth setting and make use of the special regionwidthdouble setting that we added.

The final thing that we did was add the <nowiki>[[setting:customcss]]</nowiki> to the bottom of the file to ensure that the custom CSS comes last (and therefore can override all other CSS).

And with that we are finished. The screenshot below shows how this now looks in the browser if I set the background colour setting to '''<span style='color:#FFA800;'>#FFA800</span>''' and made the column width 240px;

[[Image:Theme.settings.page.04.png|715px|thumb|left|Our settings in action]]<br style="clear:both;" />

==Using the settings within our layout files==
Now that we have utilised the first three settings within our theme's CSS file it is time to implement the other two settings within the layout files so that they are written directly into the page.

You'll be glad to know this is no where near as difficult as utilising settings within a CSS file although it still does require a little bit of PHP.

First up is the logo setting. Into this setting the user is able to enter the URL to an image to use as the logo for the site. In my case I want this to be just a background logo on top of which I want to position the page header.

Before I start there is one thing I need to do however and that is create a default logo background that gets shown if the user hasn't set a specific logo file. To do this I simply created an image '''logo.jpg''' and put it into a pix directory within the demystified theme. You should end up with '''theme/demystified/pix/logo.jpg'''.

Next open up the front-page layout file ''theme/demystified/layout/frontpage.php''. At the top of the file is the PHP that checks what blocks regions the page has and a bit of other stuff. Well right below the existing bit of PHP we want to add the following code:
<code php>
if (!empty($PAGE->theme->settings->logo)) {
$logourl = $PAGE->theme->settings->logo;
} else {
$logourl = $OUTPUT->pix_url('logo', 'theme');
}
</code>
What we are doing here is creating a variable called $logourl that will contain the URL to a logo file that was either entered by the user or if they left it blank is that of our default logo file.

There are two things that you should notice about this. First the logo setting can be retrieved through '''$PAGE->theme->settings->logo''' and second we get the default logo url by calling '''$OUTPUT->pix_url('logo', 'theme')'''.

Now that we have the logo URL we are going to use we need to add an image to the header section of the page as shown below:
<code php>
<div id="page-header" class="clearfix">
<img class="sitelogo" src="<?php echo $logourl;?>" alt="Custom logo here" />
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
....
</code>

If you save that and browse to your sites front page you will notice that the logo file is now being shown. Hooray. However it is probably not styled too nicely so lets quickly fix that. Open up the core.css file and add the following lines of CSS to the bottom of the file.
<code css>
#page-header {position:relative;min-height:100px;}
#page-header .sitelogo {float:left;}
#page-header .headermain {position:absolute;left:0.5em;top:50px;margin:0;float:none;font-size:40px;}
</code>
These three lines position the image correctly and if you now refresh everything should appear perfectly.

With the logo done the last setting we need to deal with is the footnote setting. The idea with this setting was that the administrator could enter some text into the editor and it would be displayed in the footer of the page.

This is probably the easiest setting to implement.

Within the front page layout file that we edited above add the following lines below those we added previously.

<code php>
if (!empty($PAGE->theme->settings->footnote)) {
$footnote = $PAGE->theme->settings->footnote;
} else {
$footnote = '';
}
</code>

Here we are just collecting the footnote into a variable '''$footnote''' and setting a default footnote comment if the user hasn't entered one.

We can now echo the $footnote variable within the page footer. This can be done as shown below.

<code php>

<div id="page-footer">
<div class="footnote"><?php echo $footnote; ?></div>
<p class="helplink">
<?php echo page_doc_link(get_string('moodledocslink')) ?>
</p>
</code>

And with that done we are finished! Congratulations if you got this far.

The screenshot below shows the demystified theme we have just created that is styled by the settings page.

[[Image:Theme.settings.page.05.png|715px|thumb|left|My finished demystified theme]]<br style="clear:both" />

==Testing our creation==
Congratulations to you! If you've made it this far you have done very well. Now it is time to have a look at what we have created and give it a quick test run.

So in this tutorial we have achieved the following:

* We created a theme called demystified that is based on the standard theme.
* We added a settings page to our new theme.
* We added the following settings to our settings page:
** We can set a background colour through the admin interface.
** We can change the logo of the site.
** We can change the block region width.
** We can add a footnote to the page footer
** We can add some custom CSS to seal the deal.
* Those settings were then used in the CSS files for our theme.
* They were also used in the layout files for our theme.
* And here we are testing it all.

The screenshots below show my testing process and I change each setting and view the outcome. The great thing about this is that with theme designer mode on you see the changes as soon as the form refreshes.

[[Image:Theme.settings.page.06.png|300px|thumb|left|Default settings]]
[[Image:Theme.settings.page.07.png|300px|thumb|left|Changed the background colour setting]]
[[Image:Theme.settings.page.08.png|300px|thumb|left|Changed the logo and region width]]
[[Image:Theme.settings.page.09.png|300px|thumb|left|Added a footnote]]
[[Image:Theme.settings.page.10.png|300px|thumb|left|Added some custom CSS]]
<br style="clear:both" />

==Common pitfalls and useful notes==

This section is really just a collection of pointers, tips, notes, and other short useful stuff that may be of use to those attempting this tutorial.

# First up and most importantly there are very few limitations to what you achieve in this fashion.
# If you get stuck or need a hand ask in the forums, there's always someone round who can help.
# If you do something really cool let us know, I know everyone in the community loves finding our what others are achieving.

==More information==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 overriding a renderer]]
* [[Development:Styling and customising the dock]]
* http://moodle.org/mod/forum/discuss.php?d=152053

Themes FAQ

2010-06-10T20:16:03Z

Tqr: /* How do I install a new theme when using cPanel? */

{{Themes}}
==How do I install a new theme?==

# Unzip the .zip file to an empty local directory.
# Upload folder to your web server to the /moodle/theme/[Theme Name]. (Replace [Theme Name] with the name of the theme you have downloaded.) Ensure the new theme folder and its contents are readable by the webserver. Change Read and Write permissions (CHMOD) for the files and folder to 755 - Owner read/write/execute, Group read/execute, Everyone read/execute. Incorrect permissions may prevent display of the newly installed theme.
# Choose your new theme from within Moodle via ''Administration > Appearance > Themes > Theme selector'' (or ''Administration > Configuration > Themes'' in versions of Moodle prior to 1.7).

==How do I install a new theme when using cPanel?==

#Upload your new theme .zip file to your web server via cPanel.
#Then using cPanel install the new theme to your Moodle theme's folder. The new theme will be installed into its own folder at /moodle/theme/[mytheme] (where [mytheme] is the name of your new theme.
#Ensure the new theme folder and its contents are readable by the webserver. If necessary change Read and Write permissions (CHMOD) for the files and folder to 755 - Owner read/write/execute, Group read/execute, Everyone read/execute. Incorrect permissions may prevent display of the newly installed theme.
# Choose your new theme from within Moodle via ''Administration > Appearance > Themes > Theme selector'' (or ''Administration > Configuration > Themes'' in versions of Moodle prior to 1.7).

==How do I create a custom theme?==

See [[Creating a custom theme]] and/or [[Make your own theme]].

==Can I assign a specific theme to a course?==

Yes. In the course settings, use the "Force theme" dropdown box.

== Where shall I put my custom CSS code? ==

Instead of modifying the theme's CSS files you better put your own code in a separate CSS file and make your theme aware of that file by modifying its config.php file (be sure add your own CSS file as the last one in the list so that you will override all prior settings). See this posting for [http://moodle.org/mod/forum/discuss.php?d=128599#p564055 detailed instructions].

See also the instructions on creating your own theme mentioned above.

==How can I get the New Moodle2 theme for my site?==
Not til Moodle 2.x comes out and it will be a "sort of". The new look (refered to as "Moodle2") for Moodle.org was made public just before the close of 2008. The Moodle2 look has various things hard coded into its fabric. The good news is that many pieces of the look are available.

==Will I lose my courses, language files, logo, etc. if I switch my theme?==
Switching themes only changes the appearance of your site, not the content within it. The logo is a part of the theme and will be lost when you switch.

Follow these instructions to [[Creating_a_custom_theme#Adding_a_Logo|add a logo]] to a theme.

== Are there tools which help me creating and editing themes? ==

=== Clear Cache Button ===
This useful Firefox add-on let's you add a button to your tool bar for easily clearing your cache while working on your theme: https://addons.mozilla.org/de/firefox/addon/1801

<p class="note">Please note that the following tools are only for development. They only change the way ''you'' see your Moodle site, not the Moodle site itself. Any changes you make using these tools will not be visible to anyone else who uses your site. For this you will have to make those changes permanent by changing your theme's CSS files for example.</p>

=== Firebug ===
The single most useful tool is the [[Development:Firebug|Firebug]] add-on for the [[Firefox]] web browser. Firebug integrates with Firefox to put a wealth of development tools at your fingertips while you browse. You can edit, debug, and monitor CSS, HTML, and JavaScript live in any web page... And there are additional add-ons for making Firebug an even more powerful tool.

==== Firebug enhancements ====
You can enhance Firebug even further. See [[Firebug]] for more information.

=== Web Developer Toolbar ===
Another great tool for any web developer is the [[Web developer extension]], another Firefox add-on. One very useful feature is the option to '''disable your browser's cache''' while working on your theme. That way you are sure you're always presented with your latest modifications and not with an older, cached version.

Now also available for Google's Chrome browser: [http://www.sitepoint.com/blogs/2010/03/23/chrome-web-developer-toolbar/ "The Web Developer Toolbar Comes to Chrome"]

=== Stylish ===
Modifications made with Firebug are lost when refreshing your page. If you want your CSS changes to be a bit more permanent, for example to try them with different pages of your Moodle installation, you can use another Firefox plugin: [https://addons.mozilla.org/en-US/firefox/addon/2108 Stylish]. That way you can change your site's CSS with a simple mouse click without having to change Moodle code.

See [[Stylish]] for detailed instructions and examples.

== How do I check for cross-browser compatibility? ==
There are some tools (standalone and online) which can show you how your site looks in different browsers. See this [http://moodle.org/mod/forum/discuss.php?d=127746 forum discussion] for details.

== Concrete examples for modifying Moodle themes ==
<p class="note">
The following examples were taken from the former ''Theme Scrapbook'':
<br />
"The Moodle '''Theme Scrapbook''' is a collection of small how-to descriptions. You theme designers and Moodle users working with themes add your knowledge here to help new Moodle users with tips and tricks for their theme work.
<br />
Feel free to add to this list! Don't know how? Read our [[MoodleDocs:Guidelines_for_contributors|Guidelines for contributors]]."
</p>

=== Changing things ===

==== Colors ====
* [[Forcing the colour of the chat discussion pane (pop-up mode)]]
* [http://moodle.org/mod/forum/discuss.php?d=142765 Changing background colour of a topic box]

==== Logo and icons ====
* [[Alternate Icon Set|Using an alternate icon set in Moodle]]
* [[Favicon|Change the favicon that shows in front of the web address]]
* [[Footer replacement|Replace the logo in the footer with your web address and/or or own logo]]
*[[Header logo|Replace the logo in the header]]

==== Layout ====
* [http://moodle.org/mod/forum/discuss.php?d=136546 Overriding the $menu / $button variables] using PHP regular expressions in header.html
* [http://moodle.org/mod/forum/discuss.php?d=143411 Changing the view of course categories] - work in progress
* [http://moodle.org/mod/forum/discuss.php?d=143411 Sub categories and courses layout] - work in progress

=== Adding things ===
* [[Header logo|Adding a logo to the theme header]]

=== Hiding things ===
* Hiding an element with CSS is generally achieved using the [http://reference.sitepoint.com/css/display display: none;] property on the element.
* See [[Print style]] and [[Stylish#Print style for Database records]] for an example how to hide parts of a page not meant for printing.

=== Moving things ===
* [[Center Forum Posts|Centre smaller forum posts on the page]]
* [[Footer positioning|Positioning the page footer]]
* [[Left-align quiz|Left align quiz questions and answers]]
* [http://moodle.org/mod/forum/discuss.php?d=121847 Indentation for nested categories]
* [http://moodle.org/mod/forum/discuss.php?d=128599 Positioning login and choose language field]
* [http://moodle.org/mod/forum/discuss.php?d=145179 Match question type - position answers nearer to the questions]

=== Miscellaneous ===
* [[Fixed-width theme|Creating a fixed-width theme]]
* [[Homepage design|Homepage design of moodle.org]]
* [http://moodle.org/mod/forum/discuss.php?d=146763 Is there a way to fix oversized HTML Editor using CSS?]

==How can I see theme changes when using the Windows Complete Installer package==
In the [http://download.moodle.org/windows/ Windows Complete Installer package], the eAccelerator in the XAMPP install can cause some issues with changes to your theme's CSS and HTML files from showing.

Open the php.ini file inside of the server\php folder from your install in notepad and search for "eAccelerator" you should see a line that reads:
extension=eaccelerator.dll

Insert a semi-colon (turns the line into a comment) at the start of this line so it now reads:
;extension=eaccelerator.dll

Restart the Moodle server using the "stop moodle" and then the "start moodle" programs in your server folder. You should now find that all of your changes to your CSS are reflected as soon as you save the file and refresh your browser cache (usually you can refresh your cache by pressing F5). This FAQ from a discussion at [http://moodle.org/mod/forum/discuss.php?d=151562#p663950 Deactivating caching with XAMPP installations]

== See also ==

* Using Moodle [http://moodle.org/mod/forum/view.php?f=29 Themes forum]
* [[CSS FAQ]]
* [http://learn.open.ac.uk/mod/oublog/view.php?user=155976 "Understanding Moodle Themes"] - Blog post by [http://moodle.org/user/view.php?id=78896&course=5 Christopher Douce] (Open University)
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=149534 Testing 2.0. Use for modern vs old browsers] forum discussion

[[Category:FAQ]]
[[de:Designs_FAQ]]