Customising/Themes/20.10

Updating a current Bootstrap 4 theme to 20.10

If your theme is older than 19.04, please follow the steps to update your theme to Bootstrap 4 first from https://wiki.mahara.org/wiki/Customising/Themes/19.04 Alternatively, you may wish to start from scratch, using one of the built-in themes as basis.

Creating a new theme

There are two common ways of creating a custom theme:

1. Copy one of the Mahara core themes (it will inherit the 'Raw' theme as parent by default), upload your own logo, and change variables only within _theme-variables.scss, _custom-variables.scss, and _bootstrap-variables.scss.
2. Create your custom theme as a child theme of one of the built-in Mahara themes (so the Mahara theme you choose will be the parent), change to your own logo, and make changes with variables within _theme-variables.scss, _custom-variables.scss, and _bootstrap-variables.scss.

From these two starting points, you can further customise your theme.

Option 1: Copy a theme

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.

1. Copy the theme and all files within its folder that you want to adjust.
2. In the /theme/<your theme folder>/themeconfig.php, choose a different 'displayname'.
3. Change the variable values in /theme/<your theme folder>/sass/utilities/_theme-variables.scss. These variables are the main colours of your theme.
4. Change any values in /theme/<your theme folder>/sass/utilities/_custom-variables.scss that you want to adjust. These variables are for elements that are easy to change and don't require fiddling.
5. Review the variable values in /theme/<your theme folder>/sass/utilities/_bootstrap-variables.scss. These are Bootstrap variables that the entire site utilises. So unless you know what you are doing, it is best to avoid making too many changes.
6. Upload your logo through the Mahara site administration interface or name your logo site-logo.svg / site-logo.png and put into your theme images folder. Note: You will also need a square site-logo-small.svg / site-logo-small.png for smaller screens.
7. Compile the theme via Gulp.
8. Preview your theme and make any other adjustments you see fit.

See the notes on further customisation of a theme below.

Option 2: Create a theme off any built-in Mahara theme

If you want to create a theme similar to a built-in Mahara theme but with different colours and minor adjustments, you can create a child theme off it and change the colour values.

1. Copy the folder 'subthemestarter' and give it a new name. Please do not use spaces and special characters in the folder name.
2. 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. That is the name you will see in Mahara itself when you select a theme.
3. If your parent theme is not 'Raw': In the file /utilities/style.scss, uncomment the lines under '** If your parent theme is a subtheme for example, Modern...' (lines 19, 20, 36, and 37) if your parent theme is anything other than 'Raw'. Change '<your parent theme name>' to your parent theme folder name.
4. 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 into your file so you are not missing any.
   3. Change the variable colours.
5. You may need to copy the images folder from your parent theme.
   1. 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.
   2. 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.
6. Upload your logo through the Mahara site administration interface or name your logo site-logo.svg / site-logo.png and put into your theme images folder. Note: You will also need a square site-logo-small.svg / site-logo-small.png for smaller screens.
7. Compile the theme via Gulp.
8. Preview your theme and make any other adjustments you see fit.

Further customise your theme

Add @import line

In /theme/<your theme folder>/sass/style.scss, uncomment or add the lines after the parent files are defined:

 @import "utilities/bootstrap-variables";
 @import "utilities/custom-variables";

This means you will be able to override your parent variables with your theme variables that you choose to put into these files within your theme.

Then uncomment or add the line after @import "../../raw/sass/style":

 @import "utilities/index";

And create a file _index.scss in the 'utilities' folder. In this file, you will need to @import any additional .scss files that you may add into your theme to override existing parent styles.

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

Rem/em not px

To ensure your theme is accessible, avoid using px in your theme, it would be best to use rem/em.

Fonts

If you choose to use a new 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.

Note: In 'Raw', headings are $font-family-serif and body text is $font-family-sans-serif. You can change that in the headings and body text variables as well.

Templates

If you need to add or change mark-ups, you can copy the relevant .tpl file from /raw/templates into your theme and make changes in that file. These will override what is in 'Raw'.

Note: This does make future theme updates harder because each template will need to be checked against 'Raw'’s template for new parts to copy over to your theme when it comes to upgrading.