Development:Theme changes in 2.0

From MoodleDocs

Template:Moodle 2.0

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. improve performance
  4. solve majority of browser caching problems
  5. use YUI CSS foundation
  6. full template support - no templates in core yet though
  7. allow themes to be stored in dataroot (optional in future)

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 only new and upgraded themes in selectors instead of pretending old themes will work 100%. We have to make sure old themes will not cause fatal white screen errors.

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 directory structure

File/folder'
'Description
db/ (optional) Installation and upgrade hooks - use of db tables is not recommended.
lang/ Folder with standard language files - name of theme, usage information, settings. Standard themes store lang files in /lang/.
layout/ Folder with page layout templates
pix/ Folder with theme pictures - used from CSS or layout only, not used from other plugins.
pix_core/ (optional) Folder with overridden core images and icons from /pix/ folder
pix_plugins/ (optional) Folder with overridden plugin icons - structure is typeofplugin/pluginname/ which maps to pix folder in plugins
pix_yui/ (optional) Folder with overridden YUI CSS images, maps to /lib/yui/assets/sam/
template/ Folder with template files - structure is typeofplugin/pluginname/templatename.php which maps to pix folder in plugins (not in 2.0)
config.php Theme configuration - see bellow.
favicon.ico Site icon.
lib.php (optional) Library functions - custom css post-processing, custom render factory, theme init function
renderers.php (optional) Custom renderers used from custom renderer factories.
settings.php (optional) Custom theme settings - colours, logos, etc. Settings are applied in custom css post-processing function.
styles_*.css (optional) Style sheet files.
version.php Needed for install and upgrade hooks, states compatibility with specific Moodle versions. Used for triggering of cache purging.

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->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->sheets = array('styles_layout', 'styles_fonts', 'styles_color'); The same as before, lists files from current theme directory.


$THEME->editor_sheets = array('styles_tinymce'); We can not load the full CSS file into the HTML editor's content area, instead we load editor sheet from lib/editor/editorname/editor_sheets.css and also sheets specified in theme.


$THEME->plugins_exclude_sheets('mod_book', 'gradereport_grader'); Ideally all plugin specific CSS should be stored in styles.css file separately in each plugin. This option lists plugins that should be excluded from this theme, if not specified the value from the parent theme is used.


$THEME->layouts = array(...); The complete list of themes is in theme/standard/config.php. Page layouts are in fact high level templates that are using PHP syntax. The template files are stored in template/ subdirectory. Each page layout has specification of block areas and link to template file. Themes may also reference template files from other themes.


$THEME->resource_mp3player_colors, $THEME->filter_mediaplugin_colors Obsoleted. If not specified the value from the parent theme is used. All these should be moved to real theme settings.


$THEME->rendererfactory = 'standard_renderer_factory'; The same as before. It is the name of class that returns needed instances of core and plugin renderers. defined in core some library or theme/themename/lib.php or theme/themename/renderers.php


$THEME->csspostprocess = 'csspostprocess'; Name of custom CSS post-processing function, this function is usually defined in theme/themename/lib.php.

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

Combination of YUI 2 and 3

YUI 3 uses JS autoloading which is a great step forward and simplification. Unfortunately we still need the YUI2 libraries around for some time, we can remove them only after YUI 3 matures enough and has all the features.

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.


In the stable branch we have a strange mix of standard themes. The simplified installation and upgrades would allow us to lower the number of themes in official distribution. I think we need only:

  • standard - basic theme that can be used as base for other themes
  • customcolor - standard with admin specified colour palette and custom logos
  • and one other fancy modern theme like anomaly with multiple configuration settings

Other contrib themes would be available via web interface from Moodle configuration.

We can reimplement the original $CFG->themedir, but instead of replacing the $CFG->dirroot/theme/ completely it would just contain extra custom themes.

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.

The actual replacing of setting placeholders by setting values is performed in custom css post-processing function specified in config.php. Logos and other custom images would be specified as external URLs, later we could also add basic support for storage of these custom theme files in standard Moodle filesystem.

Page layout

Each page may specify one of standard page layouts that are defined in theme/standard/config.php. It is not possible to add custom layouts.

Layout definition consists of:

  • template file specification - template name + file name without extension
  • definition of regions
  • default region

New layouts will not be added in the STABLE CVS branches.

Renderers

Renderers are small methods that render visual elements using functional programming - our old style PHP style.


Module may define own renderer class and use own renderer methods. Themes may override both core and plugin renderers however you need to have some more advanced understanding of PHP and Moodle design in general.

Templates

Similar to page layouts but much smaller parts of UI that are embedded into pages. This is a new feature that is not used in Moodle core yet.

Code developers may choose to use templates instead of renderers for some larger parts of UI, they may also use renderers from templates. The major difference is that templates accept just one $DATA object with all parameters, templates might be also much easier to use&understand for typical theme designers.

The original emulated templates approach was replaced because it was designed for code developers, not designers. I think it is much easier to just copy templates from core or plugins into themes and tweak them, instead of the reverse engineering of the renderers.


Please note this does not mean that Moodle is switching to templates now, but technically we could, plugin developers may decide to do so independently.

Other API changes

  • added course layout
  • $PAGE->set_generaltype() replaced by $PAGE->set_pagelayout() because it really switches to one of the layouts from the standard theme; also the complete list of layouts is given in theme/standard/config.php - there is no way to add plugin layouts, the $PAGE->set_pagelayout() is used from core and plugin code, not from themes, so it is not possible to add new layouts at all (and never was)
  • name things moodle_* only if potential conflicts exist, everything plugin related should be named componentname_ (mod_ is usually an exception)- this was discussed several times before; renamed moodle_core_renderer' class to core_renderer, etc.
  • themes are now real plugins with capabilities, lang packs, upgrade code, settings, upgrade code, etc. - it is not recommended to create new db table though

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->image_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. styles.php replaced by styles.css, supported in all plugin types - the PHP syntax is not needed anymore because images are specified using [[pix:component|dir/image]] syntax and we can also use custom css post-processors
  4. $CFG->pixpath replaced by $OUTPUT->image_url()
  5. CSS constants replaced by the admin theme settings
  6. separate IE6 and IE7 sheets - replaced by body class attributes
  7. 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 and upgrade current code. New useful pix folder and standard styles.css in all plugins. $OUTPUT->image_url() more flexible then old pixpath.
Theme designer Has to learn new theme API. Old advanced themes has to be completely redesigned. Has to understand YUI CSS foundation. They can finally override core and plugin images. Easier distribution of custom themes. New income opportunity. 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. Better performance and lower server load.
Retrieved from "https://docs.moodle.org/35/en/index.php?title=Development:Theme_changes_in_2.0&oldid=65108"
Powered by MediaWiki