2019-03-04T13:55:02Z

Basbrands: /* Using grunt to debug Sass compile issues */

== Key differences ==

=== Bootstrap version differences ===

The biggest difference between themes Bootstrapbase and Boost are the included [http://getbootstrap.com 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 ===

[http://lesscss.org/ LESS css] is used in Bootstrapbase, Boost uses [https://sass-lang.com/ 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; [https://css-tricks.com/sass-vs-less/ css-tricks] has more information on these differences. The npm package [https://www.npmjs.com/package/less2sass less2sass] can be helpful when migrating your less files.

LESS css is compiled using a core [https://docs.moodle.org/dev/Grunt grunt] task and stored in theme/bootstrapbase/style/moodle.css. Child themes need to specify additional stylesheets using the
<code php>
$THEME->sheets = []
</code>
array or use
<code php>
$THEME->lessfile = ''
</code>
to use the core [https://github.com/oyejorge/LESS.php LESScss] library

Sass css is compiled using a core [http://leafo.github.io/scssphp scssphp] Library for theme Boost and child themes if
<code php>
$THEME->scss = ''
</code>
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 [https://docs.moodle.org/dev/Boost_Presets Boost Presets]. For information on advanced usage of Sass css see the [https://docs.moodle.org/dev/SCSS SCSS] doc page.

=== Moodle templates differences ===

Theme Boost uses [https://docs.moodle.org/dev/Templates 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 [https://docs.moodle.org/dev/Themes_overview#Appendix_A Themes Overview] doc page.

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

<code php>
$THEME->lessfile = 'moodle';
$THEME->lessvariablescallback = 'theme_more_less_variables';
$THEME->extralesscallback = 'theme_more_extra_less';
$THEME->doctype = 'html5';
</code>

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

<code php>
$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;
</code>

== 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 [https://moodle.org/plugins/theme_elegance 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 .

<code php>
$THEME->scss = function($theme) {
return theme_elegance_get_main_scss_content($theme);
};
</code>
''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.

<code php>
$THEME->layouts['frontpage'] = [
'file' => 'frontpage.php',
'regions' => ['side-pre'],
'defaultregion' => 'side-pre',
'options' => ['nonavbar'],
];
</code>
''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

<code php>
/**
* 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>
''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

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

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

<code php>
echo $OUTPUT->render_from_template('theme_elegance/layout_frontpage', $templatecontext);
</code>
''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:

<code php>
$renderer = $PAGE->get_renderer('theme_elegance');
$carousel = new \theme_elegance\output\carousel();
$widgets = (object) [
'carousel' => $renderer->render($carousel)
];

$templatecontext = [
..
'widgets' => $widgets,
..
];
</code>
''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 Bootstrapbase theme css is written in the [http://lesscss.org/ LESS css extention language]. Some child themes of bootstrapbase use LESS to generate their stylesheets. Usually these files are stored in the less/ folder of the child theme.

The Boost theme css is written in the [https://sass-lang.com/ Sass css extention language]. A child theme can extend the Boost Sass files which are usually found in the sass/ folder of the child theme.

The LESS and Sass extention languages are different and not compatible, themes using less will have to migrate their stylesheets. This can be done manually or with the [https://www.npmjs.com/package/less2sass less2sass] tool to translate LESS files into Sass. This tool is a great start when migrating your LESS however, after running less2sass to migrate your stylesheets you will need to inspect them and fix them if needed.

<code css>
/* Icon styles */
// Size of big icons.
@icon-big-width: 64px;
@icon-big-height: 64px;

img.icon {
&.iconsize-big {
width: @icon-big-width;
height: @icon-big-height;
}
}

.groupinfobox {
.well;

}
</code>
''example less from theme/bootstrapbase/less/moodle/core.less''

<code css>
// Size of big icons.
$icon-big-width: 64px;
$icon-big-height: 64px;
.icon {
&.iconsize-big {
width: $icon-big-width;
height: $icon-big-height;
}
}
.groupinfobox {
@extend .card;
}
</code>
''example sass from theme/boost/scss/moodle_core.scss''

The [https://sass-lang.com/ Sass CSS] extension language is not that hard to learn. Make sure you have read [https://sass-lang.com/guide The Sass Basics] and understand how to define and override variables and use mixins.

When you start migrating your LESS file a good starting point is your theme variables.less. Usually child themes define a number of new variables and override some of the variables defined in theme/bootstrapbase/less/bootstrap/variables.less.
Your new variables will probably be okay when migrating to SASS. The overridden bootstrap variables will no longer be valid. So for each overridden variable try to find the new variables name in theme/boost/sass/bootstrap/_variables.scss.

<code css>
// Scaffolding
// -------------------------
@bodyBackground: @white;
@textColor: @grayDark;

// Links
// -------------------------
@linkColor: #08c;
@linkColorHover: darken(@linkColor, 15%);
</code>
''example variables from theme/bootstrapbase/less/bootstrap/variables.less''

<code css>
// Body
//
// Settings for the `<body>` element.

$body-bg: $white !default;
$body-color: $gray-900 !default;

// Links
//
// Style anchor elements.

$link-color: theme-color("primary") !default;
$link-decoration: none !default;
$link-hover-color: darken($link-color, 15%) !default;
$link-hover-decoration: underline !default;
</code>
''example variables form theme/boost/sass/bootstrap/_variables.scss''

=== Using Grunt to compile Sass ===

When you start creating your new Sass files debugging what happens in the Moodle core PHP Sass compiler can take a lot of time. The compiler is run using a caching mechanism and error reporting is poor, when a variable is misspelled the errors are send to your webserver logfiles.

To speed up development The [http://gruntjs.com/ Grunt] Javascript taskrunner that runs on [https://nodejs.org/en/ Node.js] can be very helpful. If you have not tried to get Grunt running for Moodle core tasks make sure you read the [https://docs.moodle.org/dev/Grunt Moodle Grunt] docs page for more info.

You can use Grunt to compile your Sass and check your Sass syntaxs. Once you have Grunt and Node.js up and running you can create your own Gruntfile.js and package.json file.

For theme Elegance these files are found in [https://github.com/bmbrands/moodle-theme_elegance/blob/MOODLE_36_STABLE/Gruntfile.js theme/elegance/Gruntfile.js] and [https://github.com/bmbrands/moodle-theme_elegance/blob/MOODLE_36_STABLE/postcss.js theme/elegance/package.json].

You can copy these into your theme folder and run the Node installer to retreive all Node dependancies.

<code bash>
> nmp install
</code>

Make sure you update the Gruntfile.js to reflect your configuration:

<code javascript>
sass: {
options: {
style: 'expanded'
},
dist: {
files: {
'style/elegance.css': 'scss/gruntcompile.scss'
}
}
},
</code>
''section of the Grunfile.js you will need to change''

Once all dependancies are installed you can run Grunt to watch your Sass files. Each time you make a change in any of the files the the Node compiler will run and create a new stylesheet in your theme's style/ folder

This stylesheet will not be served to the end user unless you change your theme configuration:

<code php>
$THEME->sheets = ['elegance'];

// Commented out to prevent PHP Sass compiling.
//$THEME->scss = function($theme) {
// return theme_elegance_get_main_scss_content($theme);
//};
</code>
''section of theme/elegance/config.php''

Moving your theme to use boost as a parent theme

2019-03-04T13:54:18Z

Basbrands:

Moving your theme to use boost as a parent theme

2019-03-04T12:41:05Z

Basbrands: /* Migrating your LESS files */

Moving your theme to use boost as a parent theme

2019-03-04T12:39:58Z

Basbrands: /* Migrating your LESS files */

== Key differences ==

=== Bootstrap version differences ===

The biggest difference between themes Bootstrapbase and Boost are the included [http://getbootstrap.com 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 ===

[http://lesscss.org/ LESS css] is used in Bootstrapbase, Boost uses [https://sass-lang.com/ 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; [https://css-tricks.com/sass-vs-less/ css-tricks] has more information on these differences. The npm package [https://www.npmjs.com/package/less2sass less2sass] can be helpful when migrating your less files.

LESS css is compiled using a core [https://docs.moodle.org/dev/Grunt grunt] task and stored in theme/bootstrapbase/style/moodle.css. Child themes need to specify additional stylesheets using the
<code php>
$THEME->sheets = []
</code>
array or use
<code php>
$THEME->lessfile = ''
</code>
to use the core [https://github.com/oyejorge/LESS.php LESScss] library

Sass css is compiled using a core [http://leafo.github.io/scssphp scssphp] Library for theme Boost and child themes if
<code php>
$THEME->scss = ''
</code>
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 [https://docs.moodle.org/dev/Boost_Presets Boost Presets]. For information on advanced usage of Sass css see the [https://docs.moodle.org/dev/SCSS SCSS] doc page.

=== Moodle templates differences ===

Theme Boost uses [https://docs.moodle.org/dev/Templates 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 [https://docs.moodle.org/dev/Themes_overview#Appendix_A Themes Overview] doc page.

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

<code php>
$THEME->lessfile = 'moodle';
$THEME->lessvariablescallback = 'theme_more_less_variables';
$THEME->extralesscallback = 'theme_more_extra_less';
$THEME->doctype = 'html5';
</code>

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

<code php>
$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;
</code>

== 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 [https://moodle.org/plugins/theme_elegance 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 .

<code php>
$THEME->scss = function($theme) {
return theme_elegance_get_main_scss_content($theme);
};
</code>
''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.

<code php>
$THEME->layouts['frontpage'] = [
'file' => 'frontpage.php',
'regions' => ['side-pre'],
'defaultregion' => 'side-pre',
'options' => ['nonavbar'],
];
</code>
''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

<code php>
/**
* 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>
''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

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

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

<code php>
echo $OUTPUT->render_from_template('theme_elegance/layout_frontpage', $templatecontext);
</code>
''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:

<code php>
$renderer = $PAGE->get_renderer('theme_elegance');
$carousel = new \theme_elegance\output\carousel();
$widgets = (object) [
'carousel' => $renderer->render($carousel)
];

$templatecontext = [
..
'widgets' => $widgets,
..
];
</code>
''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 Bootstrapbase theme css is written in the [http://lesscss.org/ LESS css extention language]. Some child themes of bootstrapbase use LESS to generate their stylesheets. Usually these files are stored in the less/ folder of the child theme.

The Boost theme css is written in the [https://sass-lang.com/ Sass css extention language]. A child theme can extend the Boost Sass files which are usually found in the sass/ folder of the child theme.

The LESS and Sass extention languages are different and not compatible, themes using less will have to migrate their stylesheets. This can be done manually or with the [https://www.npmjs.com/package/less2sass less2sass] tool to translate LESS files into Sass. This tool is a great start when migrating your LESS however, after running less2sass to migrate your stylesheets you will need to inspect them and fix them if needed.

<code css>
/* Icon styles */
// Size of big icons.
@icon-big-width: 64px;
@icon-big-height: 64px;

img.icon {
&.iconsize-big {
width: @icon-big-width;
height: @icon-big-height;
}
}

.groupinfobox {
.well;

}
</code>
''example less from theme/bootstrapbase/less/moodle/core.less''

<code css>
// Size of big icons.
$icon-big-width: 64px;
$icon-big-height: 64px;
.icon {
&.iconsize-big {
width: $icon-big-width;
height: $icon-big-height;
}
}
.groupinfobox {
@extend .card;
}
</code>
''example sass from theme/boost/scss/moodle_core.scss''

The [https://sass-lang.com/ Sass CSS] extension language is not that hard to learn. Make sure you have read [https://sass-lang.com/guide The Sass Basics] and understand how to define and override variables and use mixins.

When you start migrating your LESS file a good starting point is your theme variables.less. Usually child themes define a number of new variables and override some of the variables defined in theme/bootstrapbase/less/bootstrap/variables.less.
Your new variables will probably be okay when migrating to SASS. The overridden bootstrap variables will no longer be valid. So for each overridden variable try to find the new variables name in theme/boost/sass/bootstrap/_variables.scss.

<code css>
// Scaffolding
// -------------------------
@bodyBackground: @white;
@textColor: @grayDark;

// Links
// -------------------------
@linkColor: #08c;
@linkColorHover: darken(@linkColor, 15%);
</code>
''example variables from theme/bootstrapbase/less/bootstrap/variables.less''

<code css>
// Body
//
// Settings for the `<body>` element.

$body-bg: $white !default;
$body-color: $gray-900 !default;

// Links
//
// Style anchor elements.

$link-color: theme-color("primary") !default;
$link-decoration: none !default;
$link-hover-color: darken($link-color, 15%) !default;
$link-hover-decoration: underline !default;
</code>
''example variables form theme/boost/sass/bootstrap/_variables.scss''

Moving your theme to use boost as a parent theme

2019-03-04T12:38:39Z

Basbrands: /* Migrating your LESS files */

== Key differences ==

=== Bootstrap version differences ===

The biggest difference between themes Bootstrapbase and Boost are the included [http://getbootstrap.com 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 ===

[http://lesscss.org/ LESS css] is used in Bootstrapbase, Boost uses [https://sass-lang.com/ 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; [https://css-tricks.com/sass-vs-less/ css-tricks] has more information on these differences. The npm package [https://www.npmjs.com/package/less2sass less2sass] can be helpful when migrating your less files.

LESS css is compiled using a core [https://docs.moodle.org/dev/Grunt grunt] task and stored in theme/bootstrapbase/style/moodle.css. Child themes need to specify additional stylesheets using the
<code php>
$THEME->sheets = []
</code>
array or use
<code php>
$THEME->lessfile = ''
</code>
to use the core [https://github.com/oyejorge/LESS.php LESScss] library

Sass css is compiled using a core [http://leafo.github.io/scssphp scssphp] Library for theme Boost and child themes if
<code php>
$THEME->scss = ''
</code>
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 [https://docs.moodle.org/dev/Boost_Presets Boost Presets]. For information on advanced usage of Sass css see the [https://docs.moodle.org/dev/SCSS SCSS] doc page.

=== Moodle templates differences ===

Theme Boost uses [https://docs.moodle.org/dev/Templates 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 [https://docs.moodle.org/dev/Themes_overview#Appendix_A Themes Overview] doc page.

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

<code php>
$THEME->lessfile = 'moodle';
$THEME->lessvariablescallback = 'theme_more_less_variables';
$THEME->extralesscallback = 'theme_more_extra_less';
$THEME->doctype = 'html5';
</code>

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

<code php>
$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;
</code>

== 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 [https://moodle.org/plugins/theme_elegance 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 .

<code php>
$THEME->scss = function($theme) {
return theme_elegance_get_main_scss_content($theme);
};
</code>
''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.

<code php>
$THEME->layouts['frontpage'] = [
'file' => 'frontpage.php',
'regions' => ['side-pre'],
'defaultregion' => 'side-pre',
'options' => ['nonavbar'],
];
</code>
''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

<code php>
/**
* 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>
''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

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

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

<code php>
echo $OUTPUT->render_from_template('theme_elegance/layout_frontpage', $templatecontext);
</code>
''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:

<code php>
$renderer = $PAGE->get_renderer('theme_elegance');
$carousel = new \theme_elegance\output\carousel();
$widgets = (object) [
'carousel' => $renderer->render($carousel)
];

$templatecontext = [
..
'widgets' => $widgets,
..
];
</code>
''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 Bootstrapbase theme css is written in the [http://lesscss.org/ LESS css extention language]. Some child themes of bootstrapbase use LESS to generate their stylesheets. Usually these files are stored in the less/ folder of the child theme.

The Boost theme css is written in the [https://sass-lang.com/ Sass css extention language]. A child theme can extend the Boost Sass files which are usually found in the sass/ folder of the child theme.

The LESS and Sass extention languages are different and not compatible, themes using less will have to migrate their stylesheets. This can be done manually or with the [https://www.npmjs.com/package/less2sass less2sass] tool to translate LESS files into Sass. This tool is a great start when migrating your LESS however, after running less2sass to migrate your stylesheets you will need to inspect them and fix them if needed.

<code css>
/* Icon styles */
// Size of big icons.
@icon-big-width: 64px;
@icon-big-height: 64px;

img.icon {
&.iconsize-big {
width: @icon-big-width;
height: @icon-big-height;
}
}

.groupinfobox {
.well;

}
</code>
_example less from theme/bootstrapbase/less/moodle/core.less_

<code css>
// Size of big icons.
$icon-big-width: 64px;
$icon-big-height: 64px;
.icon {
&.iconsize-big {
width: $icon-big-width;
height: $icon-big-height;
}
}
.groupinfobox {
@extend .card;
}
</code>
_example sass from theme/boost/scss/moodle_core.scss_

The [https://sass-lang.com/ Sass CSS] extension language is not that hard to learn. Make sure you have read [https://sass-lang.com/guide The Sass Basics] and understand how to define and override variables and use mixins.

When you start migrating your LESS file a good starting point is your theme variables.less. Usually child themes define a number of new variables and override some of the variables defined in theme/bootstrapbase/less/bootstrap/variables.less.
Your new variables will probably be okay when migrating to SASS. The overridden bootstrap variables will no longer be valid. So for each overridden variable try to find the new variables name in theme/boost/sass/bootstrap/_variables.scss.

<code css>
// Scaffolding
// -------------------------
@bodyBackground: @white;
@textColor: @grayDark;

// Links
// -------------------------
@linkColor: #08c;
@linkColorHover: darken(@linkColor, 15%);
</code>
_example variables from theme/bootstrapbase/less/bootstrap/variables.less_

<code css>
// Body
//
// Settings for the `<body>` element.

$body-bg: $white !default;
$body-color: $gray-900 !default;

// Links
//
// Style anchor elements.

$link-color: theme-color("primary") !default;
$link-decoration: none !default;
$link-hover-color: darken($link-color, 15%) !default;
$link-hover-decoration: underline !default;
</code>
_example variables form theme/boost/sass/bootstrap/_variables.scss_

Moving your theme to use boost as a parent theme

2019-03-01T07:09:26Z

Basbrands: /* Renderers differences */

2018-06-18T14:30:14Z

Basbrands: /* Changed templates */

The Boost theme for Moodle 3.5 has been upgraded to use the upstream [Bootstrap 4|https://getbootstrap.com/docs/4.0/getting-started/introduction/] libraries. This affects Boost child themes in a number of ways:

== Changes in presets ==

The structure of [Boost presets|https://docs.moodle.org/dev/Boost_Presets] have changed, In versions up to Moodle 3.4 all Sass files were included using one single line for importing:

<code>
// Import Core moodle CSS.
@import "moodle";
</code>

The import has now been split into 3 separate files:

<code>
// Import FontAwesome.
@import "fontawesome";

// Import All of Bootstrap.
@import "bootstrap";

// Import Core moodle CSS.
@import "moodle";
</code>

== Changes in Bootstrap ==

Bootstrap 4 Stable includes major changes compared to the Bootstrap 4 Alpha library used in Boost for Moodle 3.4 and older releases. Changes that affect Moodle most are:

=== Flex ===
# Switch to using [flex|https://getbootstrap.com/docs/4.0/utilities/flex/] positioning. This is used a lot in grids and form elements.
Changes in variable names

=== JavaScript ===
The Boost javascript has been updated to use the 4.0 Bootstrap JavaScript, this includes using the [Popper|https://popper.js.org] library for positioning Modals and Tooltips.

=== Sass variables ===
A number of SASS variables are no longer available in Bootstrap 4 Stable. Some of these variables were widely used in Core SASS and potentially in child themes. Some examples of these are:

<pre>
$font-size-root
$brand-primary
$spacer
$gray-dark
$state-success-text
</pre>

The variables and some utility classes used in Core SASS and HTML can still be used because of the Bootstrap 4 compatibility SASS file in theme/boost/scss/moodle/bs4alphacompat.scss.

=== Bootstrap utility classes ===

m-t-* and other spacing utilities should be replaced with mt-*.

m-t-1 is now mt-3
m-t-2 is now mt-4
m-t-3 is now mt-5

A more detailed description of using spacing classes can be found on the [Bootstrap spacing utilities|https://getbootstrap.com/docs/4.0/utilities/spacing/] page

The hidden-md-up and related classes have been removed from upstream Bootstrap, rather than using explicit hidden-* classes, you hide an element by simply hiding it at that screen size using d-sm-none. More info on the [Bootstrap utilities|https://getbootstrap.com/docs/4.0/migration/#utilities] page

=== New grid breakpoints ===

The Boost grid breakpoints are
<pre>
.col-* <576px
.col-sm-* >= 576px
.col-md-* >= 768px
.col-lg-* >= 992px
.col-xl-* >= 1200px
</pre>

All usage of '*-xs-*' have been dropped. What used to be col-xs-6 should now be written as col-6.

*-md-* has become *-lg-*, and *-lg-* has become *-xl-*.

=== Typography ===

Boostrap 4 uses a native font stack that selects the best font-family for each OS and device. For font sizing the browser default root font-size (typically 16px) is used. this variable can be changed using the variable '$font-size-base'.
In the default Boost preset we use: "0.9375rem" which computes to 15px on most browser.

== Commonly used utility classes ==

Bootstrap 4 offers a wide range of [utility/helper classes|https://getbootstrap.com/docs/4.0/utilities/borders/] to quickly style elements without using any CSS code. Using these classes in your mustache templates has preference over writing custom CSS.

An example of such a utility class is the [color|https://getbootstrap.com/docs/4.0/utilities/colors/] utility class.

the .text-success class colors text green (#5cb85c) in theme Boost based on the default Boost preset using Sass variable

/theme/boost/scss/preset/default.scss
<pre>
$green: #5cb85c !default;
</pre>

Using the [color|https://getbootstrap.com/docs/4.0/utilities/colors/] utility class allows you to change color based on preset variables instead of hardcoding the css in your theme.

== Template changes ==

=== Changed templates ===
New template: theme/boost/templates/head.mustache

This is the page header:
<pre>
<html>
<head>...
</head>
</pre>

New template: theme/boost/templates/navbar.mustache

This is the fixed navbar at the top of the page containing the nav drawer toggle, brand, custom menus and user menu. In Boost for Moodle 3.4 and earlier this file was named header.mustache

Changed template: theme/boost/templates/header.mustache

This is the area for the page, the page breadcrumb and the section navigation dropdown.

New template: theme/boost/templates/footer.mustache

This is the page footer included in the main mustache template columns2.mustache

=== Template updates ===
Boost for Moodle 3.5 templates have been updated to use new Bootstrap utility classes for positioning and styling. Examples of these utility classes can be found in theme/boost/templates/core_form/element-duration-inline.mustache. In this template the bootstrap helper utilities for pacing and positioning added were:

<pre>
<div class="d-flex ml-1">
</pre>

d-flex adds this css property display: flex;

ml-1 adds margin-left 0.25rem;

Updating a boost based theme

2018-06-18T14:27:39Z

Basbrands: /* Changed templates */

The Boost theme for Moodle 3.5 has been upgraded to use the upstream [Bootstrap 4|https://getbootstrap.com/docs/4.0/getting-started/introduction/] libraries. This affects Boost child themes in a number of ways:

== Changes in presets ==

The structure of [Boost presets|https://docs.moodle.org/dev/Boost_Presets] have changed, In versions up to Moodle 3.4 all Sass files were included using one single line for importing:

<code>
// Import Core moodle CSS.
@import "moodle";
</code>

The import has now been split into 3 separate files:

<code>
// Import FontAwesome.
@import "fontawesome";

// Import All of Bootstrap.
@import "bootstrap";

// Import Core moodle CSS.
@import "moodle";
</code>

== Changes in Bootstrap ==

Bootstrap 4 Stable includes major changes compared to the Bootstrap 4 Alpha library used in Boost for Moodle 3.4 and older releases. Changes that affect Moodle most are:

=== Flex ===
# Switch to using [flex|https://getbootstrap.com/docs/4.0/utilities/flex/] positioning. This is used a lot in grids and form elements.
Changes in variable names

=== JavaScript ===
The Boost javascript has been updated to use the 4.0 Bootstrap JavaScript, this includes using the [Popper|https://popper.js.org] library for positioning Modals and Tooltips.

=== Sass variables ===
A number of SASS variables are no longer available in Bootstrap 4 Stable. Some of these variables were widely used in Core SASS and potentially in child themes. Some examples of these are:

<pre>
$font-size-root
$brand-primary
$spacer
$gray-dark
$state-success-text
</pre>

The variables and some utility classes used in Core SASS and HTML can still be used because of the Bootstrap 4 compatibility SASS file in theme/boost/scss/moodle/bs4alphacompat.scss.

=== Bootstrap utility classes ===

m-t-* and other spacing utilities should be replaced with mt-*.

m-t-1 is now mt-3
m-t-2 is now mt-4
m-t-3 is now mt-5

A more detailed description of using spacing classes can be found on the [Bootstrap spacing utilities|https://getbootstrap.com/docs/4.0/utilities/spacing/] page

The hidden-md-up and related classes have been removed from upstream Bootstrap, rather than using explicit hidden-* classes, you hide an element by simply hiding it at that screen size using d-sm-none. More info on the [Bootstrap utilities|https://getbootstrap.com/docs/4.0/migration/#utilities] page

=== New grid breakpoints ===

The Boost grid breakpoints are
<pre>
.col-* <576px
.col-sm-* >= 576px
.col-md-* >= 768px
.col-lg-* >= 992px
.col-xl-* >= 1200px
</pre>

All usage of '*-xs-*' have been dropped. What used to be col-xs-6 should now be written as col-6.

*-md-* has become *-lg-*, and *-lg-* has become *-xl-*.

=== Typography ===

Boostrap 4 uses a native font stack that selects the best font-family for each OS and device. For font sizing the browser default root font-size (typically 16px) is used. this variable can be changed using the variable '$font-size-base'.
In the default Boost preset we use: "0.9375rem" which computes to 15px on most browser.

== Commonly used utility classes ==

Bootstrap 4 offers a wide range of [utility/helper classes|https://getbootstrap.com/docs/4.0/utilities/borders/] to quickly style elements without using any CSS code. Using these classes in your mustache templates has preference over writing custom CSS.

An example of such a utility class is the [color|https://getbootstrap.com/docs/4.0/utilities/colors/] utility class.

the .text-success class colors text green (#5cb85c) in theme Boost based on the default Boost preset using Sass variable

/theme/boost/scss/preset/default.scss
<pre>
$green: #5cb85c !default;
</pre>

Using the [color|https://getbootstrap.com/docs/4.0/utilities/colors/] utility class allows you to change color based on preset variables instead of hardcoding the css in your theme.

== Template changes ==

=== Changed templates ===
New template: theme/boost/templates/head.mustache

This is the page header:
<pre>
<html>
<head>...
</head>
</pre>

New template: theme/boost/templates/navbar.mustache

This is the fixed navbar at the top of the page containing the nav drawer toggle, brand, custom menus and user menu. In Boost for Moodle 3.4 and earlier this file was named header.mustache

Changed template: theme/boost/templates/header.mustache

=== Template updates ===
Boost for Moodle 3.5 templates have been updated to use new Bootstrap utility classes for positioning and styling. Examples of these utility classes can be found in theme/boost/templates/core_form/element-duration-inline.mustache. In this template the bootstrap helper utilities for pacing and positioning added were:

<pre>
<div class="d-flex ml-1">
</pre>

d-flex adds this css property display: flex;

ml-1 adds margin-left 0.25rem;

Updating a boost based theme

2018-06-18T14:25:33Z

Basbrands: /* Template updates */

The Boost theme for Moodle 3.5 has been upgraded to use the upstream [Bootstrap 4|https://getbootstrap.com/docs/4.0/getting-started/introduction/] libraries. This affects Boost child themes in a number of ways:

== Changes in presets ==

The structure of [Boost presets|https://docs.moodle.org/dev/Boost_Presets] have changed, In versions up to Moodle 3.4 all Sass files were included using one single line for importing:

<code>
// Import Core moodle CSS.
@import "moodle";
</code>

The import has now been split into 3 separate files:

<code>
// Import FontAwesome.
@import "fontawesome";

// Import All of Bootstrap.
@import "bootstrap";

// Import Core moodle CSS.
@import "moodle";
</code>

== Changes in Bootstrap ==

Bootstrap 4 Stable includes major changes compared to the Bootstrap 4 Alpha library used in Boost for Moodle 3.4 and older releases. Changes that affect Moodle most are:

=== Flex ===
# Switch to using [flex|https://getbootstrap.com/docs/4.0/utilities/flex/] positioning. This is used a lot in grids and form elements.
Changes in variable names

=== JavaScript ===
The Boost javascript has been updated to use the 4.0 Bootstrap JavaScript, this includes using the [Popper|https://popper.js.org] library for positioning Modals and Tooltips.

=== Sass variables ===
A number of SASS variables are no longer available in Bootstrap 4 Stable. Some of these variables were widely used in Core SASS and potentially in child themes. Some examples of these are:

<pre>
$font-size-root
$brand-primary
$spacer
$gray-dark
$state-success-text
</pre>

The variables and some utility classes used in Core SASS and HTML can still be used because of the Bootstrap 4 compatibility SASS file in theme/boost/scss/moodle/bs4alphacompat.scss.

=== Bootstrap utility classes ===

m-t-* and other spacing utilities should be replaced with mt-*.

m-t-1 is now mt-3
m-t-2 is now mt-4
m-t-3 is now mt-5

A more detailed description of using spacing classes can be found on the [Bootstrap spacing utilities|https://getbootstrap.com/docs/4.0/utilities/spacing/] page

The hidden-md-up and related classes have been removed from upstream Bootstrap, rather than using explicit hidden-* classes, you hide an element by simply hiding it at that screen size using d-sm-none. More info on the [Bootstrap utilities|https://getbootstrap.com/docs/4.0/migration/#utilities] page

=== New grid breakpoints ===

The Boost grid breakpoints are
<pre>
.col-* <576px
.col-sm-* >= 576px
.col-md-* >= 768px
.col-lg-* >= 992px
.col-xl-* >= 1200px
</pre>

All usage of '*-xs-*' have been dropped. What used to be col-xs-6 should now be written as col-6.

*-md-* has become *-lg-*, and *-lg-* has become *-xl-*.

=== Typography ===

Boostrap 4 uses a native font stack that selects the best font-family for each OS and device. For font sizing the browser default root font-size (typically 16px) is used. this variable can be changed using the variable '$font-size-base'.
In the default Boost preset we use: "0.9375rem" which computes to 15px on most browser.

== Commonly used utility classes ==

Bootstrap 4 offers a wide range of [utility/helper classes|https://getbootstrap.com/docs/4.0/utilities/borders/] to quickly style elements without using any CSS code. Using these classes in your mustache templates has preference over writing custom CSS.

An example of such a utility class is the [color|https://getbootstrap.com/docs/4.0/utilities/colors/] utility class.

the .text-success class colors text green (#5cb85c) in theme Boost based on the default Boost preset using Sass variable

/theme/boost/scss/preset/default.scss
<pre>
$green: #5cb85c !default;
</pre>

Using the [color|https://getbootstrap.com/docs/4.0/utilities/colors/] utility class allows you to change color based on preset variables instead of hardcoding the css in your theme.

== Template changes ==

=== Changed templates ===
Added boost/templates/head.mustache

This template added the <html><head>...</head> part of your page

Added boost/templates/navbar.mustache

This template adds the fixed navbar at the top of the page containing the nav drawer toggle, brand, custom menus and user menu. In Boost for Moodle 3.4 and earlier this file was named header.mustache

Changed boost/templates/header.mustache

=== Template updates ===
Boost for Moodle 3.5 templates have been updated to use new Bootstrap utility classes for positioning and styling. Examples of these utility classes can be found in theme/boost/templates/core_form/element-duration-inline.mustache. In this template the bootstrap helper utilities for pacing and positioning added were:

<pre>
<div class="d-flex ml-1">
</pre>

d-flex adds this css property display: flex;

ml-1 adds margin-left 0.25rem;