Customising/Themes/Migrating themes from 1.1 to 1.2

From Mahara Wiki
Jump to: navigation, search

In order to make themes more easily maintainable in the future we have made a lot of changes to the default templates, classes, ids, image filenames, and locations of stylesheets.

Custom themes that were written for Mahara 1.1 are unlikely to work with 1.2.  If you are planning to upgrade your custom-themed site from 1.1 to 1.2, and you want to keep using your custom theme after the upgrade, you will need to spend some time (at least a few hours) updating your theme and testing it with a Mahara 1.2 installation.  Ideally you should use a copy of your site (database and dataroot) which you have upgraded to 1.2 first, but you can also just unzip a copy your theme into a new 1.2 site for testing.

You should read the notes on 1.2 themes, Differences between Smarty and Dwoo and also take a look at the pre-installed themes that come with Mahara 1.2.

A few of the most obvious changes are listed below:

Configuration file

The filename has changed from theme//config.php to theme//themeconfig.php.

The theme name now goes beside $theme->displayname rather than $theme->name.

If your theme used "default" as a parent theme, you should consider changing this to "raw".  Mahara 1.2's raw theme contains all the important layout rules, and your theme will hopefully have to override fewer styles.  If on the other hand your theme is very similar to the old default theme, and you just want to try to get it working quickly, you may find it easier to leave the parent as "default".


In Mahara 1.2, the default theme has no templates!  Default inherits from raw, and the raw theme contains all the templates that were in 1.1's default theme.  However, they are obviously not exactly the same templates -- they have had classes and ids modified in order to try to reduce the size of the stylesheets, and many other things have changed to accommodate all the new features in 1.2.

If your theme overrides templates, then you might find it useful to get the differences (using 'diff') from the old Mahara 1.1 default templates to your theme's 1.1 templates.  Then you can look at each file that has differences, find the corresponding 1.2 raw theme template, and then re-apply your changes to a new copy of that raw template.


In 1.2, many rules have been moved out of the main stylesheet into smaller stylesheets specific to a plugin or section of the site.  The main stylesheet is still called style.css.  Rules used only in the admin section are now in admin.css, and rules used only the view editing and display pages are in views.css. Plugins sometimes specify their own rules too, inside the plugin directories in files like artefact/blog/theme/raw/static/style/style.css, interaction/forum/theme/raw/static/style/style.css.  If your theme overrides rules in these additional stylesheets, you should create a new additional css file for your theme, and override the rules in that file.

Many of the ids and classes used in the old default stylesheet have changed their names.  A partial list of old selectors from 1.1 and their approximate equivalents in 1.2 is listed here:

1.1                     1.2

 #topwrapper             #top-wrapper
 #loading_box            #loading-box
 #logo                   #site-logo

 #mainnav                #main-nav
 #subnav                 #sub-nav

 #mainwrapper            #main-wrapper

 #column-left            #main-column, .main-column
 #column-full            #main-column, .main-column
 .maincontent            #main-column-container

 .profile-tabs           .in-page-tabs
 #grouppage-tabs         .in-page-tabs
 .profile-fieldsets      .subpage
 #grouppage-container    .subpage
 #group-info             .group-info

 #column-right           #right-column, .sidebar
 #sb_profile             #sb-profile, .sideblock
 #sb_onlineusers         #sb-onlineusers, .sideblock

 #footerwrap             #footer-wrap
 #footer                 -

Simply doing a search and replace on your stylesheet to perform the changes listed above is a starting point, but it will not be enough to get your theme looking good.


Some of the images have changed default location.  For example, in the raw (and pre-installed) themes, logo.gif has become site-logo.png.  If your theme doesn't have its own header template, you will either need to change your header image to site-logo.png, or override the header template.

References to images in stylesheets should be updated to use the correct parent theme image (if for example the theme's parent has changed from default to raw), and there is no version of that image in the child theme's static/images directory, for example:

    background: url(../../../raw/static/images/btn_search_off.gif) no-repeat;

This should really only be necessary if your theme needs to use an image from the parent theme in a place where the parent theme doesn't use that image, or uses a different one.