Customising/Themes/1.2 to 1.9

Note: There are some changes in where theme files for plugins are stored in Mahara 1.10 and up. See Customising/Themes/1.10

From Mahara 1.2 to 1.9 onwards, Mahara reads theme configuration files from htdocs/theme/{$themename}/themeconfig.php.  Mahara 1.2 releases come with six themes installed.  If new theme directories are placed under htdocs/theme, with a themeconfig.php, they will appear for selection on the Site Options page in the Admin section.

Templates are stored in htdocs/theme/{$themename}/templates, stylesheets are stored in htdocs/theme/{$themename}/static/style, and images in htdocs/theme/{$themename}/static/images.

The directory structure under htdocs/theme/{$themename}/templates mostly mirrors the structure of the php pages on the site, so for example, the page template used on the page htdocs/admin/site/options.php is found in htdocs/theme/default/templates/admin/site/options.tpl.  However this is not a strict rule; some pages in different folders may share a template, and some templates don't belong to a particular page, but are included by other templates.

Plugin directories contain templates which are used only by that plugin.  For example, the "My Files" page is in the file artefact plugin at htdocs/artefact/file/index.php and its template is in htdocs/artefact/file/theme/default/index.tpl.

Unlike Mahara 1.1, plugins should contain their own css and images when those styles/images are used only within the plugin.

Inheritance

A theme may specify a parent theme in its themeconfig.php file. If it leaves this out, the special "Raw" theme will be its parent. Both the parent and child stylesheets will be served up (in that order, so the child will override the parent). Also, specific pages can require their own additional stylesheets, and in these cases the additional stylesheets from both the parent and child are served.

For example, the artefact/file plugin has its own extra stylesheets.  If a user's theme is "Default", which has a parent theme of "Raw", then the user will retrieve the following stylesheets on the My Files page:

theme/raw/static/style/style.css
theme/default/static/style/style.css
artefact/file/theme/raw/static/style/style.css
artefact/file/theme/default/static/style/style.css

This gives us lots of flexibility but unfortunately browsers can end up doing a lot of stylesheet requests this way.

Of the six pre-installed themes, the "Raw" theme is special and is used as the parent theme by all the others.  Because of this, we have been able to keep the majority of the layout in the Raw theme css, and the other themes' stylesheets are much smaller because they mostly just override colours.

The child themes specify their own images, but we have been able to implement them without overriding any of the templates. They are a good place to look when getting started with a new theme.

We recommend using "Raw" as a parent for all new themes.

Creating a new theme for Mahara 1.2

1. Create a new directory in the theme/ subdirectory (e.g. theme/ponies or similar)
2. Copy the themeconfig.php from the default theme directory to your new directory
3. Edit your themeconfig.php, and add a name for your theme in the $theme->displayname line.

From then on, you will have created a new theme that inherits from the raw theme. What this means is, when Mahara needs a theme file (image, CSS file or template), it will look for it in your theme's directory, and if it can't find it there it will use the one in raw/.

To override images, create a static/images directory under your theme directory. For example, to change the site logo, put a site-logo.png in theme/ponies/static/images, and this will change the site logo for the ponies theme.

You can do the same with static/style/*.css - those stylesheets will be included on the page after the parent theme's ones, so you just need to override rules you want to change.

You will probably also want to override some of the standard plugin stylesheets too.  For example, if you want to change the look of the forums, the stylesheet used by the raw theme is in interaction/forum/theme/raw/static/style/style.css.  To override these rules, you need to create new directories under interaction/forum/theme for your theme.  So if the directory you created in step 1 was theme/ponies/, you would create the set of directories interaction/forum/theme/ponies/static/style/ and add a style.css in there, with the styles needed to override those contained in interaction/forum/theme/raw/static/style/style.css.

We hope that in most cases, theme authors won't need to create new templates, or make copies of templates from the raw theme into their new themes; a lot of the work can be done just by overriding default styles in the new theme's stylesheets.

Dwoo

In Mahara 1.2, Mahara moved to using Dwoo as its backend templating engine, rather than Smarty.  Developers familiar with Smarty should also read Differences between Smarty and Dwoo

Local theme overrides

You can also place template files in your /local directory, and they will be placed in the template search path, and used if the current theme does not have a matching template. They should go under local/theme/templates/.