Moving your theme to use boost as a parent theme

Key differences

Bootstrap version differences

The biggest difference between themes Bootstrapbase and Boost are the included Bootstrap libraries. Bootstrapbase uses Bootstrap version 2.3.3, Boost uses Bootstrap version 4.0.0 (at the time of writing this document).

CSS extension language differences

LESS css is used in Bootstrapbase, Boost uses Sass CSS.

LESS uses a different css syntax than Sass. The most obvious difference is the way variables are defined; LESS uses @, Sass uses $. There are many other differences between LESS and Sass; css-tricks has more information on these differences. The npm package less2sass can be helpful when migrating your less files.

LESS css is compiled using a core grunt task and stored in theme/bootstrapbase/style/moodle.css. Child themes need to specify additional stylesheets using the $THEME->sheets = [] array or use $THEME->lessfile = to use the core LESScss library

Sass css is compiled using a core scssphp Library for theme Boost and child themes if $THEME->scss = is used. The compiled css file served to the end user is stored in a Moodle cache and is regenerated each time theme caches are cleared. Using the core scssphp compiler allows for the usage of Boost Presets. For information on advanced usage of Sass css see the SCSS doc page.

Moodle templates differences

Theme Boost uses Templates to render the main layouts. For each of the layout files in theme/boost/layouts/ there is a corresponding layout file in theme/boost/templates.

The layout files found in theme Bootstrapbase are a combination of php and html.

Renderers differences

In theme Boost all overridden renderers can be found theme/boost/classes/output, in theme Bootstrapbase the overridden renderers are called in /theme/bootstrapbase/renderers.php.

Theme config differences

The theme configuration for Boost based themes do not differ much from Bootstrapbase based themes. For a full list of option is available in the Themes Overview doc page.

These configuration options only apply to theme Bootstrapbase and child themes:

$THEME->lessfile = 'moodle'; $THEME->lessvariablescallback = 'theme_more_less_variables'; $THEME->extralesscallback = 'theme_more_extra_less'; $THEME->doctype = 'html5';

These configuration options only apply to theme Boost and child themes:

$THEME->scss = function($theme) {

   return theme_boost_get_main_scss_content($theme);

}; $THEME->extrascsscallback = 'theme_boost_get_extra_scss'; $THEME->prescsscallback = 'theme_boost_get_pre_scss'; $THEME->precompiledcsscallback = 'theme_boost_get_precompiled_css'; $THEME->addblockposition = BLOCK_ADDBLOCK_POSITION_FLATNAV;

Upgrading a theme to use Boost as a parent theme.

There is no fit-for-all tutorial on upgrading your theme since themes can have lost of custom features. The steps specified here are the steps that were taken upgrading the community theme Elegance to use theme Boost as its parent and serve as an example.

Update the theme config

Most of the config file can remain the same. References to less files need to be removed, the theme scss content needs to be specified using a callback .

$THEME->scss = function($theme) {

   return theme_elegance_get_main_scss_content($theme);

}; code snippet from theme/elegance/config.php

In this example the theme was specialised in rendering custom widgets on the front page, so we only need to specify a different layout file for the front page.

$THEME->layouts['frontpage'] = [

       'file' => 'frontpage.php',
       'regions' => ['side-pre'],
       'defaultregion' => 'side-pre',
       'options' => ['nonavbar'],
   ];

code snippet from theme/elegance/config.php

Update the theme lib file

Add the get_main_scss_content callback function to your theme lib file.

The callback function will need to fetch the Sass files from your parent theme. Use this example when basing your theme of Boost

/**

* Returns the main SCSS content.
*
* @param theme_config $theme The theme config object.
* @return string
*/

function theme_elegance_get_main_scss_content($theme) {

   global $CFG;

   $scss = file_get_contents($CFG->dirroot . '/theme/elegance/scss/variables.scss');
   $scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/fontawesome.scss');
   $scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/bootstrap.scss');
   $scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/moodle.scss');
   $scss .= file_get_contents($CFG->dirroot . '/theme/elegance/scss/post.scss');

   return $scss;

} code snippet from theme/elegance/lib.php

Make sure your create these files when using the example above:

theme/elegance/scss/variables.scss
theme/elegance/scss/post.scss

Create your template and layout files

If your theme contains custom layouts it will need a template for each layout.

For theme elegance these layout files and templates were copied

cp theme/boost/layout/columns2.php theme/elegance/layout/frontpage.php cp theme/boost/templates/columns2.mustache theme/elegance/templates/layout_frontpage.mustache

in the new frontpage.php the reference to the template needs updating after copying these:

   echo $OUTPUT->render_from_template('theme_elegance/layout_frontpage', $templatecontext);

code snippet from theme/elegance/layout/frontpage.php

Now the layout file and the template file are in place custom widget / renderers can be added for the front page.

For theme elegance a carousel slideshow can be configured through the theme settings. The renderer for this carousel is called in theme/elegance/layout/frontpage.php:

$renderer = $PAGE->get_renderer('theme_elegance'); $carousel = new \theme_elegance\output\carousel(); $widgets = (object) [

   'carousel' => $renderer->render($carousel)

];
$templatecontext = [

   ..
   'widgets' => $widgets,
   ..

]; code snippet from theme/elegance/layout/frontpage.php

The carousel widget is passed on to the theme/elegance/template/layout_frontpage.mustache template

Migrating your LESS files

The Sass CSS extension language is not that hard to learn. Make sure you have read The Sass Basics and understand how to define and override variables and use mixins.

Less files can be translated with less2sass. Once you have translated your less files to SASS syntax you will need to inspect them to see if they still make sense.

If you have created the files scss/variables.scss and scss/post.scss you can used these files to include your translated sass files.

Copy paste variables into scss/variables.scss Include your translated files in scss/post.scss

Documentation