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
Line 29: Line 29:
== Changes in Bootstrap ==
== 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:
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 [https://getbootstrap.com/docs/4.0/migration/ Bootstrap migration doc]. The changes that affect Moodle the most are listed below.


=== Flex ===
=== Flexbox ===
Switch to using [flex|https://getbootstrap.com/docs/4.0/utilities/flex/] positioning. Flexbox css properties are used in many places in Bootstrap including form fields, grids and cards.  Using the Bootstrap flex utility classes allow theme developer to have more control over the alignment of elements in a grid.
Bootstrap Layouts have switched to [https://getbootstrap.com/docs/4.0/utilities/flex/ 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 [https://getbootstrap.com/docs/4.1/components/card/#card-decks card decks].
.


=== JavaScript ===
=== 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.
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.


=== Sass variables ===
=== Sass variables ===
Line 48: Line 49:
</pre>
</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.
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 [https://github.com/moodle/moodle/blob/master/theme/boost/scss/moodle/bs4alphacompat.scss bs4alphacompat.scss]. For more info on using these variables read the [https://getbootstrap.com/docs/4.1/getting-started/theming/ Bootstrap theming] doc and the [https://docs.moodle.org/dev/Boost_Presets Boost presets] doc.


=== Bootstrap utility classes ===
=== 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-* and other spacing utilities should be replaced with mt-*.
Line 58: Line 61:
m-t-3 is now mt-5
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
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.


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 [Bootstrap utilities|https://getbootstrap.com/docs/4.0/migration/#utilities] page

Revision as of 09:05, 19 June 2018

The Boost theme for Moodle 3.5 has been upgraded to use the upstream Bootstrap 4 libraries. This affects Boost child themes in a number of ways.

If you are using a Moodle preset 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 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|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.

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

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

$green:   #5cb85c !default;

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:

<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

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:

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

d-flex adds this css property display: flex;

ml-1 adds margin-left 0.25rem;