Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Updating a boost based theme: Difference between revisions

From MoodleDocs
No edit summary
m (Text replacement - "</code>" to "</syntaxhighlight>")
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Moodle 3.5}}
{{Template:Themes}}
The Boost theme for Moodle 3.5 has been upgraded to use the upstream [https://getbootstrap.com/docs/4.0/getting-started/introduction/ Bootstrap 4] libraries. Most Boost child themes will need some updates for Moodle 3.5, this document has been written to help you understand what has been changed. And keep in mind, after your theme has been updated you will have access to the full range of Bootstrap 4 components and utilities which allow you to create amazing designs and layouts.
The Boost theme for Moodle 3.5 has been upgraded to use the upstream [https://getbootstrap.com/docs/4.0/getting-started/introduction/ Bootstrap 4] libraries. Most Boost child themes will need some updates for Moodle 3.5, this document has been written to help you understand what has been changed. And keep in mind, after your theme has been updated you will have access to the full range of Bootstrap 4 components and utilities which allow you to create amazing designs and layouts.


If you were using a [https://docs.moodle.org/dev/Boost_Presets Boost preset] for styling the preset file will need some updates, see the changes in presets section below. Without these changes your Moodle install will break.
<p class="note">If you were using a [https://docs.moodle.org/dev/Boost_Presets Boost preset] for styling the preset file will need some updates, see the changes in presets section below. Without these changes your Moodle install will break.</p>


If your theme uses custom mustache templates or templates copied from Boost carefully compare your templates to the Moodle 3.5 boost templates. Especially the template columns2.mustach and the included navbar.mustache.  
If your theme uses custom mustache templates or templates copied from Boost carefully compare your templates to the Moodle 3.5 boost templates. Especially the template columns2.mustach and the included navbar.mustache.  
Line 9: Line 12:
The structure of [https://docs.moodle.org/dev/Boost_Presets Boost presets] have changed, In versions up to Moodle 3.4 all Sass files were included using one single line for importing:
The structure of [https://docs.moodle.org/dev/Boost_Presets Boost presets] have changed, In versions up to Moodle 3.4 all Sass files were included using one single line for importing:


<code>
<syntaxhighlight lang="php">
// Import Core moodle CSS.
// Import Core moodle CSS.
@import "moodle";
@import "moodle";
</code>
</syntaxhighlight>


The import has been split into 3 separate imports
The import has been split into 3 separate imports


<code>
<syntaxhighlight lang="php">
// Import FontAwesome.
// Import FontAwesome.
@import "fontawesome";
@import "fontawesome";
Line 25: Line 28:
// Import Core moodle CSS.
// Import Core moodle CSS.
@import "moodle";
@import "moodle";
</code>
</syntaxhighlight>


== Changes in Bootstrap ==
== Changes in Bootstrap ==
Line 36: Line 39:


=== JavaScript ===
=== JavaScript ===
The Boost javascript has been updated to use the 4.0 Bootstrap JavaScript. Bootstrap dropdowns, popovers and tooltips also depend on the [Popper|https://popper.js.org] library which has been added as a Moodle core library. Upstream Bootstrap JavaScript has been reformatted into AMD using the Babel.js library. For more info see the Boost readme_moodle.txt.
The Boost javascript has been updated to use the 4.0 Bootstrap JavaScript. Bootstrap dropdowns, popovers and tooltips also depend on the [https://popper.js.org Popper] library which has been added as a Moodle core library. Upstream Bootstrap JavaScript has been reformatted into AMD using the Babel.js library. For more info see the Boost readme_moodle.txt.


=== Sass variables ===
=== Sass variables ===
Line 63: Line 66:
Note: The "old" style utilities are still available in Boost and are provided by [https://github.com/moodle/moodle/blob/master/theme/boost/scss/moodle/bs4alphacompat.scss bs4alphacompat.scss].
Note: The "old" style utilities are still available in Boost and are provided by [https://github.com/moodle/moodle/blob/master/theme/boost/scss/moodle/bs4alphacompat.scss bs4alphacompat.scss].


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.  
A more detailed description of using spacing classes can be found on the [https://getbootstrap.com/docs/4.0/utilities/spacing/ Bootstrap spacing utilities] 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
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 [https://getbootstrap.com/docs/4.0/migration/#utilities Bootstrap utilities] page


=== New grid breakpoints ===
=== New grid breakpoints ===
Line 89: Line 92:
== Commonly used utility classes ==
== 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.  
Bootstrap 4 offers a wide range of [https://getbootstrap.com/docs/4.0/utilities/borders/ utility/helper classes] 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.
An example of such a utility class is the [https://getbootstrap.com/docs/4.0/utilities/colors/ color] utility class.


the .text-success class colors text green (#5cb85c) in theme Boost based on the default Boost preset using Sass variable
the .text-success class colors text green (#5cb85c) in theme Boost based on the default Boost preset using Sass variable
Line 116: Line 119:
New template: <b>theme/boost/templates/navbar.mustache</b>
New template: <b>theme/boost/templates/navbar.mustache</b>


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. The navbar color is styled using <code>navbar-light bg-white</code> css classes. Changing the navbar color works best when copying the navbar.mustache theme into your Boost child theme. Simply copy the template into this folder structure in your theme:
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. The navbar color is styled using <syntaxhighlight lang="php">navbar-light bg-white</syntaxhighlight> css classes. Changing the navbar color works best when copying the navbar.mustache theme into your Boost child theme. Simply copy the template into this folder structure in your theme:


<code>/templates/theme_boost/navbar.mustache</code>
<syntaxhighlight lang="php">/templates/theme_boost/navbar.mustache</syntaxhighlight>


And modify the mustache template to use <code>navbar-dark bg-primary</code> or any other background color.
And modify the mustache template to use <syntaxhighlight lang="php">navbar-dark bg-primary</syntaxhighlight> or any other background color.





Latest revision as of 20:27, 14 July 2021

Moodle 3.5


The Boost theme for Moodle 3.5 has been upgraded to use the upstream Bootstrap 4 libraries. Most Boost child themes will need some updates for Moodle 3.5, this document has been written to help you understand what has been changed. And keep in mind, after your theme has been updated you will have access to the full range of Bootstrap 4 components and utilities which allow you to create amazing designs and layouts.

If you were using a Boost preset for styling the preset file will need some updates, see the changes in presets section below. Without these changes your Moodle install will break.

If your theme uses custom mustache templates or templates copied from Boost carefully compare your templates to the Moodle 3.5 boost templates. Especially the template columns2.mustach and the included navbar.mustache.

Changes in Boost presets

The structure of Boost presets have changed, In versions up to Moodle 3.4 all Sass files were included using one single line for importing:

// Import Core moodle CSS.
@import "moodle";

The import has been split into 3 separate imports

// Import FontAwesome.
@import "fontawesome";

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

// Import Core moodle CSS.
@import "moodle";

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. Most of these changes are documented in the Bootstrap migration doc. The changes that affect Moodle the most are listed below.

Flexbox

Bootstrap Layouts have switched to Flexbox display utilities. Flexbox is used in many places in Bootstrap including forms, grids and cards. Flexbox layout allows themers to have more control over the positioning of elements in a row or a column. A nice example of the power of Flexbox is the Bootstrap card decks. .

JavaScript

The Boost javascript has been updated to use the 4.0 Bootstrap JavaScript. Bootstrap dropdowns, popovers and tooltips also depend on the Popper library which has been added as a Moodle core library. Upstream Bootstrap JavaScript has been reformatted into AMD using the Babel.js library. For more info see the Boost readme_moodle.txt.

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:

$font-size-root
$brand-primary
$spacer
$gray-dark
$state-success-text

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 bs4alphacompat.scss. For more info on using these variables read the Bootstrap theming doc and the Boost presets doc.

Bootstrap utility classes

Utility classes can be used to modify web page elements without needing to make any CSS changes. Bootstrap provides a wide range of utility classes ready to use when writing your HTML. These classes are widely used in Moodle templates and renderers. With the upgrade to Bootstrap 4 stable the classnames for spacing have changed.

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

Note: The "old" style utilities are still available in Boost and are provided by bs4alphacompat.scss.

A more detailed description of using spacing classes can be found on the Bootstrap spacing utilities 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 page

New grid breakpoints

The Boost grid breakpoints are

.col-*  <576px
.col-sm-* >= 576px
.col-md-* >= 768px
.col-lg-* >= 992px
.col-xl-* >= 1200px

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 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 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

$green:   #5cb85c !default;

Using the color 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:

<html>
    <head>...
    </head>

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. The navbar color is styled using

navbar-light bg-white

css classes. Changing the navbar color works best when copying the navbar.mustache theme into your Boost child theme. Simply copy the template into this folder structure in your theme:

/templates/theme_boost/navbar.mustache

And modify the mustache template to use

navbar-dark bg-primary

or any other background color.


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

This is the area for the page, the page breadcrumb and the section navigation dropdown, this used to be the page navbar.


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:

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

d-flex adds this css property display: flex;

ml-1 adds margin-left 0.25rem;