MoodleDocs - Contribucions de l'usuari [ca]

Themes 2.0

2011-01-17T13:17:40Z

DougNix: /* Layout 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 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 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 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 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.

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

==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]]
[[es:Temas 2.0]]

Themes 2.0

2011-01-17T13:14:41Z

DougNix: minor grammatical changes

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

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

==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]]
[[es:Temas 2.0]]

DragMath equation editor

2010-01-29T16:13:49Z

DougNix:

===Introduction===
To quote the W3C [http://www.w3.org/Math/Software/mathml_software_cat_editors.html]:
This is an open-source drag and drop equation editor written in Java.
Once an expression is created the user can convert it into a variety
of different linear syntax for mathematics, including MathML, LaTeX,
Maple, Maxima or any user defined style.
Created by Christoper Sangwin and Alexander Billingsley at the University of Birmingham as part of the [http://www.stack.bham.ac.uk STACK project], DragMath allows students to build mathematical expressions using a graphical drag-and-drop interface similar in appearance to that available in a number of office productivity suites.

Initially integrated with Moodle to be used with Moodle's Tex filter, the export feature available with DragMath has now allowed an integration that supports the creation of LaTex text expressions with and without the doubledollar signs used to signal parsing by the filter as well as AsciiMathML text expressions.

To use DragMath, users must have the Java Runtime Environment (JRE) version 1.5 or higher installed on their desktop computers. Most systems come with the JRE as standard equipment, so you may not have to do anything. If you need to install the JRE manually, you can download it from [http://java.com/en/download/index.jsp here]. Note that the JRE is variously known as Java software for your computer, Java Runtime Environment, the Java Runtime, Runtime Environment, Runtime, Java Virtual Machine, Virtual Machine, Java VM, JVM, VM, or Java download.

You can see a demo of the DragMath editor [http://www.dragmath.bham.ac.uk/ here]. The DragMath interface is highly intuitive and anyone can be using it productively after a few minutes of trial-and-error. If you have questions about the editor, there is a short manual [http://www.dragmath.bham.ac.uk/doc/index.html here].

===How the DragMath editor has been integrated with Moodle===

[[Category:Mathematics]]
DragMath is integrated with Moodle through a new button on the editor toolbar. This way, the DragMath editor is available everywhere that you or your students are called upon to enter text. '''Please note:''' The DragMath editor does not come supplied with Moodle. You (or your administrator) will have to install it. The following comments are targeted at the single file install, which has retained the beloved smileys.

====Getting Started====
Suppose that you're entering text in the HTML editor and you reach a point where you want to insert a mathematical expression. You want to be able to show the text expression you would use to create an equations as well as the equations itself. Pushing the DragMath button launches the DragMath editor in a small popup window (Note: the first time you do this, there will be a delay of a few seconds due to applet initialization).

====Create the math expression in DragMath====
Drag the various graphic constituents of your equation into the construction area until the equation is to your satisfaction.

====Save the expression====
From the Menu Bar click File->Save As or click on the floppy icon. Provide a local location where you want to save the equation and the applet stores the equation there in a .dgrm file.

====Select Export Format====
From the Menu Bar click Options->Set Export Format. If you want to insert the text expression for a tex formula, select LaTex. If you wish to insert the text expression with the doubledollar tokens so that the expression will be converted by the moodle tex filter, select MoodleTex (this will likely be the default choice in your applet). If you have replaced your tex filter with the ASCIIMathML filter, select ASCIIMathML.

====Insert the expression====
Click the "Insert button" and you're done. The editor will disappear and the output you selected will be inserted. If you chose MoodleTex, the LaTeX expression (with $$ delimiters added at both ends) will be inserted into your text at the current cursor position. Note the screen shot below. This demonstrates the results when you have selected MoodleTex to insert the equation in your work. '''Note ASCIIMathML users:''' the ASCIIMathML.xml file currently has backtics set as tokens. You can edit that file to use the auto nomenclature if you choose

====Altering Applet Parameters====
The window presented by the dragmath plugin is controlled by an applet reference in a php file, which for htmlarea in Moodle 1.9.x is dlg_ins_dragmath.php, one of the files included in the distribution, which can be found in moodleroot/lib/editor/htmlarea/popups . Applet parameters, per the dragmath documentation, can be changed in this file. By default, the language is set to English and the output format is set to MoodleTex (that is, the output will include double dollars signs, and if you have turned off your tex filter and are using asciimath then you will probably want to set your default export format to ASCIIMathML.)

In answer to the prayers of users, the STACK folk added the ability to drop the dot that DragMath had always inserted in 3x between the coefficient and the variable as in 3∙x . You will find a menu item in DragMath's gui to turn this on and off right next to the menu items for formatting. This setting can also be set via an applet parameter.

You can add formats and languages via /lib/DragMath/Config.xml with the various XML export formats in the formats subdirectory of applets and the languages in the lang subdirectory. Of course you can, with care, edit the various xml files.

Should you wish to make any changes, please remember to back up a copy of your original file.

[[Image:Dragmath_instructions.png|DragMath instructions]]

===Installing DragMath===
The most current version of DragMath can now be installed properly by simply using unzip (see the section immediately below this one). The Moodle CVS system and issues with managing adminlib.php have resulted in our going to this new and easier to use package. The new package offers a single zip that includes not only the integration files (at least for htmlarea for the present and with smileys) but the current DragMath files as well. The file can be unzipped in place, a welcome change from the hassles of installing with the Moodle CVS zip; just place the zip file in the moodle root and unzip.

This method is different than the two previously used. Beware of relying on installation advice or files posted in forums prior to July 2009 as they may be addressing files and methods no longer in use. You may also find a variety of development code in the forums regarding use of dragmath with a number of editors. Some of this may work and some may not, but none of it will be current. Use at your own risk!

DragMath may eventually become core technology in Moodle, meaning that as of a certain version no installation may be required, but installation instructions will continue to remain so as to support older versions as long as feasible.

====Installing DragMath from the non-CVS Zip - Recommended!====
We have come full circle and as a result of the issues with maintaining a current adminlib.php for every version as well as with the potential move of dragmath that may take place with Moodle 2, dragmath is now available as a [http://tracker.moodle.org/secure/attachment/18040/dragmathintegration_v0.7.8.1_final.zip zip file] that can be easily installed from your root moodle directory (unlike the CVS zip described below, one reason we recommend you no longer use the CVS zip.)

Simply place the zip file above in your root moodle directory (/moodle for many) and unzip. The dragmath files will be installed in their correct locations. Additionally, you will get a file called adminlib_exampleonly.php which you can diff with your adminlib.php to demonstrate the addition of the lines to allow you to turn the dragmath icon on and off (see [[DragMath equation editor#Managing Your Editor Icons Through adminlib.php]]).

If you are using prior versions of DragMath it is suggested that you do a new install as there have been some changes internal to the DragMath directory as well as to the integration files. Once you have done a new install, future versions of DragMath in Moodle 1.9.x will likely only require that you replace the DragMath directory that has now been located at /lib/DragMath with a newer directory from sourceforge (or you can wait until you see an updated on Moodle).

Early adopters of the as yet unreleased Moodle 2 should note that dragmath is presently included in HEAD (do not do any installation) and you should review the section on Moodle 2 below for further information.

====Installing DragMath From the Moodle CVS - NOT RECOMMENDED====
Please note that the Moodle CVS for dragmath is no longer being supported. The files however are still present and if you insist you can access them. It is recommended that you DO NOT DO THIS.

If you are running version 1.9.+ [http://download.moodle.org/patches19/dragmath.zip click here] or if you are running Moodle version 1.8.4 or greater but not 1.9.x [http://download.moodle.org/patches18/dragmath.zip click here]
and you will start the download of the cvs zip file (at present there are no differences between the two versions.)

At this point you can unzip on your workstation and then you can upload the included files to their appropriate locations ('''but read the warning below first'''). This version retains the smileys and includes all integration files and all DragMath files (demos, docs, and all export formats) The Moodle automagically creates the zip with a parent directory of "dragmath". Should you wish you can unzip the files and then rezip with the top level directory being /lib, and this will allow you to simply upload the zip you just created to your moodle root and unzip there, and the files will be placed in their appropriate locations. However, please DO NOT include the adminlib.php file and make sure all files are backed up, and in as much as there are only a few files you may want to manually install even if a zip with /lib as top directory were provided here just to ensure each file is backed up before installation. Upload the zip file to your Moodle root and unzip.

'''Warning:''' At present the CVS zip file includes a version of adminlib.php. This file is included because there is a line added to it that allows you to hide the dragmath icon. In any event, the included adminlib.php should '''NOT''' be used to over write your adminlib.php!

'''DO NOT''' over write your adminlib.php. Install the rest of the files (other than adminlib.php) and DragMath will work without a problem.
====Managing Your Editor Icons Through adminlib.php====
To be able to add your dragmath icon, save your existing copy of adminlib.php (you will find it in the /lib directory) and insert this line:
'insertdragmath' => 'em.icon.dragmath.gif',

below this line:
'insertsmile' => 'em.icon.smile.gif',

and save. The line can really be placed anywhere in that array, but by providing a specific location it will help when addressing requests for assistance in hiding buttons. And, having taken the time to explore this beautiful little array, you can now alter your button images to your hearts content!

The array is employed by the admin GUI (Site Administration-> Appearance->HTML editor) to provide you the Administrator with the ability to hide buttons in the HTML editor via editorhidebuttons. Once you have installed Dragmath and added the button, you can use the GUI to hide the insertdragmath button.

You may ask, what about altering the adminlib.php file in the CVS or providing a patch? [http://tracker.moodle.org/browse/MDL-16280 This was raised and you can vote on it.] Let's get real here folks, we are talking about one line which could be added to adminlib.php at 1.8.4 or later without any other impact. Is it really necessary to provide a separate adminlib.php for dragmath everytime someone changes adminlib.php in the core? If you have an opinion on this please edit the page comments on this and provide your input as to whether adminlib.php should just be dropped from the dragmath distribution.

===Locally saving and restoring a DragMath expression===
When you press the Insert button, DragMath inserts the export string into your text and the DragMath window closes. ''The exported string can no longer be manipulated using DragMath.'' If you decide to change the string, you have two options:
*delete the string (including the dollar signs or other token) and completely recreate it using DragMath
*edit the expression by hand
You can not tell DragMath to re-read the expression and show it again in two dimensions. This is a theoretical limitation, not a limitation of DragMath.

But suppose the expression is very complicated. It would be impractical to start over just to make a simple change. Before you Insert the expression, you can save a copy of the expression (a .drgm file) to your local disk using the Save button (see screenshot). Later, if you need to make a change, you open the saved .drgm file.

[[Image:Dragmath_save_and_restore.png|DragMath instructions]]

A .drgm file contains three-dimensional representation of your mathematical expression. It is a binary file that can only be opened by DragMath.
===Troubleshooting===
====unzip====
Some packages like winRAR provide a separate setting that prefixes the archives name on directories. In order for the files to be properly placed when the archive is unzipped you must make sure this is not the case. In winRAR for Windows for example you can go to Options->Settings and on the Compression tab you will see something to the effect of "Append archive name to path"; make sure this is not set!

Also, please note that the non-cvs zip is created so that the files in various directories are placed correctly. If, however, you set unzip or instruct unzip not to overwrite but to rename, then you will unpack the archived files into new directories (for example /lib(2) instead of /lib) and your install will not work.

====java jre====
Dragmath is java based, and unless you have a current java runtime environment you will likely run into trouble. Make sure you keep your JRE current and that the current JRE is selected.

===Development===
====Extending DragMath to Moodle 1.9.x Chat====
.
.
.
.
====Language Files====
The 0.7.8.1 package now includes language files (with Finnish, courtesy of Mauno Korpelainen) and the integration files should provide for automatic selection of the language based on the Moodle language setting.
====Square brackets====
Use of text expressions in the Moodle Wiki can create problems when the text expression includes square brackets, which is how TeX expresses the nth root. Pending a simple wiki based solution users may want to use the ASCIIMathML filter and the ASCIIMathML export format as this combination avoids the use of square brackets.
====Consistent integration with all html editors====
The Moodle discussion regarding html editors suggests that it will be important for DragMath to have consistent integration with a variety of html editors as htmlarea passes into obsolescence. Plugins for tinyMCE, Xinha and FCKEditor with a similar structure and common codebase are ready and compatible with all browsers that support javascript and Java.
====Additional formats====
There are quite a few options now available for creating text expressions to for displaying equations and Moodle functionality can only be increased if tools were able to create and parse expressions created by the tools a user is most comfortable with. ASCIIMathML is one tool now available as a filter for Moodle that allows the parsing of both TeX and its own ASCIIMathML text expression syntax. Microsoft has now launched its OMML initiative in Office 2007 (see footnotes on http://en.wikipedia.org/wiki/Office_Open_XML and OpenOffice employs its own text expression syntax (the OOo syntax is described at http://documentation.openoffice.org/manuals/oooauthors2/0216WG-MathObjects.pdf).
The ability to have DragMath create text expressions that can be used in native documents as well as parsed by filters such as ASCIIMathML will help make use of equations on-line more transparent for everyone.
====Math Chat====
Having been introduced by Marc Grober to a math chat application (http://www.imathas.com/cur/mathchat/testchat.html) it would be useful to see similar features in Moodle's chat, specifically:

1. The ability to ''easily'' display mathematical symbols with DragMath incorporated into the chat window.

2. The ability to create and display mathematical graphs.

===Moodle 2===
<s>As part of planning for Moodle 2 we have recommended that DragMath be placed in /lib/editor/common/dragmath alongside asciimathml (which is located in /lib/editor/common/asciimath). This should not result in any other major changes and those wanting to stay abreast may either want to look moving files before Moodle 2 or may want to keep an eye out for a zip of asciimath and dragmath packaged as a precursor to Moodle 2.</s>

Discussion of the transition of DragMath to Moodle core: http://moodle.org/mod/forum/discuss.php?d=125977&parent=551794

[[ca:DragMath_editor_d%27equacions]]

DragMath equation editor

2010-01-29T14:59:14Z

DougNix:

===Introduction===
To quote the W3C [http://www.w3.org/Math/Software/mathml_software_cat_editors.html]:
This is an open-source drag and drop equation editor written in Java.
Once an expression is created the user can convert it into a variety
of different linear syntax for mathematics, including MathML, LaTeX,
Maple, Maxima or any user defined style.
Created by Christoper Sangwin and Alexander Billingsley at the University of Birmingham as part of the [http://www.stack.bham.ac.uk STACK project], DragMath allows students to build mathematical expressions using a graphical drag-and-drop interface similar in appearance to that available in a number of office productivity suites.

Initially integrated with Moodle to be used with Moodle's Tex filter, the export feature available with DragMath has now allowed an integration that supports the creation of LaTex text expressions with and without the doubledollar signs used to signal parsing by the filter as well as AsciiMathML text expressions.

To use DragMath, users must have the Java Runtime Environment (JRE) version 1.5 or higher installed on their desktop computers. Most systems come with the JRE as standard equipment, so you may not have to do anything. If you need to install the JRE manually, you can download it from [http://java.com/en/download/index.jsp here]. Note that the JRE is variously known as Java software for your computer, Java Runtime Environment, the Java Runtime, Runtime Environment, Runtime, Java Virtual Machine, Virtual Machine, Java VM, JVM, VM, or Java download.

You can see a demo of the DragMath editor [http://www.dragmath.bham.ac.uk/ here]. The DragMath interface is highly intuitive and anyone can be using it productively after a few minutes of trial-and-error. If you have questions about the editor, there is a short manual [http://www.dragmath.bham.ac.uk/doc/index.html here].

===How the DragMath editor has been integrated with Moodle===

[[Category:Mathematics]]
DragMath is integrated with Moodle through a new button on the editor toolbar. This way, the DragMath editor is available everywhere that you or your students are called upon to enter text. '''Please note:''' The DragMath editor does not come supplied with Moodle. You (or your administrator) will have to install it. The following comments are targeted at the single file install, which has retained the beloved smileys.

====Getting Started====
Suppose that you're entering text in the HTML editor and you reach a point where you want to insert a mathematical expression. You want to be able to show the text expression you would use to create an equations as well as the equations itself. Pushing the DragMath button launches the DragMath editor in a small popup window (Note: the first time you do this, there will be a delay of a few seconds due to applet initialization).

====Create the math expression in DragMath====
Drag the various graphic constituents of your equation into the construction area until the equation is to your satisfaction.

====Save the expression====
From the Menu Bar click File->Save As or click on the floppy icon. Provide a local location where you want to save the equation and the applet stores the equation there in a .dgrm file.

====Select Export Format====
From the Menu Bar click Options->Set Export Format. If you want to insert the text expression for a tex formula, select LaTex. If you wish to insert the text expression with the doubledollar tokens so that the expression will be converted by the moodle tex filter, select MoodleTex (this will likely be the default choice in your applet). If you have replaced your tex filter with the ASCIIMathML filter, select ASCIIMathML.

====Insert the expression====
Click the "Insert button" and you're done. The editor will disappear and the output you selected will be inserted. If you chose MoodleTex, the LaTeX expression (with $$ delimiters added at both ends) will be inserted into your text at the current cursor position. Note the screen shot below. This demonstrates the results when you have selected MoodleTex to insert the equation in your work. '''Note ASCIIMathML users:''' the ASCIIMathML.xml file currently has backtics set as tokens. You can edit that file to use the auto nomenclature if you choose

====Altering Applet Parameters====
The window presented by the dragmath plugin is controlled by an applet reference in a php file, which for htmlarea in Moodle 1.9.x is dlg_ins_dragmath.php, one of the files included in the distribution, which can be found in moodleroot/lib/editor/htmlarea/popups . Applet parameters, per the dragmath documentation, can be changed in this file. By default, the language is set to English and the output format is set to MoodleTex (that is, the output will include double dollars signs, and if you have turned off your tex filter and are using asciimath then you will probably want to set your default export format to ASCIIMathML.)

In answer to the prayers of users, the STACK folk added the ability to drop the dot that DragMath had always inserted in 3x between the coefficient and the variable as in 3∙x . You will find a menu item in DragMath's gui to turn this on and off right next to the menu items for formatting. This setting can also be set via an applet parameter.

You can add formats and languages via /lib/DragMath/Config.xml with the various XML export formats in the formats subdirectory of applets and the languages in the lang subdirectory. Of course you can, with care, edit the various xml files.

Should you wish to make any changes, please remember to back up a copy of your original file.

[[Image:Dragmath_instructions.png|DragMath instructions]]

===Installing DragMath===
The most current version of DragMath can now be installed properly by simply using unzip (see the section immediately below this one). The Moodle CVS system and issues with managing adminlib.php have resulted in our going to this new and easier to use package. The new package offers a single zip that includes not only the integration files (at least for htmlarea for the present and with smileys) but the current DragMath files as well. The file can be unzipped in place, a welcome change from the hassles of installing with the Moodle CVS zip; just place the zip file in the moodle root and unzip.

This method is different than the two previously used. Beware of relying on installation advice or files posted in forums prior to July 2009 as they may be addressing files and methods no longer in use. You may also find a variety of development code in the forums regarding use of dragmath with a number of editors. Some of this may work and some may not, but none of it will be current. Use at your own risk!

DragMath may eventually become core technology in Moodle, meaning that as of a certain version no installation may be required, but installation instructions will continue to remain so as to support older versions as long as feasible.

====Installing DragMath from the non-CVS Zip - Recommended!====
We have come full circle and as a result of the issues with maintaining a current adminlib.php for every version as well as with the potential move of dragmath that may take place with Moodle 2, dragmath is now available as a [http://tracker.moodle.org/secure/attachment/18040/dragmathintegration_v0.7.8.1_final.zip zip file] that can be easily installed from your root moodle directory (unlike the CVS zip described below, one reason we recommend you no longer use the CVS zip.)

Simply place the zip file above in your root moodle directory (/moodle for many) and unzip. The dragmath files will be installed in their correct locations. Additionally, you will get a file called adminlib_exampleonly.php which you can diff with your adminlib.php to demonstrate the addition of the lines to allow you to turn the dragmath icon on and off (see [[DragMath equation editor#Managing Your Editor Icons Through adminlib.php]]).

If you are using prior versions of DragMath it is suggested that you do a new install as there have been some changes internal to the DragMath directory as well as to the integration files. Once you have done a new install, future versions of DragMath in Moodle 1.9.x will likely only require that you replace the DragMath directory that has now been located at /lib/DragMath with a newer directory from sourceforge (or you can wait until you see an updated on Moodle).

Early adopters of the as yet unreleased Moodle 2 should note that dragmath is presently included in HEAD (do not do any installation) and you should review the section on Moodle 2 below for further information.

====Installing DragMath From the Moodle CVS - NOT RECOMMENDED====
Please note that the Moodle CVS for dragmath is no longer being supported. The files however are still present and if you insist you can access them. It is recommended that you DO NOT DO THIS.

If you are running version 1.9.+ [http://download.moodle.org/patches19/dragmath.zip click here] or if you are running Moodle version 1.8.4 or greater but not 1.9.x [http://download.moodle.org/patches18/dragmath.zip click here]
and you will start the download of the cvs zip file (at present there are no differences between the two versions.)

At this point you can unzip on your workstation and then you can upload the included files to their appropriate locations ('''but read the warning below first'''). This version retains the smileys and includes all integration files and all DragMath files (demos, docs, and all export formats) The Moodle automagically creates the zip with a parent directory of "dragmath". Should you wish you can unzip the files and then rezip with the top level directory being /lib, and this will allow you to simply upload the zip you just created to your moodle root and unzip there, and the files will be placed in their appropriate locations. However, please DO NOT include the adminlib.php file and make sure all files are backed up, and in as much as there are only a few files you may want to manually install even if a zip with /lib as top directory were provided here just to ensure each file is backed up before installation. Upload the zip file to your Moodle root and unzip.

'''Warning:''' At present the CVS zip file includes a version of adminlib.php. This file is included because there is a line added to it that allows you to hide the dragmath icon. In any event, the included adminlib.php should '''NOT''' be used to over write your adminlib.php!

'''DO NOT''' over write your adminlib.php. Install the rest of the files (other than adminlib.php) and DragMath will work without a problem.
====Managing Your Editor Icons Through adminlib.php====
To be able to add your dragmath icon, save your existing copy of adminlib.php (you will find it in the /lib directory) and insert this line:
'insertdragmath' => 'em.icon.dragmath.gif',

below this line:
'insertsmile' => 'em.icon.smile.gif',

and save. The line can really be placed anywhere in that array, but by providing a specific location it will help when addressing requests for assistance in hiding buttons. And, having taken the time to explore this beautiful little array, you can now alter your button images to your hearts content!

The array is employed by the admin GUI (Site Administration-> Appearance->HTML editor) to provide you the Administrator with the ability to hide buttons in the HTML editor via editorhidebuttons. Once you have installed Dragmath and added the button, you can use the GUI to hide the insertdragmath button.

You may ask, what about altering the adminlib.php file in the CVS or providing a patch? [http://tracker.moodle.org/browse/MDL-16280 This was raised and you can vote on it.] Let's get real here folks, we are talking about one line which could be added to adminlib.php at 1.8.4 or later without any other impact. Is it really necessary to provide a separate adminlib.php for dragmath everytime someone changes adminlib.php in the core? If you have an opinion on this please edit the page comments on this and provide your input as to whether adminlib.php should just be dropped from the dragmath distribution.

===Locally saving and restoring a DragMath expression===
When you press the Insert button, DragMath inserts the export string into your text and the DragMath window closes. ''The exported string can no longer be manipulated using DragMath.'' If you decide to change the string, you have two options:
*delete the string (including the dollar signs or other token) and completely recreate it using DragMath
*edit the expression by hand
You can not tell DragMath to re-read the expression and show it again in two dimensions. This is a theoretical limitation, not a limitation of DragMath.

But suppose the expression is very complicated. It would be impractical to start over just to make a simple change. Before you Insert the expression, you can save a copy of the expression (a .drgm file) to your local disk using the Save button (see screenshot). Later, if you need to make a change, you open the saved .drgm file.

[[Image:Dragmath_save_and_restore.png|DragMath instructions]]

A .drgm file contains three-dimensional representation of your mathematical expression. It is a binary file that can only be opened by DragMath.
===Troubleshooting===
====unzip====
Some packages like winRAR provide a separate setting that prefixes the archives name on directories. In order for the files to be properly placed when the archive is unzipped you must make sure this is not the case. In winRAR for Windows for example you can go to Options->Settings and on the Compression tab you will see something to the effect of "Append archive name to path"; make sure this is not set!

Also, please not that the non-cvs zip is created so that the files in various directories are placed correctly. If, however, you set unzip or instruct unzip not to overwrite but to rename, then you will unpack the archived files into new directories (for example /lib(2) instead of /lib) and your install will not work.

====java jre====
Dragmath is java based, and unless you have a current java runtime environment you will likely run into trouble. Make sure you keep your JRE current and that the current JRE is selected.

===Development===
====Extending DragMath to Moodle 1.9.x Chat====
.
.
.
.
====Language Files====
The 0.7.8.1 package now includes language files (with Finnish, courtesy of Mauno Korpelainen) and the integration files should provide for automatic selection of the language based on the Moodle language setting.
====Square brackets====
Use of text expressions in the Moodle Wiki can create problems when the text expression includes square brackets, which is how TeX expresses the nth root. Pending a simple wiki based solution users may want to use the ASCIIMathML filter and the ASCIIMathML export format as this combination avoids the use of square brackets.
====Consistent integration with all html editors====
The Moodle discussion regarding html editors suggests that it will be important for DragMath to have consistent integration with a variety of html editors as htmlarea passes into obsolescence. Plugins for tinyMCE, Xinha and FCKEditor with a similar structure and common codebase are ready and compatible with all browsers that support javascript and Java.
====Additional formats====
There are quite a few options now available for creating text expressions to for displaying equations and Moodle functionality can only be increased if tools were able to create and parse expressions created by the tools a user is most comfortable with. ASCIIMathML is one tool now available as a filter for Moodle that allows the parsing of both TeX and its own ASCIIMathML text expression syntax. Microsoft has now launched its OMML initiative in Office 2007 (see footnotes on http://en.wikipedia.org/wiki/Office_Open_XML and OpenOffice employs its own text expression syntax (the OOo syntax is described at http://documentation.openoffice.org/manuals/oooauthors2/0216WG-MathObjects.pdf).
The ability to have DragMath create text expressions that can be used in native documents as well as parsed by filters such as ASCIIMathML will help make use of equations on-line more transparent for everyone.
====Math Chat====
Having been introduced by Marc Grober to a math chat application (http://www.imathas.com/cur/mathchat/testchat.html) it would be useful to see similar features in Moodle's chat, specifically:

1. The ability to ''easily'' display mathematical symbols with DragMath incorporated into the chat window.

2. The ability to create and display mathematical graphs.

===Moodle 2===
<s>As part of planning for Moodle 2 we have recommended that DragMath be placed in /lib/editor/common/dragmath alongside asciimathml (which is located in /lib/editor/common/asciimath). This should not result in any other major changes and those wanting to stay abreast may either want to look moving files before Moodle 2 or may want to keep an eye out for a zip of asciimath and dragmath packaged as a precursor to Moodle 2.</s>

Discussion of the transition of DragMath to Moodle core: http://moodle.org/mod/forum/discuss.php?d=125977&parent=551794

[[ca:DragMath_editor_d%27equacions]]

Grades

2010-01-13T03:09:03Z

DougNix:

{{Grades}}<p class="note">'''Note:''' This page, together with the pages listed in the block on the right, describe the gradebook in Moodle 1.9 onwards. For documentation on the gradebook in Moodle prior to 1.9, see [[Grades pre-1.9]].</p>

==Introduction==

The concepts of ''grades'' and of ''gradebook'' have been completely revisited in Moodle 1.9. These words and modules were used in earlier version. There are important differences that users who are upgrading to 1.9 need to understand and this should also help new users.

The two central ideas of grading in Moodle 1.9 are:

#'''Grades''' are scores attributed to participants in a Moodle course
#The '''gradebook''' is a repository of these grades: modules push their grades to it, but the gradebook doesn't push anything back to the modules

The three building blocks of the Gradebook in Moodle 1.9 are

*The [[Grade_categories|grade category]]
:A grade category groups grade items together, and has settings for affecting these grade items
*The [[Grade_items|grade item]]
:A grade item stores a grade for each course participant, and has settings for affecting these grades
*The grade -Student scores in a course
:A grade has settings for affecting how it is displayed to the users, as well as [[Grade locking|locking]] and [[Grade hiding|hiding]] functions.

As an overview:
Grades can be [[Grade_calculations|calculated]], [[Grade_categories#Aggregation|aggregated]] and [[Grader_report#Display|displayed]] in a variety of ways, the many settings having been designed to suit the needs of a great variety of organisations.

Many activities in Moodle, such as [[Assignment module|assignments]], [[Forum module|forums]] and [[Quiz module|quizzes]] may be given grades. Grades may have numerical values, or words/phrases from a [[Scales|scale or rating system]].

Grades can also be used as [[Outcomes|outcomes]] and as arbitrary text attributed to each participant in a course.

==Grades pushed by modules==
When activity modules produce grades, they use the [[Development:Grades#API_for_communication_with_modules.2Fblocks|gradebook public API]] to push (or send) their grades to the gradebook. These grades are then stored in database tables that are independent of the modules. The grades are still kept in the module database tables, and the gradebook will never access or modify these original grades.

The gradebook, however, provides administrators and teachers with tools for changing the ways in which grades are calculated, aggregated and displayed, as well as [[grade/edit/tree/grade|means to change the grades manually]] (a manual edit of a grade automatically locks the grade in the gradebook, so that the module which originally created the grade can no longer update that grade in the gradebook until the grade is unlocked).

==Settings affecting grades==
Being the smallest unit in the gradebook, the grade is affected by many settings at different levels. Here is a list of these levels, in hierarchical order:

*[[General_grade_settings|Site-wide general settings]]
*[[Grade_category_settings|Site-wide grade category settings]]
*[[Grade_item_settings|Site-wide grade item settings]]
*[[Gradebook_report_settings|Gradebook report settings]]
*[[Gradebook_course_settings|Course settings]]
*[[Grade_categories|Category settings]]
*[[Grade_items|Grade item settings]]
*[[grade/edit/tree/grade|Grade settings]]

==Outcomes==

[[Outcomes]] are specific descriptions of what a student is expected to be able to do or understand at the completion of an activity or course. An activity might have more than one outcome, and each may have a grade against it (usually on a [[Scales|scale]]).

==Gradebook reports==

The gradebook includes a variety of reports, available via the grades link in each [[Course administration block|course administration block]]:

* [[Grader report]] - The main teacher view of a course gradebook. The "[[Grade preferences|My report preferences]]" tab in the grader report enables teachers to change how the grader report is displayed.
* [[Outcomes report]]
* [[Overview report]]
* [[User report]]

==Grades organisation==

Teachers may organise grades into [[Grade categories|grade categories]], [[Grade import|import]] and/or [[Grade export|export]] grades, and make [[Grade calculations|grade calculations]].

Symbols to represent ranges of grades may be set as [[Grade letters|grade letters]].

Administrators may control the appearance of the gradebook site-wide by adjusting settings available via the grades link in the site administration block:

*[[General grade settings]]
*[[Grade category settings]]
*[[Grade item settings]]
*[[Gradebook report settings]]

==See also==

*Using Moodle [http://moodle.org/mod/forum/view.php?id=2122 Gradebook forum]

Video tutorials:
*[http://www.youtube.com/watch?v=YeUy-_kbvqQ Basic Moodle Gradebook howto]
*[http://www.youtube.com/watch?v=5hrLNbifiGQ Gradebook reports]
*[http://www.youtube.com/watch?v=lXEefYe3qdk How to use the grade item settings and grade letters at admin level]
*[http://www.youtube.com/watch?v=sUslTuZPu6A Grade category settings]
*[http://www.youtube.com/watch?v=EB58W3KePBc How to set up the gradebook]
*[http://www.youtube.com/watch?v=PmkEGfvjj9U How to use outcomes in Moodle]
*[http://www.youtube.com/watch?v=yZcbN_7p2zI How to export grades from the gradebook]
*[http://www.youtube.com/watch?v=p6zWwJGb9TA How to use gradebook site settings and defaults]
*[http://www.youtube.com/watch?v=WKUGyzAXcyA How to set up calculations in the gradebook (basic)]
*[http://www.youtube.com/watch?v=VBEj8mmu8lM How to set up calculations in the gradebook (advanced)]
*[http://www.youtube.com/watch?v=jWPUEqdhI4A How to change the display of grades in the gradebook]

[[ca:Qualificacions]]
[[cs:Známky]]
[[de:Bewertungen]]
[[eu:Kalifikazioak]]
[[fr:Notes]]
[[es:Calificaciones]]