Moving your theme to use boost as a parent theme: Difference between revisions
No edit summary |
Bas Brands (talk | contribs) |
||
Line 35: | Line 35: | ||
=== Renderers differences === | === 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/ | 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 === | === Theme config differences === |
Revision as of 07:09, 1 March 2019
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