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. Also, the Mahara git repository now stores SASS files that must be compiled into CSS; rather than storing the static CSS files themselves.

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://github.com/MaharaProject/mahara/blob/master/htdocs/theme/Readme.md
• The "subthemestarter" sample theme to guide the creation of new themes: https://github.com/MaharaProject/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.

How to compile the Mahara 15.10 themes

As mentioned, Mahara's git repository no longer contains compiled CSS files. Instead it contains SASS files, which are written in a language that compiles into CSS and allows various programmer tricks like variables, code re-use, etc. This means that our CSS is now a "build product", and it's best practice to exclude build products from your version control system (such as Git).

So in order to work on Mahara 15.10 themes, you'll need the SASS files, and you'll need to be able to compile them into CSS.

If you checked out Mahara from git then you will notice that you've got the SASS (specifically, .scss) files, but no CSS files. You'll just need to compile that SASS. The "theme/Readme.md" file has instructions on how to make this happen.

If you downloaded Mahara from Launchpad then you will notice you have a bunch of unreadable minified CSS files, and none of this SASS everyone's talking about. That's because the ZIP files on Launchpad are a packaged release which removes the files that are only needed during development, such as SCSS files and test scripts. You will need to either clone Mahara from git, or download an unpackaged zip of the git repository from here: https://git.mahara.org/mahara/mahara/tags

Debug your theme

Gulp Usage

• Running 'gulp' will behave the same as before this patch.
• Running 'gulp --production false' will compile the css with debug comments in place.

Make Usage

• Running 'make css' will behave as before.
• Running 'make css production=false' will compile the css with debug comments in place.

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 (aaronw (talk) 15:21, 4 December 2015 (NZDT)) haven't written any yet! And I honestly haven't done much work developing themes (we have a separate "front-end developers" team for that). But if you have recently migrated a theme from 15.04 to 15.10, please do share your advice here. In the meantime, I can suggest these options:

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, with 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 compatibility layer

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.