Customising/Themes/19.04

Upgrade to Bootstrap 4

For Mahara 19.04, Mahara is switching to Bootstrap 4, the latest iteration of the popular CSS framework that we've used in Mahara since the October 2015 version, Mahara 15.10.

The Bootstrap team made far-reaching changes in the framework that impact everyone who is switching. In this guide, we want to provide you with useful information to make the transition from Bootstrap 3 to Bootstrap 4 as easy as possible. There are three common ways of creating a custom theme:

1. Copy one of the Mahara core themes and adjust logo, font, and colour values only.
2. Create your custom theme as a child theme of one of the built-in Mahara themes and change logo, font, and colour values only.
3. Create a more custom theme, making far-reaching changes.

Themes created via option 1 and 2 will be much easier to upgrade than themes created via option 3.

Option 1: Copy a theme

Note 1: While this option is the easiest as you have all files in your resulting theme, it is more difficult to maintain. When changes are made to the original theme that you copied, they will not make it into your theme. You will need to make those changes yourself. Only changes made directly in "Raw" are inherited.

Note 2: Do not change anything in the folder /theme/raw/lib.

If, on your current version of Mahara, you copied one of the existing Mahara core themes, i.e. Default, Modern, Ocean, or Primary School, and you only changed the logo, font, and made colour adjustments, you can follow these steps:

1. Upgrade to Mahara 19.04.
2. Copy the theme that you want to adjust.
3. In the /theme/<your theme folder>/themeconfig.php, choose a different "displayname".
4. Change the variable values in /theme/<your theme folder>/sass/utilities/_theme-variables.scss.
5. Change any values in /theme/<your theme folder>/sass/utilities/_custom-variables.scss that you want to adjust.
6. Review the variable values in /theme/<your theme folder>/sass/utilities/_bootstrap-variables.scss, in particular the link colour and the font if you wish to use a different one.
   • If you choose a different font, make sure that you upload all font files into the folder /theme/<your theme folder>/fonts and define the fonts in /theme/<your theme folder>/sass/typography/_fonts.scss.
   • If you want to replace all occurrences of the font, you can add the font to the list of fonts in the font variables $font-family-sans-serif or $font-family-serif in /theme/<your theme folder>/sass/utilities/_bootstrap-variables.scss.
   • If you only want to change the font on the dashboard for example, you'd change it in the specific scss file.
7. Make any other adjustments you see fit.
8. Compile the theme via Gulp.
9. Preview your theme and make changes where needed.

Option 2: Create a basic theme off any built-in Mahara theme with only colour changes

If you want to create a very basic theme along the lines of the configurable theme that is available for institutions, you can create a child theme off any built-in Mahara theme and change the colour values.

Note: Do not change anything in the folder /theme/raw/lib.

1. Upgrade to Mahara 19.04.
2. Copy the folder "subthemestarter" and give it a new name. Please do not use spaces and special characters in the folder name.
3. Open the file /theme/<your theme folder>/themeconfig.php and give your theme a human readable name in the variable "displayname". You can use spaces and special characters if needed.
4. If your parent theme is "Default", "Modern", Primary School", or "Ocean", uncomment the import lines under the comment "If your parent theme is a subtheme for example, Modern..." in the file /utilities/style.scss. If your parent theme is "Raw", you don't need to do that.
5. Make your changes in /theme/<your theme folder>/sass/utilities/_theme-variables.scss. You may need to add additional theme variables based on the parent theme:
   1. Open the parent theme's "_theme-variables.scss" file.
   2. Copy all the variables over into your file so you are not missing any.
   3. Change the variable colours.
6. You may need to copy the images folder from your parent theme.
   • If the images come from the scss folder, then you need to copy the images folder. That is the case for the "Default" theme, for example.
   • If the image is called in a template in the parent theme, then you do not have to copy the images folder. That is the case for the images on the dashboard of the "Primary School" theme.
7. If you want to use the font from the parent theme, copy the "fonts" folder into your child theme folder.
8. Compile the theme via Gulp.
9. Upload your logo through the Mahara site administration interface.
10. Preview your theme and make additional adjustments.

Note: You should be able to use this method if you had already created a theme that way in the past. Rather than copying your existing theme folder, only copy /theme/<your theme folder>/themeconfig.php and the variables in /theme/<your old theme folder>/sass/utilities/_theme-variables.scss.

If you want to make any other changes, you will need to make more adjustments and may need to copy more folders and files from the parent theme in order for styles to be used properly or be able to be overwritten. The subthemestarter theme kit provides a common basis shared by all themes. With your knowledge of SASS, you can make any sort of customisation to create a fully custom theme.