Customising/Themes/15.10

The Mahara theme system had a complete overhaul in Mahara 15.10, to use the Bootstrap CSS framework. This resulted in some major changes that make Mahara 15.10 themes nearly incompatible with themes from Mahara 15.04 and earlier. The big differences are:

1. 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
2. The CSS stylings in the "raw" theme have completely changed
3. 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
4. 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

We haven't covered this in detail in the wiki yet, but the Mahara git repository itself now contains some theming instructions:

1. The "Readme.md" file in the htdocs/theme/ directory: https://git.mahara.org/mahara/mahara/blob/master/htdocs/theme/Readme.md
2. The "subthemestarter" sample theme to guide the creation of new themes: https://git.mahara.org/mahara/mahara/tree/master/htdocs/theme/subthemestarter
3. 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.

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