Moodle 2.0

PROJECT STATE: Proposal
MAIN TRACKER ISSUE: n/a
DISCUSSION AND COMMENTS: n/a
AUTHOR: Petr Škoda (škoďák) + feedback and ideas from other developers
TIME NEEDED FOR IMPLEMENTATION: a few days

Please note this is a work in progress, do not edit - use page comments instead if needed, thanks.

Goals

The main goals are:

simplify core and themes code
easier theme customizations - both CSS and images
allow themes to be stored in dataroot
improve performance
solve majority of browser caching problems
use YUI CSS foundation

It should be easy to upgrade simple older themes. I think it is better if old themes are completely disabled with reasonable fallback mechanism. Why should we display broken themes during upgrade? Imagine users or teachers can select "broken" themes in course edit page or profile? I think it is more professional to display "My nice theme (upgrade required)" in theme selectors, instead of pretending old themes will work 100%.

Design overview

All theme files are served through two files /theme/styles.php and /theme/image.php. If more advanced themes need extra javascript files we could add optional /theme/javascript.php file and new config option with list of JS files.

All CSS style sheets (including YUI, plugin CSS and parents) are merged into single large CSS file served via the /theme/styles.php file. This script accepts following parameters:

theme - string, name of the theme, usually from current_theme()
rtl - bool, modified style sheet for RTL languages, usually from current_language()
rev - int, theme revision number stored in main config table ($CFG-themerevision)

The theme config.php can is simplified, the complete list of available options is:

$THEME->parents = array('standard', 'purple'); lists all parents top-down, each theme contains the full list of parents, this is non-recursive and more flexible specification without any limits
$THEME->sheets = array('styles_layout', 'styles_fonts', 'styles_color'); the same as before, lists files from current theme directory
$THEME->parents_exclude_sheets('standard'=>array('styles_moz'), 'purple'=>array('styles_fonts.css')); it is also posssible to use true instead of array in order to specify all sheets or all sheets in all parents, , if not specified the value from the parent theme is used
$THEME->plugins_exclude_sheets('mod_book', 'gradereport_grader'); - specifies individual plugin styles that should be excluded from this theme, if not specified the value from the parent theme is used
$THEME->layouts = array(...); - the same as before, cascades through parent themes
other resource and filter hacks $THEME->resource_mp3player_colors, $THEME->filter_mediaplugin_colors;, if not specified the value from the parent theme is used
CSS constant definitions, values are merged with all parent themes - this is probably the easiest way to creator different colour variations of one theme

Implementation

One huge CSS sheet

Each page includes only one huge style sheet. The URL is returned from $OUTPUT->get_theme_stylesheet_url($iehack=) function. All theme sheets are served by a /theme/styles.php script. Page parameters specifying theme name, RTL flag and revision.

The CSS concatenation is done using the YUI CSS, styles.css from all plugins and theme CSS, please note the order is very important. The algorithm is following:

YUI CSS
1. merge all YUI CSS into one file, respect correct order of files
2. inject image placeholders instead of relative links {{yui|someimage}}
plugins CSS
1. go through all plugins and search for styles.css - put the list into array, use component names as keys, locations as values
2. filter out excluded sheets specified in current $THEME->plugins_exluded_sheetes
theme CSS
1. go through all sheets defined in all parents and store all #THEME->sheets in array
2. filter out excluded sheets specified in current $THEME->parent_exluded_sheetes
resolve real image locations
1. regex search for {{image:componentname|imagewithsibdirnoext}}
2. priority is: current theme, parent themes, then plugin or YUI fodlers
3. images in web accessible areas are linked directly, images in dataroot would have to go through /theme/image.php?theme=xxx&image=/sub/img
resolve our CSS constants

Please note that the current $PAGE->requires->css() does not fit into this proposed design.

IE6/7 are an exception are handled through special body tags.

Theme caching

Potential problems are:

server performance - the merging of all CSS, parent themes and image resolving is relatively expensive
bandwidth - longer caching, fewer files and optional gzip compression
stale data in browser caches - different file needs to be served when anything in CSS changes

The theme CSS content depends on:

current theme
current language RTL flag
theme revision

The theme revision is stored in $CFG->themerevision, it is an integer counter incremented after installation/upgrade of any plugin or core. The revision is also bumped up right after switching on/off theme designer mode or even manually.

Theme designer mode

Administrator, theme designers and developers often need to tweak CSS. In previous versions users had to purge the browser caches manually.

In theme designer mode no CSS is cached on server or in browser, each changes are immediately visible. The switching on of this mode immediately invalidates old caches, the caching is turned on again after switching it off. This mode causes higher server load.

The setting should be available from the Appearance settings page.

Performance improvements

There are several possibilities for more performance improvements:

storing of final CSS files in dataroot - caches need to be deleted after each theme revision change; this could significantly reduce server load
longer lifetimes - revision parameter eliminates the stale CSS in browser cache completely , lower bandwidth consumption
gzip compression - faster page loading on first page
remove comments and useless white space
etc.

Browser hacks

Old meta.php was used mostly for conditional loading of IE specific hacks. Open university developed alternative solution which adds browser specific classes to body html element.

<body class="ie ie7">

#mypage .whatever {
 /** normal rules */
}
.ie6#mypage .whatever {
 /** broken rules */
}

OU used these hacks not only for IE ;-)

YUI

Moodle started using YUI framework around 1.7, until 2.0dev we did not use any UI widgets that required CSS. The problem is that the YUI needs to be loaded before theme and plugin CSS, second problem is that standard YUI CSS requires reset CSS which greatly improves A-grade browser compatibility and helps theme designers.

In 2.0dev there was an option to use external YUI library, unfortunately we can not use external CSS because we need to recalculate image links (this allows easy overriding of YUI images without actually overriding the CSS definition.

YUI CSS foundation

Why should we base our themes on YUI CSS foundation? Why not? The benefits are:

eliminates some different HTML defaults (margins, paddings, font sizes, etc.) (YUI CSS Reset)
consistent font sizing and better font-family degradation (YUI CSS Fonts)
incredibly simple table-less page layouts that include nesting (YUI CSS Grids)
the standard YUI CSS is already built on top of this foundation

I do not think we should expect any problems related to the use of YUI CSS foundation, it looks like the current themes need only minor tweaking to make it compatible (already tested).

Core and custom themes could use the extremely simple and powerful YUI CSS Grids framework for page layout. I do not think we could quickly develop anything as reliable and compatible before the release of 2.0.

If we do not use this foundation we have to write all CSS for standard YUI widgets, this could be very time consuming and the results/timeframe are not predictable.

YUI widgets customisation

The standard YUI CSS has to be loaded after YUI CSS Base (Reset+Fonts+Grids), but before our own CSS. The CSS may be overridden through plugin styles.css or theme styles. YUI standard images could be simply changed by adding different images with the same name into theme/standard/yui_pix/.. or any other theme. The image resolver would first look into current theme, all parents and the last option would be standard YUI library

YUI versioning

In 1.9 we store all YUI files in /lib/yui/ folder, this may be a potential problem when upgrading YUI version from upstream because the old files could be still cached in browsers. Solution could be to add version number /lib/yui/x.yy/.

Image resolver

Images are used in html code and in CSS style sheets. The problem is easy to solve in PHP code, partial solution was already present in Moodle 1.9 - see $CFG->pixpath

In 2.0dev there was implemented a new icon_finder class, it can be replaced by much simpler rules, we could also add pix support into all plugins.

Image locations:

/lib/yui/
/mod/modulename/pix/, blocks/blockname/pix/ - in all plugins
/theme/themename/pix/ - standard theme images
/theme/themename/yui_pix/ - overriding of yui images from themes
/theme/themename/plugin_pix/component_name/ - overriding of plugin images in themes

The standard API is $OUTPUT->get_image_url($componentname, $imagename) when used from PHP and {{image:componentname|imagenamewithpathwithoutextension}} if used in CSS.

There are a few exceptions like theme favicon and screenshots, all other images should be placed in pix directories.

Image resolved allows us to also serve images from dataroot via /theme/image.php script.

Themes in dataroot

A frequently requested feature...

Backwards compatibility and upgrades

BC is very limited, all themes and modules need to be manually updated. Keeping old themes during the upgrade must not cause fatal PHP errors. Old themes can be detected by searching for /theme/oldtheme/styles.php, this file will not be present in the new themes any more. Moodle core would simply use the specified parent theme or the standard theme.

Theme upgrade steps

delete styles.php
redefine all config.php options - in majority of cases change parent value to parents array
rename styles_ie6.css and styles_ie7.css to styles_layout_ie6.css and styles_layout_ie7.css - each normal sheet may have an extra sheet with _ieX suffix now, these are loaded automatically, excluding is applied based on $THEME->parents_exclude_sheets() info from the current theme
rename rtl.css to styles_layout_rtl.css - again each normal style sheet may have extra sheet with _rtl suffix similar to IE hacks sheets
delete header.html, footer.html and meta.php - obsoleted by $THEME->layouts option and new layout files
add custom layouts and rendereds

In order to minimize confusion during the upgrade, the old themes will be ignored and will be listed os "Incompatible" on the theme selection page - this page is probably the first place admins go in order to diagnose theme problems.

Module upgrade steps

rename mod/modname/styles.php to styles.css
put all images into mod/modname/pix/
replace $CFG->pixpath with $OUTPUT->get_icon_url('imagename', 'mod_modname')

Removed features

sometheme/meta.php - used mostly for IE6/7 hacks, custom layouts may be used instead, see reasoning against this ->requires->css() bellow
smartpix - completely obsoleted by the new image location resolution algorithm
$CFG->themewww, $CFG->themedir and friends - themes can be stored in dataroot, web hosting companies may use shared dirroot without custom themes, the styles.php URLs would be always constructed via some helper functions
styles.php replaced by styles.css, supported in all plugin types - the PHP is not needed because images are specified using {{image:component|dir/image}} syntax
$PAGE->requires->css() replaced by styles.css in each plugin - we can not load it in the middle of the huge CSS file because it is browser specific, we can not load it before because YUI Reset would alter it, we should not load it after because theme could not override it
$CFG->pixpath replaced by $OUTPUT->get_icon_url()

Documentation

Theme changes in 2.0

Contents