Theme changes in 2.0

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:

1. easier theme customisations - both CSS and images
2. simplify core and themes code
3. allow themes to be stored in dataroot
4. improve performance
5. solve majority of browser caching problems
6. 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 the course edit page or a profile, I think it is more professional to display "My older 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 an optional /theme/javascript.php file and a new config option with list of JS files. This approach allows us to parse the resulting CSS and replace all image placeholders and theme settings with current values.

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

• theme (string) - name of the theme
• rev (int) - theme revision number stored in $CFG->themerevision

All options and features are reviewed and optimised. Backwards compatibility is not a primary concern, future possibilities and easy maintenance are always favoured.

Theme config.php

The theme config.php structure is simplified and a bit more flexible. The goal is to make overriding of parent themes simple and easy to understand.

$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. Originally the number of parent levels was restricted.

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

$THEME->resource_mp3player_colors, $THEME->filter_mediaplugin_colors If not specified the value from the parent theme is used.

$THEME->rendererfactory = 'standard_renderer_factory'; The same as before.

Implementation

One huge CSS sheet

Each page includes only one huge style sheet. The URL is returned from $OUTPUT->theme_stylesheet_url($encoded) function. All theme sheets are served by a /theme/styles.php script. Page parameters specify the theme name and revision.

The CSS concatenation is done from the YUI CSS, styles.css from all plugins and theme style sheets starting with top most parent and current theme last, please note the order is very important. The algorithm is following:

1. YUI CSS
   1. merge all YUI CSS into one file, respect correct order of files
   2. inject image placeholders instead of relative links [[pix:yui|someimage]]
2. 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
3. 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
4. resolve real image locations
   1. regex search for [[pix: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&file=/sub/img&component=moodle&rev=-1
5. apply theme admin settings - values and image locations

Please note that the current $PAGE->requires->css() is suitable mostly for user supplied CSS for data content such as the custom CSS used in mod/data.

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
• 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 value -1 is used in theme designer mode to prevent the caching completely.

All images used both from PHP and CSS have to be cached too. This is handled automatically in /theme/image.php which accepts similar parameters like the styles.php script.

The theme designer mode

Administrator, theme designers and developers often need to tweak CSS or images. 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.

This mode also disables all CSS cleanup and compression, all comments are kept and extra debug information can be included in CSS.

This 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. This can be implemented in the pagelib method returning standard body tags.

<body class="ie ie7">

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

OU used these hacks not only for IE ;-)

RTL support

Originally RTL tweaks were stored in separate files. Now we use the same body class tweaks as described above.

<body class="dir-rtl">

#mypage .whatever {
 /** normal rules */
}
.dir-rtl #mypage .whatever {
 /** RTL rules */
}

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

The 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:

• /mod/modulename/pix/, blocks/blockname/pix/ - in all plugins
• /theme/themename/pix/ - theme images
• /theme/themename/pix_core/ - overridden images from core /pix/ folder
• /theme/themename/pix_yui/ - overriding of yui images from themes
• /theme/themename/pix_plugins/plugin/plugintype/ - overriding of plugin images in themes

The standard API is $OUTPUT->image_url($componentname, $imagename, encoded) when used from PHP and [[pix:componentname|imagename]] 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 serve images from dataroot via /theme/image.php script and also solves the browser caching issues.

Themes in dataroot

A frequently requested feature...

Some admins might not like this, it should be optional. Some really advanced themes with lots of custom files might not be compatible at first. In fact it does not have to be dataroot, this location could be configurable.

Admin theme settings

Very often users need to make small tweaks to standard themes such as different colour or logos. There should be a way to keep this settings in config_plugin and files separately in dataroot. Settings are placed in /theme/themename/settings.php. This new feature could significantly reduce known theme upgrade problems in the future.

This feature replaces the original CSS constants and will probably use the same syntax. The original CSS constants required modifications in dirroot which was in some cases unacceptable. CSS constants would not be compatible with automatic updates vie web interface anyway.

This feature requires advanced caching of CSS. These settings and files should be available in layouts and renderers too.

I do not have any idea how to implement the file support yet, but using of own logos in themes is a very common practise.

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

1. delete styles.php
2. redefine all config.php options - in majority of cases change parent value to parents array
3. 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
4. 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
5. delete header.html, footer.html and meta.php - obsoleted by $THEME->layouts option and new layout files
6. 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->icon_url('imagename', 'mod_modname')

Removed features

1. sometheme/meta.php - used mostly for IE6/7 hacks, custom layouts may be used instead
2. smartpix - completely obsoleted by the new image location resolution algorithm
3. $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
4. styles.php replaced by styles.css, supported in all plugin types - the PHP is not needed because images are specified using [[pix:component|dir/image]] syntax
5. $CFG->pixpath replaced by $OUTPUT->get_icon_url()
6. CSS constants replaced by the admin theme settings
7. separate IE6 and IE7 sheets - replaced by body class attributes
8. separate RTL sheets - replaced by body class attribute

Expected reactions

User type	Negative	Positive
Core developer	none	No backwards compatibility headaches. Powerful new features. More flexible API.
Contrib developer	Has to learn new API	New useful pix folder and standard styles.css in all plugins. $OUTPUT->icon_url() more flexible then old pixpath.
Theme designer	Has to learn new theme API. Old advanced themes has to be completely redesigned.	They can finally override core and plugin images. New income opportunity - all themes need to be updated. Easier distribution of custom themes. Basic theme structure is simplified. No browser caching issues when designing themes.
Administrator	All themes need to be updated. Old themes are ignored.	Much easier installation (optionally in dataroot) and easy customisation without code modification (images and colours for example). Much safer upgrades. Possibility to upgrade theme via web interface. No browser caching issues when upgrading themes. Much better performance.