Customising/Themes/1.2 to 1.9
From Mahara Wiki
< Customising | ThemesRevision as of 18:54, 9 May 2011 by Brettwilkins (Created page with "Mahara 1.2 reads theme configuration files from <code>htdocs/theme//themeconfig.php</code>. Mahara 1.2 releases come with six themes installed. If new theme directories are p…")
Mahara 1.2 reads theme configuration files from
htdocs/theme//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//templates, stylesheets are stored in
htdocs/theme//static/style, and images in
The directory structure under
htdocs/theme//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
Unlike Mahara 1.1, plugins should contain their own css and images when those styles/images are used only within the plugin.
A theme must specify a parent theme in its themeconfig.php file. Both the parent and child stylesheets will be served up (in that order). 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
- Create a new directory in the theme/ subdirectory (e.g. theme/ponies or similar)
- Copy the
themeconfig.phpfrom the default theme directory to your new directory
- Edit your
themeconfig.php, and add a name for your theme in the
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
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
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.
Mahara 1.2 has moved to using Dwoo as its backend templating engine, rather than Smarty. Developers familiar with Smarty should also read Differences between Smarty and Dwoo