Customising/Themes/15.10

Most of the information in Customising/Themes/1.10 is still accurate for Mahara 15.10.

However, Mahara themes from 15.04 and earlier are likely to be incompatible with Mahara 15.10, because we moved to using the Bootstrap framework for our front-end code (CSS, Javascript, and HTML). As a result, nearly every template file and CSS file has been rewritten to a large degree.

Where to get 15.10 theming instructions

Until we update this wiki (feel free to help!), you will probably find the freshest information in these sources:

• The "Readme.md" file in the htdocs/theme/ directory: https://git.mahara.org/mahara/mahara/blob/master/htdocs/theme/Readme.md
• The "subthemestarter" sample theme to guide the creation of new themes: https://git.mahara.org/mahara/mahara/tree/master/htdocs/theme/subthemestarter
• The "styleguide.php" file, which contains snippets of HTML to be used in the creation of new Mahara pages. You can view this by logging into Mahara as an admin and going to /theme/styleguide.php in your Mahara site.

The main things that have changed in Mahara 15.10

As mentioned, nearly every template file, and virtually all of our CSS, was rewritten to a large degree. Specifically:

1. Now uses the Bootstrap framework, for CSS and some Javascript
2. Switched from static CSS to compiled SASS
   • So the Mahara git repository no longer stores static CSS files, but instead has SASS files that must be compiled into CSS
3. Nearly every template was rewritten, and class names and selectors were changed to be more compatible with Bootstrap
   • As a result, most CSS selectors from previous Mahara versions are no longer valid
4. Nearly every CSS class was rewritten
5. We reorganized theme files a little bit. Previously each theme could have a directory called "templates" to store Dwoo templates, "static" to store everything else (CSS, images, etc), and a directory for each plugintype to customize the appearance of plugins (artefact, blocktype, etc). New theme developers told us this was confusing, especially when we added SASS files (which are not static but compiled) into the "static" directory. So:
   • We moved all the theme files for plugins with a theme, into a directory called "plugintype"
     • So what used to be: htdocs/theme/raw/blocktype/creativecommons/...
     • Is now: htdocs/theme/raw/plugintype/blocktype/creativecommons/...
   • And we moved all the theme files that used to in the "static" directory of the theme, up into the root level of the theme
     • So what used to be: htdocs/theme/raw/static/images/logo.png
     • Is now: /htdocs/theme/raw/images/logo.png

15.04 migration help

Sorry, I haven't written any yet. ;) Some quick ideas:

Learn to love Bootstrap

Read the theme/Readme.md. Read some Bootstrap tutorials. Get gulp and npm running on your computer (it can be done on Windows!) or get some other system to compile our SASS (it's an open standard; patches welcome!). You may find that you much prefer the Bootstrap way over the old ad-hoc system.

Wait a while

We anticipated that upgrading to 15.10 might be a burden for some sites, especially if they have a heavily customized theme that will have to be completely rewritten for 15.10 and up. So, we declared 15.04 to be an extended support release, which a support lifetime of 30 months (until October 2017) instead of the normal 18 months, in order to give sites more time to upgrade. So if you can't yet upgrade your theme to 15.10, then it may be reasonable to wait a bit, and perhaps see if someone implements a 3rd party theme you'd like to use as a base.

Write a compatility theme

This is an idea that the Mahara core team considered implementing to provide backwards compatibility, but we decided it would be more effective to use our resources to improve the new theme, than to provide continuing support for the old system. However, it should be technically possible in Mahara 15.10.

The big breaker for 15.04 themes in 15.10 is that the "raw" theme in 15.10 contains major changes from 15.04, and all themes ultimately inherited from raw in 15.04 and earlier.

However, in 15.10 we made it possible for a theme to declare that it has no parent, thus making it an "alternate raw". So it may be possible to port the "raw" theme from 15.04 into 15.10 (call it "legacy") and then simply change your 15.04 themes to inherit from "legacy" instead of "raw".

Some changes would probably still be necessary, due to some pieces of Javascript requiring the 15.10 selectors, and some parts of Mahara's interface having been substantially rewritten (particularly the page permissions screen). However, if you absolutely hate bootstrap and strongly prefer the 15.04 theming system, this is an option. If you do implement this, please do share it with the community on the Mahara forums, and you will be hailed as a hero by people who love their 15.04 themes.