MoodleDocs - User contributions [en]

Creating a theme based on boost

2020-07-31T11:42:23Z

Meeth: Undo revision 57736 by Meeth (talk)

{{Moodle 3.2}}
{{Template:Themes}}

This is a tutorial for how to create a new theme in any version of Moodle from 3.2 and later.

Moodle 3.2 introduced a new core theme named "Boost" which is a great starting point for themers wanting to build a modern Moodle theme utilising all the latest features available to themes in Moodle. If you aren't sure where to start, then START HERE! :-)

== Getting started ==
What is a theme? A theme in Moodle is just another type of plugin that can be developed. Themes are responsible for setting up the structure of each page and have the ability to customise the output of any page in Moodle.

This tutorial is based on a working theme named "theme_photo" you can download it or view the source code for it here: https://github.com/damyon/moodle-theme_photo

=== Choosing a name ===
Your new theme will need a name. Try and think of something short and memorable - and make sure it is not a name that has already been used by someone else. A quick search on the moodle.org/plugins can save you a lot of work renaming things later.

Lets call our new example theme "photo" as we will add some settings to allow "photos" in various places in Moodle.

=== Starting files ===
As a plugin, themes must start with the basic structure of a plugin in Moodle. See https://docs.moodle.org/dev/Tutorial#The_skeleton_of_your_plugin for an overview of the files common to all plugins in Moodle.

Following this guide we can start creating our theme. First we create the folder for the new theme under "/theme/" folder in the Moodle root directory.

<code>
/theme/photo/
</code>

Now we need to add some standard plugin files to our theme. First is version.php

''/theme/photo/version.php''

<code php>

<?php
// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// This is the version of the plugin.
$plugin->version = '2016102100';

// This is the version of Moodle this plugin requires.
$plugin->requires = '2016070700';

// This is the component name of the plugin - it always starts with 'theme_'
// for themes and should be the same as the name of the folder.
$plugin->component = 'theme_photo';

// This is a list of plugins, this plugin depends on (and their versions).
$plugin->dependencies = [
'theme_boost' => '2016102100'
];

</code>

We also need a language file so that all our strings can be translated into different languages. The name of this file is the component name of our plugin and it sits in the lang/en/ folder for our plugin. We can include translations of our plugin, but we can also provide translations via the https://lang.moodle.org/ website once our plugin has been published to the plugins database at http://www.moodle.org/plugins/.

''/theme/photo/lang/en/theme_photo.php''

<code php>

<?php
// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// A description shown in the admin theme selector.
$string['choosereadme'] = 'Theme photo is a child theme of Boost. It adds the ability to upload background photos.';
// The name of our plugin.
$string['pluginname'] = 'Photo';
// We need to include a lang string for each block region.
$string['region-side-pre'] = 'Right';
</code>

=== Theme specific files ===
Theme plugins have a few more standard files they need to define.

Themes require a favicon file to show in the address bar. See [[http://docs.moodle.org/en/Favicon Favicon]].

''pix/favicon.ico''

(Image file not shown).

Themes also require an example screenshot to be displayed in the theme selector.

''pix/screenshot.jpg''

(Image file not shown).

Themes require a lib.php file. This file contains callbacks used by various API's in Moodle. Initially this file can be empty, but as we add features to our theme we will need to add some functions here.

''lib.php''
<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// We will add callbacks here as we add features to our theme.
</code>

Theme config goes in a config.php file. This is one of the most important files in our theme. Once we add this file we will be ready to test our theme for the first time.

''config.php''

<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// $THEME is defined before this page is included and we can define settings by adding properties to this global object.

// The first setting we need is the name of the theme. This should be the last part of the component name, and the same
// as the directory name for our theme.
$THEME->name = 'photo';

// This setting list the style sheets we want to include in our theme. Because we want to use SCSS instead of CSS - we won't
// list any style sheets. If we did we would list the name of a file in the /style/ folder for our theme without any css file
// extensions.
$THEME->sheets = [];

// This is a setting that can be used to provide some styling to the content in the TinyMCE text editor. This is no longer the
// default text editor and "Atto" does not need this setting so we won't provide anything. If we did it would work the same
// as the previous setting - listing a file in the /styles/ folder.
$THEME->editor_sheets = [];

// This is a critical setting. We want to inherit from theme_boost because it provides a great starting point for SCSS bootstrap4
// themes. We could add more than one parent here to inherit from multiple parents, and if we did they would be processed in
// order of importance (later themes overriding earlier ones). Things we will inherit from the parent theme include
// styles and mustache templates and some (not all) settings.
$THEME->parents = ['boost'];

// A dock is a way to take blocks out of the page and put them in a persistent floating area on the side of the page. Boost
// does not support a dock so we won't either - but look at bootstrapbase for an example of a theme with a dock.
$THEME->enable_dock = false;

// This is an old setting used to load specific CSS for some YUI JS. We don't need it in Boost based themes because Boost
// provides default styling for the YUI modules that we use. It is not recommended to use this setting anymore.
$THEME->yuicssmodules = array();

// Most themes will use this rendererfactory as this is the one that allows the theme to override any other renderer.
$THEME->rendererfactory = 'theme_overridden_renderer_factory';

// This is a list of blocks that are required to exist on all pages for this theme to function correctly. For example
// bootstrap base requires the settings and navigation blocks because otherwise there would be no way to navigate to all the
// pages in Moodle. Boost does not require these blocks because it provides other ways to navigate built into the theme.
$THEME->requiredblocks = '';

// This is a feature that tells the blocks library not to use the "Add a block" block. We don't want this in boost based themes because
// it forces a block region into the page when editing is enabled and it takes up too much room.
$THEME->addblockposition = BLOCK_ADDBLOCK_POSITION_FLATNAV;
</code>

=== Ready set go! ===
If you have been following along - now we are at the point where we can actually install and test our new theme. Try it now by visiting the admin notifications page to install the new plugin, and then choosing the new theme from the theme selector.

[[https://docs.moodle.org/en/Standard_themes#Theme_selector Theme selector]]

When you choose the new theme - you will find that it looks exactly the same as Boost. At this point with our minimal configuration - we are inheriting almost everything from our parent theme including styles and templates. You will notice though that we don't inherit the settings from our parent theme. If you choose a different preset in Boost - it is not applied in this child theme.

<div class="warningbox">
Note: make sure your config.php file contains $THEME->hidefromselector = false; (or at least set to false) or else, your theme wont show up in theme selector.
</div>

=== What if I want the settings too? ===

<div class="warningbox">
This section is included for completeness - but it is not recommended for themes to utilise settings from their parents. To find out how to duplicate the settings from the parent theme so they operate independently skip to [[#Duplicate the settings from Boost]].
</div>

If I want the settings from Boost to apply to my child theme as well I need to know a bit about how each of the settings in Boost is applied to make them work in my child theme.

'''Setting 1 - preset.'''

The "preset" file is the file that is used as the main file for scss compilation. In Boost this is controlled by the theme config value:

''theme_boost/config.php''
<code php>
$THEME->scss = function($theme) {
return theme_boost_get_main_scss_content($theme);
};
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');
} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_boost', 'preset', 0, '/', $filename))) {
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

return $scss;
}
</code>

What this function is doing is checking for a theme setting "preset" and either fetching the file from Moodles internal file storage, or from the /preset/ folder. The function then returns the contents of this file.

It does not automatically work for our child theme because we have no setting named "preset" in our child theme and this code is not searching the theme parents for the setting. If we wanted it to apply we could do this in our child theme:

''config.php''
<code php>
// This setting defines the main scss file for our theme to be compiled. We could set it to a static file in the scss folder or to a function which returns the SCSS based on theme settings.
$THEME->scss = function($theme) {

// We need to load the config for our parent theme because that is where the preset setting is defined.
$parentconfig = theme_config::load('boost');
// Call a function from our parent themes lib.php file to fetch the content of the themes main SCSS file based on it's own config, not ours.
return theme_boost_get_main_scss_content($parentconfig);
};
</code>

'''Settings 2+3 brandcolor + scsspre'''

The way these settings work is they generate a chunk of SCSS to be prepended to the main scss file. In boost they work like this:

''theme_boost/config.php''
<code php>
$THEME->prescsscallback = 'theme_boost_get_pre_scss';
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_pre_scss($theme) {
global $CFG;

$scss = '';
$configurable = [
// Config key => [variableName, ...].
'brandcolor' => ['brand-primary'],
];

// Prepend variables first.
foreach ($configurable as $configkey => $targets) {
$value = isset($theme->settings->{$configkey}) ? $theme->settings->{$configkey} : null;
if (empty($value)) {
continue;
}
array_map(function($target) use (&$scss, $value) {
$scss .= '$' . $target . ': ' . $value . ";\n";
}, (array) $targets);
}

// Prepend pre-scss.
if (!empty($theme->settings->scsspre)) {
$scss .= $theme->settings->scsspre;
}

return $scss;
}
</code>

What this code is doing is:
* looping over a list of theme settings that map to a SCSS variable and building some SCSS to initialise that variable from the setting. In Boost there is only one * brandprimary - but if we wanted to expose more bootstrap variables as theme settings we could use this function as a template in our child theme and add more settings to the $configurable array.
* Adding all of the raw SCSS from the scsspre theme setting
* Returning the whole thing as a string to be added before the main scss file.

If we want this code to work in our child theme, using the settings from Boost we could do this:

''config.php''
<code php>
// This is a function that returns some SCSS as a string to prepend to the main SCSS file.
$THEME->prescsscallback = 'theme_photo_get_pre_scss';
</code>

''lib.php''
<code php>
// Function to return the SCSS to prepend to our main SCSS for this theme.
// Note the function name starts with the component name because this is a global function and we don't want namespace clashes.
function theme_photo_get_pre_scss($theme) {
// Load the settings from the parent.
$theme = theme_config::load('boost');
// Call the parent themes get_pre_scss function.
return theme_boost_get_pre_scss($theme);
}
</code>

'''Setting 4 scss (post)'''

The final setting from Boost is a raw text field which adds SCSS to the end of the main SCSS file. This is a useful place to add style rules as they will override previously defined styles with the same specificity. It is applied in Boost by the following lines:

''theme_boost/config.php''
<code php>
$THEME->extrascsscallback = 'theme_boost_get_extra_scss';
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_extra_scss($theme) {
return !empty($theme->settings->scss) ? $theme->settings->scss : '';
}
</code>

This is just returning the value of the setting as a string.

To make this setting apply in our child theme too - we use similar code to the previous sections.

''config.php''
<code php>
// This is a function that returns some SCSS as a string to append to the main SCSS file.
$THEME->extrascsscallback = 'theme_photo_get_extra_scss';
</code>

''lib.php''
<code php>
// Function to return the SCSS to append to our main SCSS for this theme.
// Note the function name starts with the component name because this is a global function and we don't want namespace clashes.
function theme_photo_get_extra_scss($theme) {
// Load the settings from the parent.
$theme = theme_config::load('boost');
// Call the parent themes get_extra_scss function.
return theme_boost_get_extra_scss($theme);
}
</code>

=== Duplicate the settings from Boost ===

This is the recommended way to extend boost as your child theme will not be affected by changes to the Boost settings, and both themes can be in use with different settings applied.

All that needs to happen is to create theme settings in the child theme that match each of the settings in the parent theme. You will need to add matching language strings for each of these settings in the language file.

This example shows how to do it - We are re-using the nice looking theme_boost_admin_settingspage_tabs class from boost and creating duplicate versions of each of the settings.

''settings.php''

<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// This is used for performance, we don't need to know about these settings on every page in Moodle, only when
// we are looking at the admin settings pages.
if ($ADMIN->fulltree) {

// Boost provides a nice setting page which splits settings onto separate tabs. We want to use it here.
$settings = new theme_boost_admin_settingspage_tabs('themesettingphoto', get_string('configtitle', 'theme_photo'));

// Each page is a tab - the first is the "General" tab.
$page = new admin_settingpage('theme_photo_general', get_string('generalsettings', 'theme_photo'));

// Replicate the preset setting from boost.
$name = 'theme_photo/preset';
$title = get_string('preset', 'theme_photo');
$description = get_string('preset_desc', 'theme_photo');
$default = 'default.scss';

// We list files in our own file area to add to the drop down. We will provide our own function to
// load all the presets from the correct paths.
$context = context_system::instance();
$fs = get_file_storage();
$files = $fs->get_area_files($context->id, 'theme_photo', 'preset', 0, 'itemid, filepath, filename', false);

$choices = [];
foreach ($files as $file) {
$choices[$file->get_filename()] = $file->get_filename();
}
// These are the built in presets from Boost.
$choices['default.scss'] = 'default.scss';
$choices['plain.scss'] = 'plain.scss';

$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Preset files setting.
$name = 'theme_photo/presetfiles';
$title = get_string('presetfiles','theme_photo');
$description = get_string('presetfiles_desc', 'theme_photo');

$setting = new admin_setting_configstoredfile($name, $title, $description, 'preset', 0,
array('maxfiles' => 20, 'accepted_types' => array('.scss')));
$page->add($setting);

// Variable $brand-color.
// We use an empty default value because the default colour should come from the preset.
$name = 'theme_photo/brandcolor';
$title = get_string('brandcolor', 'theme_photo');
$description = get_string('brandcolor_desc', 'theme_photo');
$setting = new admin_setting_configcolourpicker($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Must add the page after definiting all the settings!
$settings->add($page);

// Advanced settings.
$page = new admin_settingpage('theme_photo_advanced', get_string('advancedsettings', 'theme_photo'));

// Raw SCSS to include before the content.
$setting = new admin_setting_configtextarea('theme_photo/scsspre',
get_string('rawscsspre', 'theme_photo'), get_string('rawscsspre_desc', 'theme_photo'), '', PARAM_RAW);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Raw SCSS to include after the content.
$setting = new admin_setting_configtextarea('theme_photo/scss', get_string('rawscss', 'theme_photo'),
get_string('rawscss_desc', 'theme_photo'), '', PARAM_RAW);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

$settings->add($page);
}
</code>

''lang/en/theme_photo.php''
<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();
// The name of the second tab in the theme settings.
$string['advancedsettings'] = 'Advanced settings';
// The brand colour setting.
$string['brandcolor'] = 'Brand colour';
// The brand colour setting description.
$string['brandcolor_desc'] = 'The accent colour.';
// A description shown in the admin theme selector.
$string['choosereadme'] = 'Theme photo is a child theme of Boost. It adds the ability to upload background photos.';
// Name of the settings pages.
$string['configtitle'] = 'Photo settings';
// Name of the first settings tab.
$string['generalsettings'] = 'General settings';
// The name of our plugin.
$string['pluginname'] = 'Photo';
// Preset files setting.
$string['presetfiles'] = 'Additional theme preset files';
// Preset files help text.
$string['presetfiles_desc'] = 'Preset files can be used to dramatically alter the appearance of the theme. See <a href=https://docs.moodle.org/dev/Boost_Presets>Boost presets</a> for information on creating and sharing your own preset files, and see the <a href=http://moodle.net/boost>Presets repository</a> for presets that others have shared.';
// Preset setting.
$string['preset'] = 'Theme preset';
// Preset help text.
$string['preset_desc'] = 'Pick a preset to broadly change the look of the theme.';
// Raw SCSS setting.
$string['rawscss'] = 'Raw SCSS';
// Raw SCSS setting help text.
$string['rawscss_desc'] = 'Use this field to provide SCSS or CSS code which will be injected at the end of the style sheet.';
// Raw initial SCSS setting.
$string['rawscsspre'] = 'Raw initial SCSS';
// Raw initial SCSS setting help text.
$string['rawscsspre_desc'] = 'In this field you can provide initialising SCSS code, it will be injected before everything else. Most of the time you will use this setting to define variables.';
// We need to include a lang string for each block region.
$string['region-side-pre'] = 'Right';
</code>

We aren't quite there yet as you will notice if you try and upload a preset file and then choose it. The "theme_boost_get_main_scss_content" function from Boost is expecting the preset files to be stored in a file area for theme_boost only. We need to add this function to our own theme and tweak it.

''config.php''
<code php>
// This is the function that returns the SCSS source for the main file in our theme. We override the boost version because
// we want to allow presets uploaded to our own theme file area to be selected in the preset list.
$THEME->scss = function($theme) {
return theme_photo_get_main_scss_content($theme);
};
</code>

''lib.php''
<code php>
function theme_photo_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');

} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_photo', 'preset', 0, '/', $filename))) {
// This preset file was fetched from the file area for theme_photo and not theme_boost (see the line above).
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

return $scss;
}
</code>

=== Stop and try it out ===
So now what is working and what isn't. Well - everything should be working and you should have a nice new theme extending boost with it's own settings pages. When Boost gets updates for bug fixes your new theme will inherit those fixes as it inherits all the SCSS and templates from theme boost. In addition your new theme will accept preset files and supports all the same features and settings as boost, ready to add more.

== Take it further ==
Now we have our very nice starting point we can start changing or adding features, customising templates and output or tweaking the SCSS.

=== Add some new settings ===

From this point in the tutorial we will start adding features to our theme to extend it and make it AWESOME!

Lets start with a new setting to set a background image on the login page. As you saw earlier, our theme defines it's list of settings in a file called settings.php. See [[Admin settings]] for more information about adding admin settings to any plugin. All of the different kinds of admin settings can be found in lib/adminlib.php. In our case we will want to add a setting which allows an admin to upload an image file. This is an "admin_setting_configstoredfile" and we add it to our theme by adding this code to the settings.php file (inside the "if ($ADMIN->fulltree) {" condition.

''settings.php''
<code php>
// Login page background setting.
// We use variables for readability.
$name = 'theme_photo/loginbackgroundimage';
$title = get_string('loginbackgroundimage', 'theme_photo');
$description = get_string('loginbackgroundimage_desc', 'theme_photo');
// This creates the new setting.
$setting = new admin_setting_configstoredfile($name, $title, $description, 'loginbackgroundimage');
// This means that theme caches will automatically be cleared when this setting is changed.
$setting->set_updatedcallback('theme_reset_all_caches');
// We always have to add the setting to a page for it to have any effect.
$page->add($setting);
</code>

We also need to add new lang strings to our language file.

"lang/en/theme_photo.php"
<code php>
// Background image for login page.
$string['loginbackgroundimage'] = 'Login page background image';
// Background image for login page.
$string['loginbackgroundimage_desc'] = 'An image that will be stretched to fill the background of the login page.';
</code>

Now we have a new setting that lets us upload a file - but it doesn't actually do anything yet. We need to update the theme to set this image background on the login page.

In order to change the SCSS for our theme we will add 2 additional SCSS files and include them before and after our main scss.

We already have a function in our lib.php file which fetches the main SCSS for our theme. This is a good point to include additional SCSS files. We can add 2 lines to the end of this function to achieve this.

''lib.php''
<code php>
function theme_photo_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');

} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_photo', 'preset', 0, '/', $filename))) {
// This preset file was fetched from the file area for theme_photo and not theme_boost (see the line above).
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

// Pre CSS - this is loaded AFTER any prescss from the setting but before the main scss.
$pre = file_get_contents($CFG->dirroot . '/theme/photo/scss/pre.scss');
// Post CSS - this is loaded AFTER the main scss but before the extra scss from the setting.
$post = file_get_contents($CFG->dirroot . '/theme/photo/scss/post.scss');

// Combine them together.
return $pre . "\n" . $scss . "\n" . $post;
}
</code>

''scss/pre.scss''
<code scss>
// Pre SCSS for the theme.
</code>

''scss/post.scss''
<code scss>
// Post SCSS for the theme.
</code>

==== Why do we use pre and post SCSS? ====
SCSS/SASS is a powerful language for creating CSS. It supports variables, functions, loops just like php. For lots of information and an introduction to SCSS read about [https://en.wikipedia.org/wiki/Sass_(stylesheet_language) Sass on wikipedia].

'''Pre SCSS'''

In Boost we use many variables when creating style rules.

When declaring a variable in SCSS - it is best practice to define it like this:
<code scss>
$mycoolcolour: #FF0 !default;
</code>

What this means is - if this variable is not defined already - set it to the hex value '#FF0';

So by setting this variable in some PRE scss we can override the default value of this variable everywhere it is used. Boost is built with the [https://v4-alpha.getbootstrap.com/ Bootstrap 4 (Alpha 4)] CSS Framework. This is a framework which uses SCSS to provide many extremely useful layouts and components which can be reused without adding specific CSS rules to style every page. Because bootstrap consistently uses variables we can customise many of these components easily by setting the value of the variables before we include the Bootstrap SCSS files.

Many variables are available in /theme/boost/scss/bootstrap/_variables.scss - as an example we can change the look of all buttons and input fields with this one variable:

<code scss>
$border-radius: 8px;
</code>

'''Post SCSS'''

Post SCSS is useful for defining full CSS rules. Because they are included last, they override any previous matching selector with the same [https://en.wikipedia.org/wiki/Cascading_Style_Sheets#Specificity Specificity].

=== Tips for customising Moodle with SCSS (or CSS) ===
Some handy things to know when you are new to theming is that Moodle adds some classes to every page that helps you target a specific page or set of pages with some style rules.

If you inspect a moodle page and look at the body tag you will see a long list of classes e.g.

<code html>
<body id="page-course-view-weeks" class="format-weeks path-course path-course-view safari dir-ltr lang-en yui-skin-sam yui3-skin-sam damyon-per-in-moodle-com--stable_master pagelayout-course course-11 context-497 category-1 drawer-open-left jsenabled">
</code>

You can see from this example that each page gets an id. This is a simplified representation of the current page in the navigation. In this example we are looking at the course page and this course is using the weeks format.

The classes on the body tag can also be used to target a page or set of pages.
* <code>format-weeks</code> The course format
* <code>path-course path-course-view</code> The parts of the bread-crumb leading up to the current page (The current page is what goes in the id)
* <code>safari</code> Some server side guessing of the browser type - it's not accurate so I would not rely on it
* <code>dir-ltr</code> The direction of the current language for the page ( dir-rtl for RTL languages )
* <code>lang-en</code> The current language of the page
* <code>yui*</code> Legacy yui classes - ignore these
* <code>damyon-per-in-moodle-com--stable_master</code> The current hostname for the site + the site name
* <code>pagelayout-course</code> The layout type for the current page
* <code>course-11</code> The id of the current course
* <code>context-497</code> The current context id
* <code>category-1</code> The category for the current course
* <code>drawer-open-left</code> Added / removed when the navigation drawer is opened / closed in Boost
* <code>jsenabled</code> True if the browser supports javascript

[https://docs.moodle.org/dev/Themes_overview#.3Cbody.3E_CSS_id_and_classes Read about Body id and classes].

In our example the page layout is the most useful here as we have a specific page layout for login pages. We can now craft a rule that applies a background image only to login pages using "body.pagelayout-login".

=== How do we refer to an image in SCSS ? ===
So now we can add a rule to the post.scss which will set the background image for the login page. First we need to know how to construct a url to the background images from our stylesheet.

In stylesheets in Moodle we can use a special pix tag to refer to images from our theme. The rule to attach the background image looks like this:
''scss/post.scss''
<code scss>
body.pagelayout-login {
background-image: url([[pix:theme_photo|loginbackgroundimage]]);
background-size: cover;
}
</code>

There are 2 important parts to this tag (the bit in square brackets). The first is "theme_photo". In this case we are passing a component name, the image serving code in theme_config::resolve_image_location() will then look for an image file in several locations. One of these is in "$CFG->dataroot/pix_plugins/$type/$plugin/$image". We can use this to make sure the image gets served correctly by copying the file saved in the setting to this location every time it is updated. (There is an alterative way we could do this by implementing pluginfile.php in our theme - which you can read about in the [[File API]] ).

If we had just passed the value "theme" the image serving code would have looked for the image in the "pix" folder of our theme.

So - we need this final change to copy the image file into our dataroot each time the setting is changed.

In the settings file we will update the callback to a new function which we will define in our lib.php.
''settings.php''
<code php>

// Login page background setting.
// We use variables for readability.
$name = 'theme_photo/loginbackgroundimage';
$title = get_string('loginbackgroundimage', 'theme_photo');
$description = get_string('loginbackgroundimage_desc', 'theme_photo');
// This creates the new setting.
$setting = new admin_setting_configstoredfile($name, $title, $description, 'loginbackgroundimage');
// This function will copy the image into the data_root location it can be served from.
$setting->set_updatedcallback('theme_photo_update_settings_images');
// We always have to add the setting to a page for it to have any effect.
$page->add($setting);
</code>

''lib.php''
<code php>
function theme_photo_update_settings_images($settingname) {
global $CFG;

// The setting name that was updated comes as a string like 's_theme_photo_loginbackgroundimage'.
// We split it on '_' characters.
$parts = explode('_', $settingname);
// And get the last one to get the setting name..
$settingname = end($parts);

// Admin settings are stored in system context.
$syscontext = context_system::instance();
// This is the component name the setting is stored in.
$component = 'theme_photo';

// This is the value of the admin setting which is the filename of the uploaded file.
$filename = get_config($component, $settingname);
// We extract the file extension because we want to preserve it.
$extension = substr($filename, strrpos($filename, '.') + 1);

// This is the path in the moodle internal file system.
$fullpath = "/{$syscontext->id}/{$component}/{$settingname}/0{$filename}";
// Get an instance of the moodle file storage.
$fs = get_file_storage();
// This is an efficient way to get a file if we know the exact path.
if ($file = $fs->get_file_by_hash(sha1($fullpath))) {
// We got the stored file - copy it to dataroot.
// This location matches the searched for location in theme_config::resolve_image_location.
$pathname = $CFG->dataroot . '/pix_plugins/theme/photo/' . $settingname . '.' . $extension;

// This pattern matches any previous files with maybe different file extensions.
$pathpattern = $CFG->dataroot . '/pix_plugins/theme/photo/' . $settingname . '.*';

// Make sure this dir exists.
@mkdir($CFG->dataroot . '/pix_plugins/theme/photo/', $CFG->directorypermissions, true);

// Delete any existing files for this setting.
foreach (glob($pathpattern) as $filename) {
@unlink($filename);
}

// Copy the current file to this location.
$file->copy_content_to($pathname);
}

// Reset theme caches.
theme_reset_all_caches();
}
</code>

I won't show it here - but it is now easy to add a new background image setting for every layout type. I can re-use this theme_photo_update_settings_images callback for each one - so all I have to do is add the setting to the settings.php file, add the SCSS rule to the scss/post.scss file and add the lang strings to the language file.

Thats it for this tutorial, but there are [[:Category:Themes| more Themes docs]] to browse.

[[Category:Themes]]

Creating a theme based on boost

2020-07-31T10:30:59Z

Meeth: Undo revision 57735 by Meeth (talk)

{{Moodle 3.2}}
{{Template:Themes}}

This is a tutorial for how to create a new theme in any version of Moodle from 3.2 and later.

Moodle 3.2 introduced a new core theme named "Boost" which is a great starting point for themers wanting to build a modern Moodle theme utilising all the latest features available to themes in Moodle. If you aren't sure where to start, then START HERE! :-)

== Getting started ==
What is a theme? A theme in Moodle is just another type of plugin that can be developed. Themes are responsible for setting up the structure of each page and have the ability to customise the output of any page in Moodle.

This tutorial is based on a working theme named "theme_photo" you can download it or view the source code for it here: https://github.com/damyon/moodle-theme_photo

=== Choosing a name ===
Your new theme will need a name. Try and think of something short and memorable - and make sure it is not a name that has already been used by someone else. A quick search on the moodle.org/plugins can save you a lot of work renaming things later.

Lets call our new example theme "photo" as we will add some settings to allow "photos" in various places in Moodle.

=== Starting files ===
As a plugin, themes must start with the basic structure of a plugin in Moodle. See https://docs.moodle.org/dev/Tutorial#The_skeleton_of_your_plugin for an overview of the files common to all plugins in Moodle.

Following this guide we can start creating our theme. First we create the folder for the new theme under "/theme/" folder in the Moodle root directory.

<code>
/theme/photo/
</code>

Now we need to add some standard plugin files to our theme. First is version.php

''/theme/photo/version.php''

<code php>

<?php
// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// This is the version of the plugin.
$plugin->version = '2016102100';

// This is the version of Moodle this plugin requires.
$plugin->requires = '2016070700';

// This is the component name of the plugin - it always starts with 'theme_'
// for themes and should be the same as the name of the folder.
$plugin->component = 'theme_photo';

// This is a list of plugins, this plugin depends on (and their versions).
$plugin->dependencies = [
'theme_boost' => '2016102100'
];

</code>

We also need a language file so that all our strings can be translated into different languages. The name of this file is the component name of our plugin and it sits in the lang/en/ folder for our plugin. We can include translations of our plugin, but we can also provide translations via the https://lang.moodle.org/ website once our plugin has been published to the plugins database at http://www.moodle.org/plugins/.

''/theme/photo/lang/en/theme_photo.php''

<code php>

<?php
// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// A description shown in the admin theme selector.
$string['choosereadme'] = 'Theme photo is a child theme of Boost. It adds the ability to upload background photos.';
// The name of our plugin.
$string['pluginname'] = 'Photo';
// We need to include a lang string for each block region.
$string['region-side-pre'] = 'Right';
</code>

=== Theme specific files ===
Theme plugins have a few more standard files they need to define.

Themes require a favicon file to show in the address bar. See [[http://docs.moodle.org/en/Favicon Favicon]].

''pix/favicon.ico''

(Image file not shown).

Themes also require an example screenshot to be displayed in the theme selector.

''pix/screenshot.jpg''

(Image file not shown).

Themes require a lib.php file. This file contains callbacks used by various API's in Moodle. Initially this file can be empty, but as we add features to our theme we will need to add some functions here.

''lib.php''
<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// We will add callbacks here as we add features to our theme.
</code>

Theme config goes in a config.php file. This is one of the most important files in our theme. Once we add this file we will be ready to test our theme for the first time.

''config.php''

<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// $THEME is defined before this page is included and we can define settings by adding properties to this global object.

// The first setting we need is the name of the theme. This should be the last part of the component name, and the same
// as the directory name for our theme.
$THEME->name = 'photo';

// This setting list the style sheets we want to include in our theme. Because we want to use SCSS instead of CSS - we won't
// list any style sheets. If we did we would list the name of a file in the /style/ folder for our theme without any css file
// extensions.
$THEME->sheets = [];

// This is a setting that can be used to provide some styling to the content in the TinyMCE text editor. This is no longer the
// default text editor and "Atto" does not need this setting so we won't provide anything. If we did it would work the same
// as the previous setting - listing a file in the /styles/ folder.
$THEME->editor_sheets = [];

// This is a critical setting. We want to inherit from theme_boost because it provides a great starting point for SCSS bootstrap4
// themes. We could add more than one parent here to inherit from multiple parents, and if we did they would be processed in
// order of importance (later themes overriding earlier ones). Things we will inherit from the parent theme include
// styles and mustache templates and some (not all) settings.
$THEME->parents = ['boost'];

// A dock is a way to take blocks out of the page and put them in a persistent floating area on the side of the page. Boost
// does not support a dock so we won't either - but look at bootstrapbase for an example of a theme with a dock.
$THEME->enable_dock = false;

// This is an old setting used to load specific CSS for some YUI JS. We don't need it in Boost based themes because Boost
// provides default styling for the YUI modules that we use. It is not recommended to use this setting anymore.
$THEME->yuicssmodules = array();

// Most themes will use this rendererfactory as this is the one that allows the theme to override any other renderer.
$THEME->rendererfactory = 'theme_overridden_renderer_factory';

// This is a list of blocks that are required to exist on all pages for this theme to function correctly. For example
// bootstrap base requires the settings and navigation blocks because otherwise there would be no way to navigate to all the
// pages in Moodle. Boost does not require these blocks because it provides other ways to navigate built into the theme.
$THEME->requiredblocks = '';

// This is a feature that tells the blocks library not to use the "Add a block" block. We don't want this in boost based themes because
// it forces a block region into the page when editing is enabled and it takes up too much room.
$THEME->addblockposition = BLOCK_ADDBLOCK_POSITION_FLATNAV;
</code>

=== Ready set go! ===
If you have been following along - now we are at the point where we can actually install and test our new theme. Try it now by visiting the admin notifications page to install the new plugin, and then choosing the new theme from the theme selector.

[[https://docs.moodle.org/en/Standard_themes#Theme_selector Theme selector]]

When you choose the new theme - you will find that it looks exactly the same as Boost. At this point with our minimal configuration - we are inheriting almost everything from our parent theme including styles and templates. You will notice though that we don't inherit the settings from our parent theme. If you choose a different preset in Boost - it is not applied in this child theme.

<div class="warningbox">
Note: make sure your config.php file contains $THEME->hidefromselector = false; (or at least set to false) or else, your theme wont show up in theme selector.
</div>

=== What if I want the settings too? ===

<div class="warningbox">
This section is included for completeness - but it is not recommended for themes to utilise settings from their parents. To find out how to duplicate the settings from the parent theme so they operate independently skip to [[#Duplicate the settings from Boost]].
</div>

If I want the settings from Boost to apply to my child theme as well I need to know a bit about how each of the settings in Boost is applied to make them work in my child theme.

'''Setting 1 - preset.'''

The "preset" file is the file that is used as the main file for scss compilation. In Boost this is controlled by the theme config value:

''theme_boost/config.php''
<code php>
$THEME->scss = function($theme) {
return theme_boost_get_main_scss_content($theme);
};
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');
} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_boost', 'preset', 0, '/', $filename))) {
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

return $scss;
}
</code>

What this function is doing is checking for a theme setting "preset" and either fetching the file from Moodles internal file storage, or from the /preset/ folder. The function then returns the contents of this file.

It does not automatically work for our child theme because we have no setting named "preset" in our child theme and this code is not searching the theme parents for the setting. If we wanted it to apply we could do this in our child theme:

''config.php''
<code php>
// This setting defines the main scss file for our theme to be compiled. We could set it to a static file in the scss folder or to a function which returns the SCSS based on theme settings.
$THEME->scss = function($theme) {

// We need to load the config for our parent theme because that is where the preset setting is defined.
$parentconfig = theme_config::load('boost');
// Call a function from our parent themes lib.php file to fetch the content of the themes main SCSS file based on it's own config, not ours.
return theme_boost_get_main_scss_content($parentconfig);
};
</code>

'''Settings 2+3 brandcolor + scsspre'''

The way these settings work is they generate a chunk of SCSS to be prepended to the main scss file. In boost they work like this:

''theme_boost/config.php''
<code php>
$THEME->prescsscallback = 'theme_boost_get_pre_scss';
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_pre_scss($theme) {
global $CFG;

$scss = '';
$configurable = [
// Config key => [variableName, ...].
'brandcolor' => ['brand-primary'],
];

// Prepend variables first.
foreach ($configurable as $configkey => $targets) {
$value = isset($theme->settings->{$configkey}) ? $theme->settings->{$configkey} : null;
if (empty($value)) {
continue;
}
array_map(function($target) use (&$scss, $value) {
$scss .= '$' . $target . ': ' . $value . ";\n";
}, (array) $targets);
}

// Prepend pre-scss.
if (!empty($theme->settings->scsspre)) {
$scss .= $theme->settings->scsspre;
}

return $scss;
}
</code>

What this code is doing is:
* looping over a list of theme settings that map to a SCSS variable and building some SCSS to initialise that variable from the setting. In Boost there is only one * brandprimary - but if we wanted to expose more bootstrap variables as theme settings we could use this function as a template in our child theme and add more settings to the $configurable array.
* Adding all of the raw SCSS from the scsspre theme setting
* Returning the whole thing as a string to be added before the main scss file.

If we want this code to work in our child theme, using the settings from Boost we could do this:

''config.php''
<code php>
// This is a function that returns some SCSS as a string to prepend to the main SCSS file.
$THEME->prescsscallback = 'theme_photo_get_pre_scss';
</code>

''lib.php''
<code php>
// Function to return the SCSS to prepend to our main SCSS for this theme.
// Note the function name starts with the component name because this is a global function and we don't want namespace clashes.
function theme_photo_get_pre_scss($theme) {
// Load the settings from the parent.
$theme = theme_config::load('boost');
// Call the parent themes get_pre_scss function.
return theme_boost_get_pre_scss($theme);
}
</code>

'''Setting 4 scss (post)'''

The final setting from Boost is a raw text field which adds SCSS to the end of the main SCSS file. This is a useful place to add style rules as they will override previously defined styles with the same specificity. It is applied in Boost by the following lines:

''theme_boost/config.php''
<code php>
$THEME->extrascsscallback = 'theme_boost_get_extra_scss';
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_extra_scss($theme) {
return !empty($theme->settings->scss) ? $theme->settings->scss : '';
}
</code>

This is just returning the value of the setting as a string.

To make this setting apply in our child theme too - we use similar code to the previous sections.

''config.php''
<code php>
// This is a function that returns some SCSS as a string to append to the main SCSS file.
$THEME->extrascsscallback = 'theme_photo_get_extra_scss';
</code>

''lib.php''
<code php>
// Function to return the SCSS to append to our main SCSS for this theme.
// Note the function name starts with the component name because this is a global function and we don't want namespace clashes.
function theme_photo_get_extra_scss($theme) {
// Load the settings from the parent.
$theme = theme_config::load('boost');
// Call the parent themes get_extra_scss function.
return theme_boost_get_extra_scss($theme);
}
</code>

=== Duplicate the settings from Boost ===

This is the recommended way to extend boost as your child theme will not be affected by changes to the Boost settings, and both themes can be in use with different settings applied.

All that needs to happen is to create theme settings in the child theme that match each of the settings in the parent theme. You will need to add matching language strings for each of these settings in the language file.

This example shows how to do it - We are re-using the nice looking theme_boost_admin_settingspage_tabs class from boost and creating duplicate versions of each of the settings.

''settings.php''

<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// This is used for performance, we don't need to know about these settings on every page in Moodle, only when
// we are looking at the admin settings pages.
if ($ADMIN->fulltree) {

// Boost provides a nice setting page which splits settings onto separate tabs. We want to use it here.
$settings = new theme_boost_admin_settingspage_tabs('themesettingphoto', get_string('configtitle', 'theme_photo'));

// Each page is a tab - the first is the "General" tab.
$page = new admin_settingpage('theme_photo_general', get_string('generalsettings', 'theme_photo'));

// Replicate the preset setting from boost.
$name = 'theme_photo/preset';
$title = get_string('preset', 'theme_photo');
$description = get_string('preset_desc', 'theme_photo');
$default = 'default.scss';

// We list files in our own file area to add to the drop down. We will provide our own function to
// load all the presets from the correct paths.
$context = context_system::instance();
$fs = get_file_storage();
$files = $fs->get_area_files($context->id, 'theme_photo', 'preset', 0, 'itemid, filepath, filename', false);

$choices = [];
foreach ($files as $file) {
$choices[$file->get_filename()] = $file->get_filename();
}
// These are the built in presets from Boost.
$choices['default.scss'] = 'default.scss';
$choices['plain.scss'] = 'plain.scss';

$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Preset files setting.
$name = 'theme_photo/presetfiles';
$title = get_string('presetfiles','theme_photo');
$description = get_string('presetfiles_desc', 'theme_photo');

$setting = new admin_setting_configstoredfile($name, $title, $description, 'preset', 0,
array('maxfiles' => 20, 'accepted_types' => array('.scss')));
$page->add($setting);

// Variable $brand-color.
// We use an empty default value because the default colour should come from the preset.
$name = 'theme_photo/brandcolor';
$title = get_string('brandcolor', 'theme_photo');
$description = get_string('brandcolor_desc', 'theme_photo');
$setting = new admin_setting_configcolourpicker($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Must add the page after definiting all the settings!
$settings->add($page);

// Advanced settings.
$page = new admin_settingpage('theme_photo_advanced', get_string('advancedsettings', 'theme_photo'));

// Raw SCSS to include before the content.
$setting = new admin_setting_configtextarea('theme_photo/scsspre',
get_string('rawscsspre', 'theme_photo'), get_string('rawscsspre_desc', 'theme_photo'), '', PARAM_RAW);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Raw SCSS to include after the content.
$setting = new admin_setting_configtextarea('theme_photo/scss', get_string('rawscss', 'theme_photo'),
get_string('rawscss_desc', 'theme_photo'), '', PARAM_RAW);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

$settings->add($page);
}
</code>

''lang/en/theme_photo.php''
<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();
// The name of the second tab in the theme settings.
$string['advancedsettings'] = 'Advanced settings';
// The brand colour setting.
$string['brandcolor'] = 'Brand colour';
// The brand colour setting description.
$string['brandcolor_desc'] = 'The accent colour.';
// A description shown in the admin theme selector.
$string['choosereadme'] = 'Theme photo is a child theme of Boost. It adds the ability to upload background photos.';
// Name of the settings pages.
$string['configtitle'] = 'Photo settings';
// Name of the first settings tab.
$string['generalsettings'] = 'General settings';
// The name of our plugin.
$string['pluginname'] = 'Photo';
// Preset files setting.
$string['presetfiles'] = 'Additional theme preset files';
// Preset files help text.
$string['presetfiles_desc'] = 'Preset files can be used to dramatically alter the appearance of the theme. See <a href=https://docs.moodle.org/dev/Boost_Presets>Boost presets</a> for information on creating and sharing your own preset files, and see the <a href=http://moodle.net/boost>Presets repository</a> for presets that others have shared.';
// Preset setting.
$string['preset'] = 'Theme preset';
// Preset help text.
$string['preset_desc'] = 'Pick a preset to broadly change the look of the theme.';
// Raw SCSS setting.
$string['rawscss'] = 'Raw SCSS';
// Raw SCSS setting help text.
$string['rawscss_desc'] = 'Use this field to provide SCSS or CSS code which will be injected at the end of the style sheet.';
// Raw initial SCSS setting.
$string['rawscsspre'] = 'Raw initial SCSS';
// Raw initial SCSS setting help text.
$string['rawscsspre_desc'] = 'In this field you can provide initialising SCSS code, it will be injected before everything else. Most of the time you will use this setting to define variables.';
// We need to include a lang string for each block region.
$string['region-side-pre'] = 'Right';
</code>

We aren't quite there yet as you will notice if you try and upload a preset file and then choose it. The "theme_boost_get_main_scss_content" function from Boost is expecting the preset files to be stored in a file area for theme_boost only. We need to add this function to our own theme and tweak it.

''config.php''
<code php>
// This is the function that returns the SCSS source for the main file in our theme. We override the boost version because
// we want to allow presets uploaded to our own theme file area to be selected in the preset list.
$THEME->scss = function($theme) {
return theme_photo_get_main_scss_content($theme);
};
</code>

''lib.php''
<code php>
function theme_photo_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');

} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_photo', 'preset', 0, '/', $filename))) {
// This preset file was fetched from the file area for theme_photo and not theme_boost (see the line above).
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

return $scss;
}
</code>

=== Stop and try it out ===
So now what is working and what isn't. Well - everything should be working and you should have a nice new theme extending boost with it's own settings pages. When Boost gets updates for bug fixes your new theme will inherit those fixes as it inherits all the SCSS and templates from theme boost. In addition your new theme will accept preset files and supports all the same features and settings as boost, ready to add more.

== Take it further ==
Now we have our very nice starting point we can start changing or adding features, customising templates and output or tweaking the SCSS.

=== Add some new settings ===

From this point in the tutorial we will start adding features to our theme to extend it and make it AWESOME!

Lets start with a new setting to set a background image on the login page. As you saw earlier, our theme defines it's list of settings in a file called settings.php. See [[Admin settings]] for more information about adding admin settings to any plugin. All of the different kinds of admin settings can be found in lib/adminlib.php. In our case we will want to add a setting which allows an admin to upload an image file. This is an "admin_setting_configstoredfile" and we add it to our theme by adding this code to the settings.php file inside and at the end of the "if ($ADMIN->fulltree) {" condition.

''settings.php''
<code php>
// Login page background setting.
// We use variables for readability.
$name = 'theme_photo/loginbackgroundimage';
$title = get_string('loginbackgroundimage', 'theme_photo');
$description = get_string('loginbackgroundimage_desc', 'theme_photo');
// This creates the new setting.
$setting = new admin_setting_configstoredfile($name, $title, $description, 'loginbackgroundimage');
// This means that theme caches will automatically be cleared when this setting is changed.
$setting->set_updatedcallback('theme_reset_all_caches');
// We always have to add the setting to a page for it to have any effect.
$page->add($setting);
</code>

We also need to add new lang strings to our language file.

"lang/en/theme_photo.php"
<code php>
// Background image for login page.
$string['loginbackgroundimage'] = 'Login page background image';
// Background image for login page.
$string['loginbackgroundimage_desc'] = 'An image that will be stretched to fill the background of the login page.';
</code>

Now we have a new setting that lets us upload a file - but it doesn't actually do anything yet. We need to update the theme to set this image background on the login page.

In order to change the SCSS for our theme we will add 2 additional SCSS files and include them before and after our main scss.

We already have a function in our lib.php file which fetches the main SCSS for our theme. This is a good point to include additional SCSS files. We can add 2 lines to the end of this function to achieve this.

''lib.php''
<code php>
function theme_photo_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');

} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_photo', 'preset', 0, '/', $filename))) {
// This preset file was fetched from the file area for theme_photo and not theme_boost (see the line above).
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

// Pre CSS - this is loaded AFTER any prescss from the setting but before the main scss.
$pre = file_get_contents($CFG->dirroot . '/theme/photo/scss/pre.scss');
// Post CSS - this is loaded AFTER the main scss but before the extra scss from the setting.
$post = file_get_contents($CFG->dirroot . '/theme/photo/scss/post.scss');

// Combine them together.
return $pre . "\n" . $scss . "\n" . $post;
}
</code>

''scss/pre.scss''
<code scss>
// Pre SCSS for the theme.
</code>

''scss/post.scss''
<code scss>
// Post SCSS for the theme.
</code>

==== Why do we use pre and post SCSS? ====
SCSS/SASS is a powerful language for creating CSS. It supports variables, functions, loops just like php. For lots of information and an introduction to SCSS read about [https://en.wikipedia.org/wiki/Sass_(stylesheet_language) Sass on wikipedia].

'''Pre SCSS'''

In Boost we use many variables when creating style rules.

When declaring a variable in SCSS - it is best practice to define it like this:
<code scss>
$mycoolcolour: #FF0 !default;
</code>

What this means is - if this variable is not defined already - set it to the hex value '#FF0';

So by setting this variable in some PRE scss we can override the default value of this variable everywhere it is used. Boost is built with the [https://v4-alpha.getbootstrap.com/ Bootstrap 4 (Alpha 4)] CSS Framework. This is a framework which uses SCSS to provide many extremely useful layouts and components which can be reused without adding specific CSS rules to style every page. Because bootstrap consistently uses variables we can customise many of these components easily by setting the value of the variables before we include the Bootstrap SCSS files.

Many variables are available in /theme/boost/scss/bootstrap/_variables.scss - as an example we can change the look of all buttons and input fields with this one variable:

<code scss>
$border-radius: 8px;
</code>

'''Post SCSS'''

Post SCSS is useful for defining full CSS rules. Because they are included last, they override any previous matching selector with the same [https://en.wikipedia.org/wiki/Cascading_Style_Sheets#Specificity Specificity].

=== Tips for customising Moodle with SCSS (or CSS) ===
Some handy things to know when you are new to theming is that Moodle adds some classes to every page that helps you target a specific page or set of pages with some style rules.

If you inspect a moodle page and look at the body tag you will see a long list of classes e.g.

<code html>
<body id="page-course-view-weeks" class="format-weeks path-course path-course-view safari dir-ltr lang-en yui-skin-sam yui3-skin-sam damyon-per-in-moodle-com--stable_master pagelayout-course course-11 context-497 category-1 drawer-open-left jsenabled">
</code>

You can see from this example that each page gets an id. This is a simplified representation of the current page in the navigation. In this example we are looking at the course page and this course is using the weeks format.

The classes on the body tag can also be used to target a page or set of pages.
* <code>format-weeks</code> The course format
* <code>path-course path-course-view</code> The parts of the bread-crumb leading up to the current page (The current page is what goes in the id)
* <code>safari</code> Some server side guessing of the browser type - it's not accurate so I would not rely on it
* <code>dir-ltr</code> The direction of the current language for the page ( dir-rtl for RTL languages )
* <code>lang-en</code> The current language of the page
* <code>yui*</code> Legacy yui classes - ignore these
* <code>damyon-per-in-moodle-com--stable_master</code> The current hostname for the site + the site name
* <code>pagelayout-course</code> The layout type for the current page
* <code>course-11</code> The id of the current course
* <code>context-497</code> The current context id
* <code>category-1</code> The category for the current course
* <code>drawer-open-left</code> Added / removed when the navigation drawer is opened / closed in Boost
* <code>jsenabled</code> True if the browser supports javascript

[https://docs.moodle.org/dev/Themes_overview#.3Cbody.3E_CSS_id_and_classes Read about Body id and classes].

In our example the page layout is the most useful here as we have a specific page layout for login pages. We can now craft a rule that applies a background image only to login pages using "body.pagelayout-login".

=== How do we refer to an image in SCSS ? ===
So now we can add a rule to the post.scss which will set the background image for the login page. First we need to know how to construct a url to the background images from our stylesheet.

In stylesheets in Moodle we can use a special pix tag to refer to images from our theme. The rule to attach the background image looks like this:
''scss/post.scss''
<code scss>
body.pagelayout-login {
background-image: url([[pix:theme_photo|loginbackgroundimage]]);
background-size: cover;
}
</code>

There are 2 important parts to this tag (the bit in square brackets). The first is "theme_photo". In this case we are passing a component name, the image serving code in theme_config::resolve_image_location() will then look for an image file in several locations. One of these is in "$CFG->dataroot/pix_plugins/$type/$plugin/$image". We can use this to make sure the image gets served correctly by copying the file saved in the setting to this location every time it is updated. (There is an alterative way we could do this by implementing pluginfile.php in our theme - which you can read about in the [[File API]] ).

If we had just passed the value "theme" the image serving code would have looked for the image in the "pix" folder of our theme.

So - we need this final change to copy the image file into our dataroot each time the setting is changed.

In the settings file we will update the callback to a new function which we will define in our lib.php.
''settings.php''
<code php>

// Login page background setting.
// We use variables for readability.
$name = 'theme_photo/loginbackgroundimage';
$title = get_string('loginbackgroundimage', 'theme_photo');
$description = get_string('loginbackgroundimage_desc', 'theme_photo');
// This creates the new setting.
$setting = new admin_setting_configstoredfile($name, $title, $description, 'loginbackgroundimage');
// This function will copy the image into the data_root location it can be served from.
$setting->set_updatedcallback('theme_photo_update_settings_images');
// We always have to add the setting to a page for it to have any effect.
$page->add($setting);
</code>

''lib.php''
<code php>
function theme_photo_update_settings_images($settingname) {
global $CFG;

// The setting name that was updated comes as a string like 's_theme_photo_loginbackgroundimage'.
// We split it on '_' characters.
$parts = explode('_', $settingname);
// And get the last one to get the setting name..
$settingname = end($parts);

// Admin settings are stored in system context.
$syscontext = context_system::instance();
// This is the component name the setting is stored in.
$component = 'theme_photo';

// This is the value of the admin setting which is the filename of the uploaded file.
$filename = get_config($component, $settingname);
// We extract the file extension because we want to preserve it.
$extension = substr($filename, strrpos($filename, '.') + 1);

// This is the path in the moodle internal file system.
$fullpath = "/{$syscontext->id}/{$component}/{$settingname}/0{$filename}";
// Get an instance of the moodle file storage.
$fs = get_file_storage();
// This is an efficient way to get a file if we know the exact path.
if ($file = $fs->get_file_by_hash(sha1($fullpath))) {
// We got the stored file - copy it to dataroot.
// This location matches the searched for location in theme_config::resolve_image_location.
$pathname = $CFG->dataroot . '/pix_plugins/theme/photo/' . $settingname . '.' . $extension;

// This pattern matches any previous files with maybe different file extensions.
$pathpattern = $CFG->dataroot . '/pix_plugins/theme/photo/' . $settingname . '.*';

// Make sure this dir exists.
@mkdir($CFG->dataroot . '/pix_plugins/theme/photo/', $CFG->directorypermissions, true);

// Delete any existing files for this setting.
foreach (glob($pathpattern) as $filename) {
@unlink($filename);
}

// Copy the current file to this location.
$file->copy_content_to($pathname);
}

// Reset theme caches.
theme_reset_all_caches();
}
</code>

I won't show it here - but it is now easy to add a new background image setting for every layout type. I can re-use this theme_photo_update_settings_images callback for each one - so all I have to do is add the setting to the settings.php file, add the SCSS rule to the scss/post.scss file and add the lang strings to the language file.

Thats it for this tutorial, but there are [[:Category:Themes| more Themes docs]] to browse.

[[Category:Themes]]

Creating a theme based on boost

2020-07-31T09:45:53Z

Meeth: Undo revision 57737 by Meeth (talk)

{{Moodle 3.2}}
{{Template:Themes}}

This is a tutorial for how to create a new theme in any version of Moodle from 3.2 and later.

Moodle 3.2 introduced a new core theme named "Boost" which is a great starting point for themers wanting to build a modern Moodle theme utilising all the latest features available to themes in Moodle. If you aren't sure where to start, then START HERE! :-)

== Getting started ==
What is a theme? A theme in Moodle is just another type of plugin that can be developed. Themes are responsible for setting up the structure of each page and have the ability to customise the output of any page in Moodle.

This tutorial is based on a working theme named "theme_photo" you can download it or view the source code for it here: https://github.com/damyon/moodle-theme_photo

=== Choosing a name ===
Your new theme will need a name. Try and think of something short and memorable - and make sure it is not a name that has already been used by someone else. A quick search on the moodle.org/plugins can save you a lot of work renaming things later.

Lets call our new example theme "photo" as we will add some settings to allow "photos" in various places in Moodle.

=== Starting files ===
As a plugin, themes must start with the basic structure of a plugin in Moodle. See https://docs.moodle.org/dev/Tutorial#The_skeleton_of_your_plugin for an overview of the files common to all plugins in Moodle.

Following this guide we can start creating our theme. First we create the folder for the new theme under "/theme/" folder in the Moodle root directory.

<code>
/theme/photo/
</code>

Now we need to add some standard plugin files to our theme. First is version.php

''/theme/photo/version.php''

<code php>

<?php
// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// This is the version of the plugin.
$plugin->version = '2016102100';

// This is the version of Moodle this plugin requires.
$plugin->requires = '2016070700';

// This is the component name of the plugin - it always starts with 'theme_'
// for themes and should be the same as the name of the folder.
$plugin->component = 'theme_photo';

// This is a list of plugins, this plugin depends on (and their versions).
$plugin->dependencies = [
'theme_boost' => '2016102100'
];

</code>

We also need a language file so that all our strings can be translated into different languages. The name of this file is the component name of our plugin and it sits in the lang/en/ folder for our plugin. We can include translations of our plugin, but we can also provide translations via the https://lang.moodle.org/ website once our plugin has been published to the plugins database at http://www.moodle.org/plugins/.

''/theme/photo/lang/en/theme_photo.php''

<code php>

<?php
// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// A description shown in the admin theme selector.
$string['choosereadme'] = 'Theme photo is a child theme of Boost. It adds the ability to upload background photos.';
// The name of our plugin.
$string['pluginname'] = 'Photo';
// We need to include a lang string for each block region.
$string['region-side-pre'] = 'Right';
</code>

=== Theme specific files ===
Theme plugins have a few more standard files they need to define.

Themes require a favicon file to show in the address bar. See [[http://docs.moodle.org/en/Favicon Favicon]].

''pix/favicon.ico''

(Image file not shown).

Themes also require an example screenshot to be displayed in the theme selector.

''pix/screenshot.jpg''

(Image file not shown).

Themes require a lib.php file. This file contains callbacks used by various API's in Moodle. Initially this file can be empty, but as we add features to our theme we will need to add some functions here.

''lib.php''
<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// We will add callbacks here as we add features to our theme.
</code>

Theme config goes in a config.php file. This is one of the most important files in our theme. Once we add this file we will be ready to test our theme for the first time.

''config.php''

<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// $THEME is defined before this page is included and we can define settings by adding properties to this global object.

// The first setting we need is the name of the theme. This should be the last part of the component name, and the same
// as the directory name for our theme.
$THEME->name = 'photo';

// This setting list the style sheets we want to include in our theme. Because we want to use SCSS instead of CSS - we won't
// list any style sheets. If we did we would list the name of a file in the /style/ folder for our theme without any css file
// extensions.
$THEME->sheets = [];

// This is a setting that can be used to provide some styling to the content in the TinyMCE text editor. This is no longer the
// default text editor and "Atto" does not need this setting so we won't provide anything. If we did it would work the same
// as the previous setting - listing a file in the /styles/ folder.
$THEME->editor_sheets = [];

// This is a critical setting. We want to inherit from theme_boost because it provides a great starting point for SCSS bootstrap4
// themes. We could add more than one parent here to inherit from multiple parents, and if we did they would be processed in
// order of importance (later themes overriding earlier ones). Things we will inherit from the parent theme include
// styles and mustache templates and some (not all) settings.
$THEME->parents = ['boost'];

// A dock is a way to take blocks out of the page and put them in a persistent floating area on the side of the page. Boost
// does not support a dock so we won't either - but look at bootstrapbase for an example of a theme with a dock.
$THEME->enable_dock = false;

// This is an old setting used to load specific CSS for some YUI JS. We don't need it in Boost based themes because Boost
// provides default styling for the YUI modules that we use. It is not recommended to use this setting anymore.
$THEME->yuicssmodules = array();

// Most themes will use this rendererfactory as this is the one that allows the theme to override any other renderer.
$THEME->rendererfactory = 'theme_overridden_renderer_factory';

// This is a list of blocks that are required to exist on all pages for this theme to function correctly. For example
// bootstrap base requires the settings and navigation blocks because otherwise there would be no way to navigate to all the
// pages in Moodle. Boost does not require these blocks because it provides other ways to navigate built into the theme.
$THEME->requiredblocks = '';

// This is a feature that tells the blocks library not to use the "Add a block" block. We don't want this in boost based themes because
// it forces a block region into the page when editing is enabled and it takes up too much room.
$THEME->addblockposition = BLOCK_ADDBLOCK_POSITION_FLATNAV;
</code>

=== Ready set go! ===
If you have been following along - now we are at the point where we can actually install and test our new theme. Try it now by visiting the admin notifications page to install the new plugin, and then choosing the new theme from the theme selector.

[[https://docs.moodle.org/en/Standard_themes#Theme_selector Theme selector]]

When you choose the new theme - you will find that it looks exactly the same as Boost. At this point with our minimal configuration - we are inheriting almost everything from our parent theme including styles and templates. You will notice though that we don't inherit the settings from our parent theme. If you choose a different preset in Boost - it is not applied in this child theme.

<div class="warningbox">
Note: make sure your config.php file contains $THEME->hidefromselector = false; (or at least set to false) or else, your theme wont show up in theme selector.
</div>

=== What if I want the settings too? ===

<div class="warningbox">
This section is included for completeness - but it is not recommended for themes to utilise settings from their parents. To find out how to duplicate the settings from the parent theme so they operate independently skip to [[#Duplicate the settings from Boost]].
</div>

If I want the settings from Boost to apply to my child theme as well I need to know a bit about how each of the settings in Boost is applied to make them work in my child theme.

'''Setting 1 - preset.'''

The "preset" file is the file that is used as the main file for scss compilation. In Boost this is controlled by the theme config value:

''theme_boost/config.php''
<code php>
$THEME->scss = function($theme) {
return theme_boost_get_main_scss_content($theme);
};
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');
} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_boost', 'preset', 0, '/', $filename))) {
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

return $scss;
}
</code>

What this function is doing is checking for a theme setting "preset" and either fetching the file from Moodles internal file storage, or from the /preset/ folder. The function then returns the contents of this file.

It does not automatically work for our child theme because we have no setting named "preset" in our child theme and this code is not searching the theme parents for the setting. If we wanted it to apply we could do this in our child theme:

''config.php''
<code php>
// This setting defines the main scss file for our theme to be compiled. We could set it to a static file in the scss folder or to a function which returns the SCSS based on theme settings.
$THEME->scss = function($theme) {

// We need to load the config for our parent theme because that is where the preset setting is defined.
$parentconfig = theme_config::load('boost');
// Call a function from our parent themes lib.php file to fetch the content of the themes main SCSS file based on it's own config, not ours.
return theme_boost_get_main_scss_content($parentconfig);
};
</code>

'''Settings 2+3 brandcolor + scsspre'''

The way these settings work is they generate a chunk of SCSS to be prepended to the main scss file. In boost they work like this:

''theme_boost/config.php''
<code php>
$THEME->prescsscallback = 'theme_boost_get_pre_scss';
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_pre_scss($theme) {
global $CFG;

$scss = '';
$configurable = [
// Config key => [variableName, ...].
'brandcolor' => ['brand-primary'],
];

// Prepend variables first.
foreach ($configurable as $configkey => $targets) {
$value = isset($theme->settings->{$configkey}) ? $theme->settings->{$configkey} : null;
if (empty($value)) {
continue;
}
array_map(function($target) use (&$scss, $value) {
$scss .= '$' . $target . ': ' . $value . ";\n";
}, (array) $targets);
}

// Prepend pre-scss.
if (!empty($theme->settings->scsspre)) {
$scss .= $theme->settings->scsspre;
}

return $scss;
}
</code>

What this code is doing is:
* looping over a list of theme settings that map to a SCSS variable and building some SCSS to initialise that variable from the setting. In Boost there is only one * brandprimary - but if we wanted to expose more bootstrap variables as theme settings we could use this function as a template in our child theme and add more settings to the $configurable array.
* Adding all of the raw SCSS from the scsspre theme setting
* Returning the whole thing as a string to be added before the main scss file.

If we want this code to work in our child theme, using the settings from Boost we could do this:

''config.php''
<code php>
// This is a function that returns some SCSS as a string to prepend to the main SCSS file.
$THEME->prescsscallback = 'theme_photo_get_pre_scss';
</code>

''lib.php''
<code php>
// Function to return the SCSS to prepend to our main SCSS for this theme.
// Note the function name starts with the component name because this is a global function and we don't want namespace clashes.
function theme_photo_get_pre_scss($theme) {
// Load the settings from the parent.
$theme = theme_config::load('boost');
// Call the parent themes get_pre_scss function.
return theme_boost_get_pre_scss($theme);
}
</code>

'''Setting 4 scss (post)'''

The final setting from Boost is a raw text field which adds SCSS to the end of the main SCSS file. This is a useful place to add style rules as they will override previously defined styles with the same specificity. It is applied in Boost by the following lines:

''theme_boost/config.php''
<code php>
$THEME->extrascsscallback = 'theme_boost_get_extra_scss';
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_extra_scss($theme) {
return !empty($theme->settings->scss) ? $theme->settings->scss : '';
}
</code>

This is just returning the value of the setting as a string.

To make this setting apply in our child theme too - we use similar code to the previous sections.

''config.php''
<code php>
// This is a function that returns some SCSS as a string to append to the main SCSS file.
$THEME->extrascsscallback = 'theme_photo_get_extra_scss';
</code>

''lib.php''
<code php>
// Function to return the SCSS to append to our main SCSS for this theme.
// Note the function name starts with the component name because this is a global function and we don't want namespace clashes.
function theme_photo_get_extra_scss($theme) {
// Load the settings from the parent.
$theme = theme_config::load('boost');
// Call the parent themes get_extra_scss function.
return theme_boost_get_extra_scss($theme);
}
</code>

=== Duplicate the settings from Boost ===

This is the recommended way to extend boost as your child theme will not be affected by changes to the Boost settings, and both themes can be in use with different settings applied.

All that needs to happen is to create theme settings in the child theme that match each of the settings in the parent theme. You will need to add matching language strings for each of these settings in the language file.

This example shows how to do it - We are re-using the nice looking theme_boost_admin_settingspage_tabs class from boost and creating duplicate versions of each of the settings.

''settings.php''

<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// This is used for performance, we don't need to know about these settings on every page in Moodle, only when
// we are looking at the admin settings pages.
if ($ADMIN->fulltree) {

// Boost provides a nice setting page which splits settings onto separate tabs. We want to use it here.
$settings = new theme_boost_admin_settingspage_tabs('themesettingphoto', get_string('configtitle', 'theme_photo'));

// Each page is a tab - the first is the "General" tab.
$page = new admin_settingpage('theme_photo_general', get_string('generalsettings', 'theme_photo'));

// Replicate the preset setting from boost.
$name = 'theme_photo/preset';
$title = get_string('preset', 'theme_photo');
$description = get_string('preset_desc', 'theme_photo');
$default = 'default.scss';

// We list files in our own file area to add to the drop down. We will provide our own function to
// load all the presets from the correct paths.
$context = context_system::instance();
$fs = get_file_storage();
$files = $fs->get_area_files($context->id, 'theme_photo', 'preset', 0, 'itemid, filepath, filename', false);

$choices = [];
foreach ($files as $file) {
$choices[$file->get_filename()] = $file->get_filename();
}
// These are the built in presets from Boost.
$choices['default.scss'] = 'default.scss';
$choices['plain.scss'] = 'plain.scss';

$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Preset files setting.
$name = 'theme_photo/presetfiles';
$title = get_string('presetfiles','theme_photo');
$description = get_string('presetfiles_desc', 'theme_photo');

$setting = new admin_setting_configstoredfile($name, $title, $description, 'preset', 0,
array('maxfiles' => 20, 'accepted_types' => array('.scss')));
$page->add($setting);

// Variable $brand-color.
// We use an empty default value because the default colour should come from the preset.
$name = 'theme_photo/brandcolor';
$title = get_string('brandcolor', 'theme_photo');
$description = get_string('brandcolor_desc', 'theme_photo');
$setting = new admin_setting_configcolourpicker($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Must add the page after definiting all the settings!
$settings->add($page);

// Advanced settings.
$page = new admin_settingpage('theme_photo_advanced', get_string('advancedsettings', 'theme_photo'));

// Raw SCSS to include before the content.
$setting = new admin_setting_configtextarea('theme_photo/scsspre',
get_string('rawscsspre', 'theme_photo'), get_string('rawscsspre_desc', 'theme_photo'), '', PARAM_RAW);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Raw SCSS to include after the content.
$setting = new admin_setting_configtextarea('theme_photo/scss', get_string('rawscss', 'theme_photo'),
get_string('rawscss_desc', 'theme_photo'), '', PARAM_RAW);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

$settings->add($page);
}
</code>

''lang/en/theme_photo.php''
<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();
// The name of the second tab in the theme settings.
$string['advancedsettings'] = 'Advanced settings';
// The brand colour setting.
$string['brandcolor'] = 'Brand colour';
// The brand colour setting description.
$string['brandcolor_desc'] = 'The accent colour.';
// A description shown in the admin theme selector.
$string['choosereadme'] = 'Theme photo is a child theme of Boost. It adds the ability to upload background photos.';
// Name of the settings pages.
$string['configtitle'] = 'Photo settings';
// Name of the first settings tab.
$string['generalsettings'] = 'General settings';
// The name of our plugin.
$string['pluginname'] = 'Photo';
// Preset files setting.
$string['presetfiles'] = 'Additional theme preset files';
// Preset files help text.
$string['presetfiles_desc'] = 'Preset files can be used to dramatically alter the appearance of the theme. See <a href=https://docs.moodle.org/dev/Boost_Presets>Boost presets</a> for information on creating and sharing your own preset files, and see the <a href=http://moodle.net/boost>Presets repository</a> for presets that others have shared.';
// Preset setting.
$string['preset'] = 'Theme preset';
// Preset help text.
$string['preset_desc'] = 'Pick a preset to broadly change the look of the theme.';
// Raw SCSS setting.
$string['rawscss'] = 'Raw SCSS';
// Raw SCSS setting help text.
$string['rawscss_desc'] = 'Use this field to provide SCSS or CSS code which will be injected at the end of the style sheet.';
// Raw initial SCSS setting.
$string['rawscsspre'] = 'Raw initial SCSS';
// Raw initial SCSS setting help text.
$string['rawscsspre_desc'] = 'In this field you can provide initialising SCSS code, it will be injected before everything else. Most of the time you will use this setting to define variables.';
// We need to include a lang string for each block region.
$string['region-side-pre'] = 'Right';
</code>

We aren't quite there yet as you will notice if you try and upload a preset file and then choose it. The "theme_boost_get_main_scss_content" function from Boost is expecting the preset files to be stored in a file area for theme_boost only. We need to add this function to our own theme and tweak it.

''config.php''
<code php>
// This is the function that returns the SCSS source for the main file in our theme. We override the boost version because
// we want to allow presets uploaded to our own theme file area to be selected in the preset list.
$THEME->scss = function($theme) {
return theme_photo_get_main_scss_content($theme);
};
</code>

''lib.php''
<code php>
function theme_photo_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');

} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_photo', 'preset', 0, '/', $filename))) {
// This preset file was fetched from the file area for theme_photo and not theme_boost (see the line above).
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

return $scss;
}
</code>

=== Stop and try it out ===
So now what is working and what isn't. Well - everything should be working and you should have a nice new theme extending boost with it's own settings pages. When Boost gets updates for bug fixes your new theme will inherit those fixes as it inherits all the SCSS and templates from theme boost. In addition your new theme will accept preset files and supports all the same features and settings as boost, ready to add more.

== Take it further ==
Now we have our very nice starting point we can start changing or adding features, customising templates and output or tweaking the SCSS.

=== Add some new settings ===

From this point in the tutorial we will start adding features to our theme to extend it and make it AWESOME!

Lets start with a new setting to set a background image on the login page. As you saw earlier, our theme defines it's list of settings in a file called settings.php. See [[Admin settings]] for more information about adding admin settings to any plugin. All of the different kinds of admin settings can be found in lib/adminlib.php. In our case we will want to add a setting which allows an admin to upload an image file. This is an "admin_setting_configstoredfile" and we add it to our theme by adding this code to the settings.php file inside and at the end of the "if ($ADMIN->fulltree) {" condition.

''settings.php''
<code php>
// Login page background setting.
// We use variables for readability.
$name = 'theme_photo/loginbackgroundimage';
$title = get_string('loginbackgroundimage', 'theme_photo');
$description = get_string('loginbackgroundimage_desc', 'theme_photo');
// This creates the new setting.
$setting = new admin_setting_configstoredfile($name, $title, $description, 'loginbackgroundimage');
// This means that theme caches will automatically be cleared when this setting is changed.
$setting->set_updatedcallback('theme_reset_all_caches');
// We always have to add the setting to a page for it to have any effect.
$page->add($setting);
</code>

We also need to add new lang strings to our language file.

"lang/en/theme_photo.php"
<code php>
// Background image for login page.
$string['loginbackgroundimage'] = 'Login page background image';
// Background image for login page.
$string['loginbackgroundimage_desc'] = 'An image that will be stretched to fill the background of the login page.';
</code>

Now we have a new setting that lets us upload a file - but it doesn't actually do anything yet. We need to update the theme to set this image background on the login page.

In order to change the SCSS for our theme we will add 2 additional SCSS files and include them before and after our main scss.

We already have a function in our lib.php file which fetches the main SCSS for our theme. This is a good point to include additional SCSS files. We can add 2 lines to the end of this function to achieve this.

''lib.php''
<code php>
function theme_photo_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');

} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_photo', 'preset', 0, '/', $filename))) {
// This preset file was fetched from the file area for theme_photo and not theme_boost (see the line above).
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

// Pre CSS - this is loaded AFTER any prescss from the setting but before the main scss.
$pre = file_get_contents($CFG->dirroot . '/theme/photo/scss/pre.scss');
// Post CSS - this is loaded AFTER the main scss but before the extra scss from the setting.
$post = file_get_contents($CFG->dirroot . '/theme/photo/scss/post.scss');

// Combine them together.
return $pre . "\n" . $scss . "\n" . $post;
}
</code>

''scss/pre.scss''
<code scss>
// Pre SCSS for the theme.
</code>

''scss/post.scss''
<code scss>
// Post SCSS for the theme.
</code>

==== Why do we use pre and post SCSS? ====
SCSS/SASS is a powerful language for creating CSS. It supports variables, functions, loops just like php. For lots of information and an introduction to SCSS read about [https://en.wikipedia.org/wiki/Sass_(stylesheet_language) Sass on wikipedia].

'''Pre SCSS'''

In Boost we use many variables when creating style rules.

When declaring a variable in SCSS - it is best practice to define it like this:
<code scss>
$mycoolcolour: #FF0 !default;
</code>

What this means is - if this variable is not defined already - set it to the hex value '#FF0';

So by setting this variable in some PRE scss we can override the default value of this variable everywhere it is used. Boost is built with the [https://v4-alpha.getbootstrap.com/ Bootstrap 4 (Alpha 4)] CSS Framework. This is a framework which uses SCSS to provide many extremely useful layouts and components which can be reused without adding specific CSS rules to style every page. Because bootstrap consistently uses variables we can customise many of these components easily by setting the value of the variables before we include the Bootstrap SCSS files.

Many variables are available in /theme/boost/scss/bootstrap/_variables.scss - as an example we can change the look of all buttons and input fields with this one variable:

<code scss>
$border-radius: 8px;
</code>

'''Post SCSS'''

Post SCSS is useful for defining full CSS rules. Because they are included last, they override any previous matching selector with the same [https://en.wikipedia.org/wiki/Cascading_Style_Sheets#Specificity Specificity].

=== Tips for customising Moodle with SCSS (or CSS) ===
Some handy things to know when you are new to theming is that Moodle adds some classes to every page that helps you target a specific page or set of pages with some style rules.

If you inspect a moodle page and look at the body tag you will see a long list of classes e.g.

<code html>
<body id="page-course-view-weeks" class="format-weeks path-course path-course-view safari dir-ltr lang-en yui-skin-sam yui3-skin-sam damyon-per-in-moodle-com--stable_master pagelayout-course course-11 context-497 category-1 drawer-open-left jsenabled">
</code>

You can see from this example that each page gets an id. This is a simplified representation of the current page in the navigation. In this example we are looking at the course page and this course is using the weeks format.

The classes on the body tag can also be used to target a page or set of pages.
* <code>format-weeks</code> The course format
* <code>path-course path-course-view</code> The parts of the bread-crumb leading up to the current page (The current page is what goes in the id)
* <code>safari</code> Some server side guessing of the browser type - it's not accurate so I would not rely on it
* <code>dir-ltr</code> The direction of the current language for the page ( dir-rtl for RTL languages )
* <code>lang-en</code> The current language of the page
* <code>yui*</code> Legacy yui classes - ignore these
* <code>damyon-per-in-moodle-com--stable_master</code> The current hostname for the site + the site name
* <code>pagelayout-course</code> The layout type for the current page
* <code>course-11</code> The id of the current course
* <code>context-497</code> The current context id
* <code>category-1</code> The category for the current course
* <code>drawer-open-left</code> Added / removed when the navigation drawer is opened / closed in Boost
* <code>jsenabled</code> True if the browser supports javascript

[https://docs.moodle.org/dev/Themes_overview#.3Cbody.3E_CSS_id_and_classes Read about Body id and classes].

In our example the page layout is the most useful here as we have a specific page layout for login pages. We can now craft a rule that applies a background image only to login pages using "body.pagelayout-login".

=== How do we refer to an image in SCSS ? ===
So now we can add a rule to the post.scss which will set the background image for the login page. First we need to know how to construct a url to the background images from our stylesheet.

In stylesheets in Moodle we can use a special pix tag to refer to images from our theme. The rule to attach the background image looks like this:
''scss/post.scss''
<code scss>
body.pagelayout-login {
background-image: url([[pix:theme_photo|loginbackgroundimage]]);
background-size: cover;
}
</code>

There are 2 important parts to this tag (the bit in square brackets). The first is "theme_photo". In this case we are passing a component name, the image serving code in theme_config::resolve_image_location() will then look for an image file in several locations. One of these is in "$CFG->dataroot/pix_plugins/$type/$plugin/$image". We can use this to make sure the image gets served correctly by copying the file saved in the setting to this location every time it is updated. (There is an alterative way we could do this by implementing pluginfile.php in our theme - which you can read about in the [[File API]] ).

If we had just passed the value "theme" the image serving code would have looked for the image in the "pix" folder of our theme.

So - we need this final change to copy the image file into our dataroot each time the setting is changed.

In the settings file we will update the callback to a new function which we will define in our lib.php.
''settings.php''
<code php>

// Login page background setting.
// We use variables for readability.
$name = 'theme_photo/loginbackgroundimage';
$title = get_string('loginbackgroundimage', 'theme_photo');
$description = get_string('loginbackgroundimage_desc', 'theme_photo');
// This creates the new setting.
$setting = new admin_setting_configstoredfile($name, $title, $description, 'loginbackgroundimage');
// This function will copy the image into the data_root location it can be served from.
$setting->set_updatedcallback('theme_photo_update_settings_images');
// We always have to add the setting to a page for it to have any effect.
$page->add($setting);
//This will commit the background image setting. If you do not add this line the Login page background setting will not be shown.
$settings->add($page);
</code>

''lib.php''
<code php>
function theme_photo_update_settings_images($settingname) {
global $CFG;

// The setting name that was updated comes as a string like 's_theme_photo_loginbackgroundimage'.
// We split it on '_' characters.
$parts = explode('_', $settingname);
// And get the last one to get the setting name..
$settingname = end($parts);

// Admin settings are stored in system context.
$syscontext = context_system::instance();
// This is the component name the setting is stored in.
$component = 'theme_photo';

// This is the value of the admin setting which is the filename of the uploaded file.
$filename = get_config($component, $settingname);
// We extract the file extension because we want to preserve it.
$extension = substr($filename, strrpos($filename, '.') + 1);

// This is the path in the moodle internal file system.
$fullpath = "/{$syscontext->id}/{$component}/{$settingname}/0{$filename}";
// Get an instance of the moodle file storage.
$fs = get_file_storage();
// This is an efficient way to get a file if we know the exact path.
if ($file = $fs->get_file_by_hash(sha1($fullpath))) {
// We got the stored file - copy it to dataroot.
// This location matches the searched for location in theme_config::resolve_image_location.
$pathname = $CFG->dataroot . '/pix_plugins/theme/photo/' . $settingname . '.' . $extension;

// This pattern matches any previous files with maybe different file extensions.
$pathpattern = $CFG->dataroot . '/pix_plugins/theme/photo/' . $settingname . '.*';

// Make sure this dir exists.
@mkdir($CFG->dataroot . '/pix_plugins/theme/photo/', $CFG->directorypermissions, true);

// Delete any existing files for this setting.
foreach (glob($pathpattern) as $filename) {
@unlink($filename);
}

// Copy the current file to this location.
$file->copy_content_to($pathname);
}

// Reset theme caches.
theme_reset_all_caches();
}
</code>

To edit the setting go to '''Site Administration > Appearance > Photo > Advanced setting'''. You will now see the Login page background setting.
It is now easy to add a new background image setting for every layout type. I can re-use this theme_photo_update_settings_images callback for each one - so all I have to do is add the setting to the settings.php file, add the SCSS rule to the scss/post.scss file and add the lang strings to the language file.

Thats it for this tutorial, but there are [[:Category:Themes| more Themes docs]] to browse.

[[Category:Themes]]

Creating a theme based on boost

2020-07-30T11:09:17Z

Meeth: /* Duplicate the settings from Boost */

{{Moodle 3.2}}
{{Template:Themes}}

This is a tutorial for how to create a new theme in any version of Moodle from 3.2 and later.

Moodle 3.2 introduced a new core theme named "Boost" which is a great starting point for themers wanting to build a modern Moodle theme utilising all the latest features available to themes in Moodle. If you aren't sure where to start, then START HERE! :-)

== Getting started ==
What is a theme? A theme in Moodle is just another type of plugin that can be developed. Themes are responsible for setting up the structure of each page and have the ability to customise the output of any page in Moodle.

This tutorial is based on a working theme named "theme_photo" you can download it or view the source code for it here: https://github.com/damyon/moodle-theme_photo

=== Choosing a name ===
Your new theme will need a name. Try and think of something short and memorable - and make sure it is not a name that has already been used by someone else. A quick search on the moodle.org/plugins can save you a lot of work renaming things later.

Lets call our new example theme "photo" as we will add some settings to allow "photos" in various places in Moodle.

=== Starting files ===
As a plugin, themes must start with the basic structure of a plugin in Moodle. See https://docs.moodle.org/dev/Tutorial#The_skeleton_of_your_plugin for an overview of the files common to all plugins in Moodle.

Following this guide we can start creating our theme. First we create the folder for the new theme under "/theme/" folder in the Moodle root directory.

<code>
/theme/photo/
</code>

Now we need to add some standard plugin files to our theme. First is version.php

''/theme/photo/version.php''

<code php>

<?php
// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// This is the version of the plugin.
$plugin->version = '2016102100';

// This is the version of Moodle this plugin requires.
$plugin->requires = '2016070700';

// This is the component name of the plugin - it always starts with 'theme_'
// for themes and should be the same as the name of the folder.
$plugin->component = 'theme_photo';

// This is a list of plugins, this plugin depends on (and their versions).
$plugin->dependencies = [
'theme_boost' => '2016102100'
];

</code>

We also need a language file so that all our strings can be translated into different languages. The name of this file is the component name of our plugin and it sits in the lang/en/ folder for our plugin. We can include translations of our plugin, but we can also provide translations via the https://lang.moodle.org/ website once our plugin has been published to the plugins database at http://www.moodle.org/plugins/.

''/theme/photo/lang/en/theme_photo.php''

<code php>

<?php
// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// A description shown in the admin theme selector.
$string['choosereadme'] = 'Theme photo is a child theme of Boost. It adds the ability to upload background photos.';
// The name of our plugin.
$string['pluginname'] = 'Photo';
// We need to include a lang string for each block region.
$string['region-side-pre'] = 'Right';
</code>

=== Theme specific files ===
Theme plugins have a few more standard files they need to define.

Themes require a favicon file to show in the address bar. See [[http://docs.moodle.org/en/Favicon Favicon]].

''pix/favicon.ico''

(Image file not shown).

Themes also require an example screenshot to be displayed in the theme selector.

''pix/screenshot.jpg''

(Image file not shown).

Themes require a lib.php file. This file contains callbacks used by various API's in Moodle. Initially this file can be empty, but as we add features to our theme we will need to add some functions here.

''lib.php''
<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// We will add callbacks here as we add features to our theme.
</code>

Theme config goes in a config.php file. This is one of the most important files in our theme. Once we add this file we will be ready to test our theme for the first time.

''config.php''

<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// $THEME is defined before this page is included and we can define settings by adding properties to this global object.

// The first setting we need is the name of the theme. This should be the last part of the component name, and the same
// as the directory name for our theme.
$THEME->name = 'photo';

// This setting list the style sheets we want to include in our theme. Because we want to use SCSS instead of CSS - we won't
// list any style sheets. If we did we would list the name of a file in the /style/ folder for our theme without any css file
// extensions.
$THEME->sheets = [];

// This is a setting that can be used to provide some styling to the content in the TinyMCE text editor. This is no longer the
// default text editor and "Atto" does not need this setting so we won't provide anything. If we did it would work the same
// as the previous setting - listing a file in the /styles/ folder.
$THEME->editor_sheets = [];

// This is a critical setting. We want to inherit from theme_boost because it provides a great starting point for SCSS bootstrap4
// themes. We could add more than one parent here to inherit from multiple parents, and if we did they would be processed in
// order of importance (later themes overriding earlier ones). Things we will inherit from the parent theme include
// styles and mustache templates and some (not all) settings.
$THEME->parents = ['boost'];

// A dock is a way to take blocks out of the page and put them in a persistent floating area on the side of the page. Boost
// does not support a dock so we won't either - but look at bootstrapbase for an example of a theme with a dock.
$THEME->enable_dock = false;

// This is an old setting used to load specific CSS for some YUI JS. We don't need it in Boost based themes because Boost
// provides default styling for the YUI modules that we use. It is not recommended to use this setting anymore.
$THEME->yuicssmodules = array();

// Most themes will use this rendererfactory as this is the one that allows the theme to override any other renderer.
$THEME->rendererfactory = 'theme_overridden_renderer_factory';

// This is a list of blocks that are required to exist on all pages for this theme to function correctly. For example
// bootstrap base requires the settings and navigation blocks because otherwise there would be no way to navigate to all the
// pages in Moodle. Boost does not require these blocks because it provides other ways to navigate built into the theme.
$THEME->requiredblocks = '';

// This is a feature that tells the blocks library not to use the "Add a block" block. We don't want this in boost based themes because
// it forces a block region into the page when editing is enabled and it takes up too much room.
$THEME->addblockposition = BLOCK_ADDBLOCK_POSITION_FLATNAV;
</code>

=== Ready set go! ===
If you have been following along - now we are at the point where we can actually install and test our new theme. Try it now by visiting the admin notifications page to install the new plugin, and then choosing the new theme from the theme selector.

[[https://docs.moodle.org/en/Standard_themes#Theme_selector Theme selector]]

When you choose the new theme - you will find that it looks exactly the same as Boost. At this point with our minimal configuration - we are inheriting almost everything from our parent theme including styles and templates. You will notice though that we don't inherit the settings from our parent theme. If you choose a different preset in Boost - it is not applied in this child theme.

<div class="warningbox">
Note: make sure your config.php file contains $THEME->hidefromselector = false; (or at least set to false) or else, your theme wont show up in theme selector.
</div>

=== What if I want the settings too? ===

<div class="warningbox">
This section is included for completeness - but it is not recommended for themes to utilise settings from their parents. To find out how to duplicate the settings from the parent theme so they operate independently skip to [[#Duplicate the settings from Boost]].
</div>

If I want the settings from Boost to apply to my child theme as well I need to know a bit about how each of the settings in Boost is applied to make them work in my child theme.

'''Setting 1 - preset.'''

The "preset" file is the file that is used as the main file for scss compilation. In Boost this is controlled by the theme config value:

''theme_boost/config.php''
<code php>
$THEME->scss = function($theme) {
return theme_boost_get_main_scss_content($theme);
};
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');
} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_boost', 'preset', 0, '/', $filename))) {
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

return $scss;
}
</code>

What this function is doing is checking for a theme setting "preset" and either fetching the file from Moodles internal file storage, or from the /preset/ folder. The function then returns the contents of this file.

It does not automatically work for our child theme because we have no setting named "preset" in our child theme and this code is not searching the theme parents for the setting. If we wanted it to apply we could do this in our child theme:

''config.php''
<code php>
// This setting defines the main scss file for our theme to be compiled. We could set it to a static file in the scss folder or to a function which returns the SCSS based on theme settings.
$THEME->scss = function($theme) {

// We need to load the config for our parent theme because that is where the preset setting is defined.
$parentconfig = theme_config::load('boost');
// Call a function from our parent themes lib.php file to fetch the content of the themes main SCSS file based on it's own config, not ours.
return theme_boost_get_main_scss_content($parentconfig);
};
</code>

'''Settings 2+3 brandcolor + scsspre'''

The way these settings work is they generate a chunk of SCSS to be prepended to the main scss file. In boost they work like this:

''theme_boost/config.php''
<code php>
$THEME->prescsscallback = 'theme_boost_get_pre_scss';
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_pre_scss($theme) {
global $CFG;

$scss = '';
$configurable = [
// Config key => [variableName, ...].
'brandcolor' => ['brand-primary'],
];

// Prepend variables first.
foreach ($configurable as $configkey => $targets) {
$value = isset($theme->settings->{$configkey}) ? $theme->settings->{$configkey} : null;
if (empty($value)) {
continue;
}
array_map(function($target) use (&$scss, $value) {
$scss .= '$' . $target . ': ' . $value . ";\n";
}, (array) $targets);
}

// Prepend pre-scss.
if (!empty($theme->settings->scsspre)) {
$scss .= $theme->settings->scsspre;
}

return $scss;
}
</code>

What this code is doing is:
* looping over a list of theme settings that map to a SCSS variable and building some SCSS to initialise that variable from the setting. In Boost there is only one * brandprimary - but if we wanted to expose more bootstrap variables as theme settings we could use this function as a template in our child theme and add more settings to the $configurable array.
* Adding all of the raw SCSS from the scsspre theme setting
* Returning the whole thing as a string to be added before the main scss file.

If we want this code to work in our child theme, using the settings from Boost we could do this:

''config.php''
<code php>
// This is a function that returns some SCSS as a string to prepend to the main SCSS file.
$THEME->prescsscallback = 'theme_photo_get_pre_scss';
</code>

''lib.php''
<code php>
// Function to return the SCSS to prepend to our main SCSS for this theme.
// Note the function name starts with the component name because this is a global function and we don't want namespace clashes.
function theme_photo_get_pre_scss($theme) {
// Load the settings from the parent.
$theme = theme_config::load('boost');
// Call the parent themes get_pre_scss function.
return theme_boost_get_pre_scss($theme);
}
</code>

'''Setting 4 scss (post)'''

The final setting from Boost is a raw text field which adds SCSS to the end of the main SCSS file. This is a useful place to add style rules as they will override previously defined styles with the same specificity. It is applied in Boost by the following lines:

''theme_boost/config.php''
<code php>
$THEME->extrascsscallback = 'theme_boost_get_extra_scss';
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_extra_scss($theme) {
return !empty($theme->settings->scss) ? $theme->settings->scss : '';
}
</code>

This is just returning the value of the setting as a string.

To make this setting apply in our child theme too - we use similar code to the previous sections.

''config.php''
<code php>
// This is a function that returns some SCSS as a string to append to the main SCSS file.
$THEME->extrascsscallback = 'theme_photo_get_extra_scss';
</code>

''lib.php''
<code php>
// Function to return the SCSS to append to our main SCSS for this theme.
// Note the function name starts with the component name because this is a global function and we don't want namespace clashes.
function theme_photo_get_extra_scss($theme) {
// Load the settings from the parent.
$theme = theme_config::load('boost');
// Call the parent themes get_extra_scss function.
return theme_boost_get_extra_scss($theme);
}
</code>

=== Duplicate the settings from Boost ===

This is the recommended way to extend boost as your child theme will not be affected by changes to the Boost settings, and both themes can be in use with different settings applied.

All that needs to happen is to create theme settings in the child theme that match each of the settings in the parent theme. You will need to add matching language strings for each of these settings in the language file.

This example shows how to do it - We are re-using the nice looking theme_boost_admin_settingspage_tabs class from boost and creating duplicate versions of each of the settings.

''settings.php''

<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// This is used for performance, we don't need to know about these settings on every page in Moodle, only when
// we are looking at the admin settings pages.
if ($ADMIN->fulltree) {

// Boost provides a nice setting page which splits settings onto separate tabs. We want to use it here.
$settings = new theme_boost_admin_settingspage_tabs('themesettingphoto', get_string('configtitle', 'theme_photo'));

// Each page is a tab - the first is the "General" tab.
$page = new admin_settingpage('theme_photo_general', get_string('generalsettings', 'theme_photo'));

// Replicate the preset setting from boost.
$name = 'theme_photo/preset';
$title = get_string('preset', 'theme_photo');
$description = get_string('preset_desc', 'theme_photo');
$default = 'default.scss';

// We list files in our own file area to add to the drop down. We will provide our own function to
// load all the presets from the correct paths.
$context = context_system::instance();
$fs = get_file_storage();
$files = $fs->get_area_files($context->id, 'theme_photo', 'preset', 0, 'itemid, filepath, filename', false);

$choices = [];
foreach ($files as $file) {
$choices[$file->get_filename()] = $file->get_filename();
}
// These are the built in presets from Boost.
$choices['default.scss'] = 'default.scss';
$choices['plain.scss'] = 'plain.scss';

$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Preset files setting.
$name = 'theme_photo/presetfiles';
$title = get_string('presetfiles','theme_photo');
$description = get_string('presetfiles_desc', 'theme_photo');

$setting = new admin_setting_configstoredfile($name, $title, $description, 'preset', 0,
array('maxfiles' => 20, 'accepted_types' => array('.scss')));
$page->add($setting);

// Variable $brand-color.
// We use an empty default value because the default colour should come from the preset.
$name = 'theme_photo/brandcolor';
$title = get_string('brandcolor', 'theme_photo');
$description = get_string('brandcolor_desc', 'theme_photo');
$setting = new admin_setting_configcolourpicker($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Must add the page after definiting all the settings!
$settings->add($page);

// Advanced settings.
$page = new admin_settingpage('theme_photo_advanced', get_string('advancedsettings', 'theme_photo'));

// Raw SCSS to include before the content.
$setting = new admin_setting_configtextarea('theme_photo/scsspre',
get_string('rawscsspre', 'theme_photo'), get_string('rawscsspre_desc', 'theme_photo'), '', PARAM_RAW);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Raw SCSS to include after the content.
$setting = new admin_setting_configtextarea('theme_photo/scss', get_string('rawscss', 'theme_photo'),
get_string('rawscss_desc', 'theme_photo'), '', PARAM_RAW);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);
}
</code>

''lang/en/theme_photo.php''
<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();
// The name of the second tab in the theme settings.
$string['advancedsettings'] = 'Advanced settings';
// The brand colour setting.
$string['brandcolor'] = 'Brand colour';
// The brand colour setting description.
$string['brandcolor_desc'] = 'The accent colour.';
// A description shown in the admin theme selector.
$string['choosereadme'] = 'Theme photo is a child theme of Boost. It adds the ability to upload background photos.';
// Name of the settings pages.
$string['configtitle'] = 'Photo settings';
// Name of the first settings tab.
$string['generalsettings'] = 'General settings';
// The name of our plugin.
$string['pluginname'] = 'Photo';
// Preset files setting.
$string['presetfiles'] = 'Additional theme preset files';
// Preset files help text.
$string['presetfiles_desc'] = 'Preset files can be used to dramatically alter the appearance of the theme. See <a href=https://docs.moodle.org/dev/Boost_Presets>Boost presets</a> for information on creating and sharing your own preset files, and see the <a href=http://moodle.net/boost>Presets repository</a> for presets that others have shared.';
// Preset setting.
$string['preset'] = 'Theme preset';
// Preset help text.
$string['preset_desc'] = 'Pick a preset to broadly change the look of the theme.';
// Raw SCSS setting.
$string['rawscss'] = 'Raw SCSS';
// Raw SCSS setting help text.
$string['rawscss_desc'] = 'Use this field to provide SCSS or CSS code which will be injected at the end of the style sheet.';
// Raw initial SCSS setting.
$string['rawscsspre'] = 'Raw initial SCSS';
// Raw initial SCSS setting help text.
$string['rawscsspre_desc'] = 'In this field you can provide initialising SCSS code, it will be injected before everything else. Most of the time you will use this setting to define variables.';
// We need to include a lang string for each block region.
$string['region-side-pre'] = 'Right';
</code>

We aren't quite there yet as you will notice if you try and upload a preset file and then choose it. The "theme_boost_get_main_scss_content" function from Boost is expecting the preset files to be stored in a file area for theme_boost only. We need to add this function to our own theme and tweak it.

''config.php''
<code php>
// This is the function that returns the SCSS source for the main file in our theme. We override the boost version because
// we want to allow presets uploaded to our own theme file area to be selected in the preset list.
$THEME->scss = function($theme) {
return theme_photo_get_main_scss_content($theme);
};
</code>

''lib.php''
<code php>
function theme_photo_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');

} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_photo', 'preset', 0, '/', $filename))) {
// This preset file was fetched from the file area for theme_photo and not theme_boost (see the line above).
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

return $scss;
}
</code>

=== Stop and try it out ===
So now what is working and what isn't. Well - everything should be working and you should have a nice new theme extending boost with it's own settings pages. When Boost gets updates for bug fixes your new theme will inherit those fixes as it inherits all the SCSS and templates from theme boost. In addition your new theme will accept preset files and supports all the same features and settings as boost, ready to add more.

== Take it further ==
Now we have our very nice starting point we can start changing or adding features, customising templates and output or tweaking the SCSS.

=== Add some new settings ===

From this point in the tutorial we will start adding features to our theme to extend it and make it AWESOME!

Lets start with a new setting to set a background image on the login page. As you saw earlier, our theme defines it's list of settings in a file called settings.php. See [[Admin settings]] for more information about adding admin settings to any plugin. All of the different kinds of admin settings can be found in lib/adminlib.php. In our case we will want to add a setting which allows an admin to upload an image file. This is an "admin_setting_configstoredfile" and we add it to our theme by adding this code to the settings.php file inside and at the end of the "if ($ADMIN->fulltree) {" condition.

''settings.php''
<code php>
// Login page background setting.
// We use variables for readability.
$name = 'theme_photo/loginbackgroundimage';
$title = get_string('loginbackgroundimage', 'theme_photo');
$description = get_string('loginbackgroundimage_desc', 'theme_photo');
// This creates the new setting.
$setting = new admin_setting_configstoredfile($name, $title, $description, 'loginbackgroundimage');
// This means that theme caches will automatically be cleared when this setting is changed.
$setting->set_updatedcallback('theme_reset_all_caches');
// We always have to add the setting to a page for it to have any effect.
$page->add($setting);
</code>

We also need to add new lang strings to our language file.

"lang/en/theme_photo.php"
<code php>
// Background image for login page.
$string['loginbackgroundimage'] = 'Login page background image';
// Background image for login page.
$string['loginbackgroundimage_desc'] = 'An image that will be stretched to fill the background of the login page.';
</code>

Now we have a new setting that lets us upload a file - but it doesn't actually do anything yet. We need to update the theme to set this image background on the login page.

In order to change the SCSS for our theme we will add 2 additional SCSS files and include them before and after our main scss.

We already have a function in our lib.php file which fetches the main SCSS for our theme. This is a good point to include additional SCSS files. We can add 2 lines to the end of this function to achieve this.

''lib.php''
<code php>
function theme_photo_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');

} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_photo', 'preset', 0, '/', $filename))) {
// This preset file was fetched from the file area for theme_photo and not theme_boost (see the line above).
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

// Pre CSS - this is loaded AFTER any prescss from the setting but before the main scss.
$pre = file_get_contents($CFG->dirroot . '/theme/photo/scss/pre.scss');
// Post CSS - this is loaded AFTER the main scss but before the extra scss from the setting.
$post = file_get_contents($CFG->dirroot . '/theme/photo/scss/post.scss');

// Combine them together.
return $pre . "\n" . $scss . "\n" . $post;
}
</code>

''scss/pre.scss''
<code scss>
// Pre SCSS for the theme.
</code>

''scss/post.scss''
<code scss>
// Post SCSS for the theme.
</code>

==== Why do we use pre and post SCSS? ====
SCSS/SASS is a powerful language for creating CSS. It supports variables, functions, loops just like php. For lots of information and an introduction to SCSS read about [https://en.wikipedia.org/wiki/Sass_(stylesheet_language) Sass on wikipedia].

'''Pre SCSS'''

In Boost we use many variables when creating style rules.

When declaring a variable in SCSS - it is best practice to define it like this:
<code scss>
$mycoolcolour: #FF0 !default;
</code>

What this means is - if this variable is not defined already - set it to the hex value '#FF0';

So by setting this variable in some PRE scss we can override the default value of this variable everywhere it is used. Boost is built with the [https://v4-alpha.getbootstrap.com/ Bootstrap 4 (Alpha 4)] CSS Framework. This is a framework which uses SCSS to provide many extremely useful layouts and components which can be reused without adding specific CSS rules to style every page. Because bootstrap consistently uses variables we can customise many of these components easily by setting the value of the variables before we include the Bootstrap SCSS files.

Many variables are available in /theme/boost/scss/bootstrap/_variables.scss - as an example we can change the look of all buttons and input fields with this one variable:

<code scss>
$border-radius: 8px;
</code>

'''Post SCSS'''

Post SCSS is useful for defining full CSS rules. Because they are included last, they override any previous matching selector with the same [https://en.wikipedia.org/wiki/Cascading_Style_Sheets#Specificity Specificity].

=== Tips for customising Moodle with SCSS (or CSS) ===
Some handy things to know when you are new to theming is that Moodle adds some classes to every page that helps you target a specific page or set of pages with some style rules.

If you inspect a moodle page and look at the body tag you will see a long list of classes e.g.

<code html>
<body id="page-course-view-weeks" class="format-weeks path-course path-course-view safari dir-ltr lang-en yui-skin-sam yui3-skin-sam damyon-per-in-moodle-com--stable_master pagelayout-course course-11 context-497 category-1 drawer-open-left jsenabled">
</code>

You can see from this example that each page gets an id. This is a simplified representation of the current page in the navigation. In this example we are looking at the course page and this course is using the weeks format.

The classes on the body tag can also be used to target a page or set of pages.
* <code>format-weeks</code> The course format
* <code>path-course path-course-view</code> The parts of the bread-crumb leading up to the current page (The current page is what goes in the id)
* <code>safari</code> Some server side guessing of the browser type - it's not accurate so I would not rely on it
* <code>dir-ltr</code> The direction of the current language for the page ( dir-rtl for RTL languages )
* <code>lang-en</code> The current language of the page
* <code>yui*</code> Legacy yui classes - ignore these
* <code>damyon-per-in-moodle-com--stable_master</code> The current hostname for the site + the site name
* <code>pagelayout-course</code> The layout type for the current page
* <code>course-11</code> The id of the current course
* <code>context-497</code> The current context id
* <code>category-1</code> The category for the current course
* <code>drawer-open-left</code> Added / removed when the navigation drawer is opened / closed in Boost
* <code>jsenabled</code> True if the browser supports javascript

[https://docs.moodle.org/dev/Themes_overview#.3Cbody.3E_CSS_id_and_classes Read about Body id and classes].

In our example the page layout is the most useful here as we have a specific page layout for login pages. We can now craft a rule that applies a background image only to login pages using "body.pagelayout-login".

=== How do we refer to an image in SCSS ? ===
So now we can add a rule to the post.scss which will set the background image for the login page. First we need to know how to construct a url to the background images from our stylesheet.

In stylesheets in Moodle we can use a special pix tag to refer to images from our theme. The rule to attach the background image looks like this:
''scss/post.scss''
<code scss>
body.pagelayout-login {
background-image: url([[pix:theme_photo|loginbackgroundimage]]);
background-size: cover;
}
</code>

There are 2 important parts to this tag (the bit in square brackets). The first is "theme_photo". In this case we are passing a component name, the image serving code in theme_config::resolve_image_location() will then look for an image file in several locations. One of these is in "$CFG->dataroot/pix_plugins/$type/$plugin/$image". We can use this to make sure the image gets served correctly by copying the file saved in the setting to this location every time it is updated. (There is an alterative way we could do this by implementing pluginfile.php in our theme - which you can read about in the [[File API]] ).

If we had just passed the value "theme" the image serving code would have looked for the image in the "pix" folder of our theme.

So - we need this final change to copy the image file into our dataroot each time the setting is changed.

In the settings file we will update the callback to a new function which we will define in our lib.php.
''settings.php''
<code php>

// Login page background setting.
// We use variables for readability.
$name = 'theme_photo/loginbackgroundimage';
$title = get_string('loginbackgroundimage', 'theme_photo');
$description = get_string('loginbackgroundimage_desc', 'theme_photo');
// This creates the new setting.
$setting = new admin_setting_configstoredfile($name, $title, $description, 'loginbackgroundimage');
// This function will copy the image into the data_root location it can be served from.
$setting->set_updatedcallback('theme_photo_update_settings_images');
// We always have to add the setting to a page for it to have any effect.
$page->add($setting);
//This will commit the background image setting. If you do not add this line the Login page background setting will not be shown.
$settings->add($page);
</code>

''lib.php''
<code php>
function theme_photo_update_settings_images($settingname) {
global $CFG;

// The setting name that was updated comes as a string like 's_theme_photo_loginbackgroundimage'.
// We split it on '_' characters.
$parts = explode('_', $settingname);
// And get the last one to get the setting name..
$settingname = end($parts);

// Admin settings are stored in system context.
$syscontext = context_system::instance();
// This is the component name the setting is stored in.
$component = 'theme_photo';

// This is the value of the admin setting which is the filename of the uploaded file.
$filename = get_config($component, $settingname);
// We extract the file extension because we want to preserve it.
$extension = substr($filename, strrpos($filename, '.') + 1);

// This is the path in the moodle internal file system.
$fullpath = "/{$syscontext->id}/{$component}/{$settingname}/0{$filename}";
// Get an instance of the moodle file storage.
$fs = get_file_storage();
// This is an efficient way to get a file if we know the exact path.
if ($file = $fs->get_file_by_hash(sha1($fullpath))) {
// We got the stored file - copy it to dataroot.
// This location matches the searched for location in theme_config::resolve_image_location.
$pathname = $CFG->dataroot . '/pix_plugins/theme/photo/' . $settingname . '.' . $extension;

// This pattern matches any previous files with maybe different file extensions.
$pathpattern = $CFG->dataroot . '/pix_plugins/theme/photo/' . $settingname . '.*';

// Make sure this dir exists.
@mkdir($CFG->dataroot . '/pix_plugins/theme/photo/', $CFG->directorypermissions, true);

// Delete any existing files for this setting.
foreach (glob($pathpattern) as $filename) {
@unlink($filename);
}

// Copy the current file to this location.
$file->copy_content_to($pathname);
}

// Reset theme caches.
theme_reset_all_caches();
}
</code>

To edit the setting go to '''Site Administration > Appearance > Photo > Advanced setting'''. You will now see the Login page background setting.
It is now easy to add a new background image setting for every layout type. I can re-use this theme_photo_update_settings_images callback for each one - so all I have to do is add the setting to the settings.php file, add the SCSS rule to the scss/post.scss file and add the lang strings to the language file.

Thats it for this tutorial, but there are [[:Category:Themes| more Themes docs]] to browse.

[[Category:Themes]]

Creating a theme based on boost

2020-07-30T11:01:07Z

Meeth: /* Add some new settings */

{{Moodle 3.2}}
{{Template:Themes}}

This is a tutorial for how to create a new theme in any version of Moodle from 3.2 and later.

Moodle 3.2 introduced a new core theme named "Boost" which is a great starting point for themers wanting to build a modern Moodle theme utilising all the latest features available to themes in Moodle. If you aren't sure where to start, then START HERE! :-)

== Getting started ==
What is a theme? A theme in Moodle is just another type of plugin that can be developed. Themes are responsible for setting up the structure of each page and have the ability to customise the output of any page in Moodle.

This tutorial is based on a working theme named "theme_photo" you can download it or view the source code for it here: https://github.com/damyon/moodle-theme_photo

=== Choosing a name ===
Your new theme will need a name. Try and think of something short and memorable - and make sure it is not a name that has already been used by someone else. A quick search on the moodle.org/plugins can save you a lot of work renaming things later.

Lets call our new example theme "photo" as we will add some settings to allow "photos" in various places in Moodle.

=== Starting files ===
As a plugin, themes must start with the basic structure of a plugin in Moodle. See https://docs.moodle.org/dev/Tutorial#The_skeleton_of_your_plugin for an overview of the files common to all plugins in Moodle.

Following this guide we can start creating our theme. First we create the folder for the new theme under "/theme/" folder in the Moodle root directory.

<code>
/theme/photo/
</code>

Now we need to add some standard plugin files to our theme. First is version.php

''/theme/photo/version.php''

<code php>

<?php
// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// This is the version of the plugin.
$plugin->version = '2016102100';

// This is the version of Moodle this plugin requires.
$plugin->requires = '2016070700';

// This is the component name of the plugin - it always starts with 'theme_'
// for themes and should be the same as the name of the folder.
$plugin->component = 'theme_photo';

// This is a list of plugins, this plugin depends on (and their versions).
$plugin->dependencies = [
'theme_boost' => '2016102100'
];

</code>

We also need a language file so that all our strings can be translated into different languages. The name of this file is the component name of our plugin and it sits in the lang/en/ folder for our plugin. We can include translations of our plugin, but we can also provide translations via the https://lang.moodle.org/ website once our plugin has been published to the plugins database at http://www.moodle.org/plugins/.

''/theme/photo/lang/en/theme_photo.php''

<code php>

<?php
// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// A description shown in the admin theme selector.
$string['choosereadme'] = 'Theme photo is a child theme of Boost. It adds the ability to upload background photos.';
// The name of our plugin.
$string['pluginname'] = 'Photo';
// We need to include a lang string for each block region.
$string['region-side-pre'] = 'Right';
</code>

=== Theme specific files ===
Theme plugins have a few more standard files they need to define.

Themes require a favicon file to show in the address bar. See [[http://docs.moodle.org/en/Favicon Favicon]].

''pix/favicon.ico''

(Image file not shown).

Themes also require an example screenshot to be displayed in the theme selector.

''pix/screenshot.jpg''

(Image file not shown).

Themes require a lib.php file. This file contains callbacks used by various API's in Moodle. Initially this file can be empty, but as we add features to our theme we will need to add some functions here.

''lib.php''
<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// We will add callbacks here as we add features to our theme.
</code>

Theme config goes in a config.php file. This is one of the most important files in our theme. Once we add this file we will be ready to test our theme for the first time.

''config.php''

<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// $THEME is defined before this page is included and we can define settings by adding properties to this global object.

// The first setting we need is the name of the theme. This should be the last part of the component name, and the same
// as the directory name for our theme.
$THEME->name = 'photo';

// This setting list the style sheets we want to include in our theme. Because we want to use SCSS instead of CSS - we won't
// list any style sheets. If we did we would list the name of a file in the /style/ folder for our theme without any css file
// extensions.
$THEME->sheets = [];

// This is a setting that can be used to provide some styling to the content in the TinyMCE text editor. This is no longer the
// default text editor and "Atto" does not need this setting so we won't provide anything. If we did it would work the same
// as the previous setting - listing a file in the /styles/ folder.
$THEME->editor_sheets = [];

// This is a critical setting. We want to inherit from theme_boost because it provides a great starting point for SCSS bootstrap4
// themes. We could add more than one parent here to inherit from multiple parents, and if we did they would be processed in
// order of importance (later themes overriding earlier ones). Things we will inherit from the parent theme include
// styles and mustache templates and some (not all) settings.
$THEME->parents = ['boost'];

// A dock is a way to take blocks out of the page and put them in a persistent floating area on the side of the page. Boost
// does not support a dock so we won't either - but look at bootstrapbase for an example of a theme with a dock.
$THEME->enable_dock = false;

// This is an old setting used to load specific CSS for some YUI JS. We don't need it in Boost based themes because Boost
// provides default styling for the YUI modules that we use. It is not recommended to use this setting anymore.
$THEME->yuicssmodules = array();

// Most themes will use this rendererfactory as this is the one that allows the theme to override any other renderer.
$THEME->rendererfactory = 'theme_overridden_renderer_factory';

// This is a list of blocks that are required to exist on all pages for this theme to function correctly. For example
// bootstrap base requires the settings and navigation blocks because otherwise there would be no way to navigate to all the
// pages in Moodle. Boost does not require these blocks because it provides other ways to navigate built into the theme.
$THEME->requiredblocks = '';

// This is a feature that tells the blocks library not to use the "Add a block" block. We don't want this in boost based themes because
// it forces a block region into the page when editing is enabled and it takes up too much room.
$THEME->addblockposition = BLOCK_ADDBLOCK_POSITION_FLATNAV;
</code>

=== Ready set go! ===
If you have been following along - now we are at the point where we can actually install and test our new theme. Try it now by visiting the admin notifications page to install the new plugin, and then choosing the new theme from the theme selector.

[[https://docs.moodle.org/en/Standard_themes#Theme_selector Theme selector]]

When you choose the new theme - you will find that it looks exactly the same as Boost. At this point with our minimal configuration - we are inheriting almost everything from our parent theme including styles and templates. You will notice though that we don't inherit the settings from our parent theme. If you choose a different preset in Boost - it is not applied in this child theme.

<div class="warningbox">
Note: make sure your config.php file contains $THEME->hidefromselector = false; (or at least set to false) or else, your theme wont show up in theme selector.
</div>

=== What if I want the settings too? ===

<div class="warningbox">
This section is included for completeness - but it is not recommended for themes to utilise settings from their parents. To find out how to duplicate the settings from the parent theme so they operate independently skip to [[#Duplicate the settings from Boost]].
</div>

If I want the settings from Boost to apply to my child theme as well I need to know a bit about how each of the settings in Boost is applied to make them work in my child theme.

'''Setting 1 - preset.'''

The "preset" file is the file that is used as the main file for scss compilation. In Boost this is controlled by the theme config value:

''theme_boost/config.php''
<code php>
$THEME->scss = function($theme) {
return theme_boost_get_main_scss_content($theme);
};
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');
} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_boost', 'preset', 0, '/', $filename))) {
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

return $scss;
}
</code>

What this function is doing is checking for a theme setting "preset" and either fetching the file from Moodles internal file storage, or from the /preset/ folder. The function then returns the contents of this file.

It does not automatically work for our child theme because we have no setting named "preset" in our child theme and this code is not searching the theme parents for the setting. If we wanted it to apply we could do this in our child theme:

''config.php''
<code php>
// This setting defines the main scss file for our theme to be compiled. We could set it to a static file in the scss folder or to a function which returns the SCSS based on theme settings.
$THEME->scss = function($theme) {

// We need to load the config for our parent theme because that is where the preset setting is defined.
$parentconfig = theme_config::load('boost');
// Call a function from our parent themes lib.php file to fetch the content of the themes main SCSS file based on it's own config, not ours.
return theme_boost_get_main_scss_content($parentconfig);
};
</code>

'''Settings 2+3 brandcolor + scsspre'''

The way these settings work is they generate a chunk of SCSS to be prepended to the main scss file. In boost they work like this:

''theme_boost/config.php''
<code php>
$THEME->prescsscallback = 'theme_boost_get_pre_scss';
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_pre_scss($theme) {
global $CFG;

$scss = '';
$configurable = [
// Config key => [variableName, ...].
'brandcolor' => ['brand-primary'],
];

// Prepend variables first.
foreach ($configurable as $configkey => $targets) {
$value = isset($theme->settings->{$configkey}) ? $theme->settings->{$configkey} : null;
if (empty($value)) {
continue;
}
array_map(function($target) use (&$scss, $value) {
$scss .= '$' . $target . ': ' . $value . ";\n";
}, (array) $targets);
}

// Prepend pre-scss.
if (!empty($theme->settings->scsspre)) {
$scss .= $theme->settings->scsspre;
}

return $scss;
}
</code>

What this code is doing is:
* looping over a list of theme settings that map to a SCSS variable and building some SCSS to initialise that variable from the setting. In Boost there is only one * brandprimary - but if we wanted to expose more bootstrap variables as theme settings we could use this function as a template in our child theme and add more settings to the $configurable array.
* Adding all of the raw SCSS from the scsspre theme setting
* Returning the whole thing as a string to be added before the main scss file.

If we want this code to work in our child theme, using the settings from Boost we could do this:

''config.php''
<code php>
// This is a function that returns some SCSS as a string to prepend to the main SCSS file.
$THEME->prescsscallback = 'theme_photo_get_pre_scss';
</code>

''lib.php''
<code php>
// Function to return the SCSS to prepend to our main SCSS for this theme.
// Note the function name starts with the component name because this is a global function and we don't want namespace clashes.
function theme_photo_get_pre_scss($theme) {
// Load the settings from the parent.
$theme = theme_config::load('boost');
// Call the parent themes get_pre_scss function.
return theme_boost_get_pre_scss($theme);
}
</code>

'''Setting 4 scss (post)'''

The final setting from Boost is a raw text field which adds SCSS to the end of the main SCSS file. This is a useful place to add style rules as they will override previously defined styles with the same specificity. It is applied in Boost by the following lines:

''theme_boost/config.php''
<code php>
$THEME->extrascsscallback = 'theme_boost_get_extra_scss';
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_extra_scss($theme) {
return !empty($theme->settings->scss) ? $theme->settings->scss : '';
}
</code>

This is just returning the value of the setting as a string.

To make this setting apply in our child theme too - we use similar code to the previous sections.

''config.php''
<code php>
// This is a function that returns some SCSS as a string to append to the main SCSS file.
$THEME->extrascsscallback = 'theme_photo_get_extra_scss';
</code>

''lib.php''
<code php>
// Function to return the SCSS to append to our main SCSS for this theme.
// Note the function name starts with the component name because this is a global function and we don't want namespace clashes.
function theme_photo_get_extra_scss($theme) {
// Load the settings from the parent.
$theme = theme_config::load('boost');
// Call the parent themes get_extra_scss function.
return theme_boost_get_extra_scss($theme);
}
</code>

=== Duplicate the settings from Boost ===

This is the recommended way to extend boost as your child theme will not be affected by changes to the Boost settings, and both themes can be in use with different settings applied.

All that needs to happen is to create theme settings in the child theme that match each of the settings in the parent theme. You will need to add matching language strings for each of these settings in the language file.

This example shows how to do it - We are re-using the nice looking theme_boost_admin_settingspage_tabs class from boost and creating duplicate versions of each of the settings.

''settings.php''

<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// This is used for performance, we don't need to know about these settings on every page in Moodle, only when
// we are looking at the admin settings pages.
if ($ADMIN->fulltree) {

// Boost provides a nice setting page which splits settings onto separate tabs. We want to use it here.
$settings = new theme_boost_admin_settingspage_tabs('themesettingphoto', get_string('configtitle', 'theme_photo'));

// Each page is a tab - the first is the "General" tab.
$page = new admin_settingpage('theme_photo_general', get_string('generalsettings', 'theme_photo'));

// Replicate the preset setting from boost.
$name = 'theme_photo/preset';
$title = get_string('preset', 'theme_photo');
$description = get_string('preset_desc', 'theme_photo');
$default = 'default.scss';

// We list files in our own file area to add to the drop down. We will provide our own function to
// load all the presets from the correct paths.
$context = context_system::instance();
$fs = get_file_storage();
$files = $fs->get_area_files($context->id, 'theme_photo', 'preset', 0, 'itemid, filepath, filename', false);

$choices = [];
foreach ($files as $file) {
$choices[$file->get_filename()] = $file->get_filename();
}
// These are the built in presets from Boost.
$choices['default.scss'] = 'default.scss';
$choices['plain.scss'] = 'plain.scss';

$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Preset files setting.
$name = 'theme_photo/presetfiles';
$title = get_string('presetfiles','theme_photo');
$description = get_string('presetfiles_desc', 'theme_photo');

$setting = new admin_setting_configstoredfile($name, $title, $description, 'preset', 0,
array('maxfiles' => 20, 'accepted_types' => array('.scss')));
$page->add($setting);

// Variable $brand-color.
// We use an empty default value because the default colour should come from the preset.
$name = 'theme_photo/brandcolor';
$title = get_string('brandcolor', 'theme_photo');
$description = get_string('brandcolor_desc', 'theme_photo');
$setting = new admin_setting_configcolourpicker($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Must add the page after definiting all the settings!
$settings->add($page);

// Advanced settings.
$page = new admin_settingpage('theme_photo_advanced', get_string('advancedsettings', 'theme_photo'));

// Raw SCSS to include before the content.
$setting = new admin_setting_configtextarea('theme_photo/scsspre',
get_string('rawscsspre', 'theme_photo'), get_string('rawscsspre_desc', 'theme_photo'), '', PARAM_RAW);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Raw SCSS to include after the content.
$setting = new admin_setting_configtextarea('theme_photo/scss', get_string('rawscss', 'theme_photo'),
get_string('rawscss_desc', 'theme_photo'), '', PARAM_RAW);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

$settings->add($page);
}
</code>

''lang/en/theme_photo.php''
<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();
// The name of the second tab in the theme settings.
$string['advancedsettings'] = 'Advanced settings';
// The brand colour setting.
$string['brandcolor'] = 'Brand colour';
// The brand colour setting description.
$string['brandcolor_desc'] = 'The accent colour.';
// A description shown in the admin theme selector.
$string['choosereadme'] = 'Theme photo is a child theme of Boost. It adds the ability to upload background photos.';
// Name of the settings pages.
$string['configtitle'] = 'Photo settings';
// Name of the first settings tab.
$string['generalsettings'] = 'General settings';
// The name of our plugin.
$string['pluginname'] = 'Photo';
// Preset files setting.
$string['presetfiles'] = 'Additional theme preset files';
// Preset files help text.
$string['presetfiles_desc'] = 'Preset files can be used to dramatically alter the appearance of the theme. See <a href=https://docs.moodle.org/dev/Boost_Presets>Boost presets</a> for information on creating and sharing your own preset files, and see the <a href=http://moodle.net/boost>Presets repository</a> for presets that others have shared.';
// Preset setting.
$string['preset'] = 'Theme preset';
// Preset help text.
$string['preset_desc'] = 'Pick a preset to broadly change the look of the theme.';
// Raw SCSS setting.
$string['rawscss'] = 'Raw SCSS';
// Raw SCSS setting help text.
$string['rawscss_desc'] = 'Use this field to provide SCSS or CSS code which will be injected at the end of the style sheet.';
// Raw initial SCSS setting.
$string['rawscsspre'] = 'Raw initial SCSS';
// Raw initial SCSS setting help text.
$string['rawscsspre_desc'] = 'In this field you can provide initialising SCSS code, it will be injected before everything else. Most of the time you will use this setting to define variables.';
// We need to include a lang string for each block region.
$string['region-side-pre'] = 'Right';
</code>

We aren't quite there yet as you will notice if you try and upload a preset file and then choose it. The "theme_boost_get_main_scss_content" function from Boost is expecting the preset files to be stored in a file area for theme_boost only. We need to add this function to our own theme and tweak it.

''config.php''
<code php>
// This is the function that returns the SCSS source for the main file in our theme. We override the boost version because
// we want to allow presets uploaded to our own theme file area to be selected in the preset list.
$THEME->scss = function($theme) {
return theme_photo_get_main_scss_content($theme);
};
</code>

''lib.php''
<code php>
function theme_photo_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');

} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_photo', 'preset', 0, '/', $filename))) {
// This preset file was fetched from the file area for theme_photo and not theme_boost (see the line above).
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

return $scss;
}
</code>

=== Stop and try it out ===
So now what is working and what isn't. Well - everything should be working and you should have a nice new theme extending boost with it's own settings pages. When Boost gets updates for bug fixes your new theme will inherit those fixes as it inherits all the SCSS and templates from theme boost. In addition your new theme will accept preset files and supports all the same features and settings as boost, ready to add more.

== Take it further ==
Now we have our very nice starting point we can start changing or adding features, customising templates and output or tweaking the SCSS.

=== Add some new settings ===

From this point in the tutorial we will start adding features to our theme to extend it and make it AWESOME!

Lets start with a new setting to set a background image on the login page. As you saw earlier, our theme defines it's list of settings in a file called settings.php. See [[Admin settings]] for more information about adding admin settings to any plugin. All of the different kinds of admin settings can be found in lib/adminlib.php. In our case we will want to add a setting which allows an admin to upload an image file. This is an "admin_setting_configstoredfile" and we add it to our theme by adding this code to the settings.php file inside and at the end of the "if ($ADMIN->fulltree) {" condition.

''settings.php''
<code php>
// Login page background setting.
// We use variables for readability.
$name = 'theme_photo/loginbackgroundimage';
$title = get_string('loginbackgroundimage', 'theme_photo');
$description = get_string('loginbackgroundimage_desc', 'theme_photo');
// This creates the new setting.
$setting = new admin_setting_configstoredfile($name, $title, $description, 'loginbackgroundimage');
// This means that theme caches will automatically be cleared when this setting is changed.
$setting->set_updatedcallback('theme_reset_all_caches');
// We always have to add the setting to a page for it to have any effect.
$page->add($setting);
</code>

We also need to add new lang strings to our language file.

"lang/en/theme_photo.php"
<code php>
// Background image for login page.
$string['loginbackgroundimage'] = 'Login page background image';
// Background image for login page.
$string['loginbackgroundimage_desc'] = 'An image that will be stretched to fill the background of the login page.';
</code>

Now we have a new setting that lets us upload a file - but it doesn't actually do anything yet. We need to update the theme to set this image background on the login page.

In order to change the SCSS for our theme we will add 2 additional SCSS files and include them before and after our main scss.

We already have a function in our lib.php file which fetches the main SCSS for our theme. This is a good point to include additional SCSS files. We can add 2 lines to the end of this function to achieve this.

''lib.php''
<code php>
function theme_photo_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');

} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_photo', 'preset', 0, '/', $filename))) {
// This preset file was fetched from the file area for theme_photo and not theme_boost (see the line above).
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

// Pre CSS - this is loaded AFTER any prescss from the setting but before the main scss.
$pre = file_get_contents($CFG->dirroot . '/theme/photo/scss/pre.scss');
// Post CSS - this is loaded AFTER the main scss but before the extra scss from the setting.
$post = file_get_contents($CFG->dirroot . '/theme/photo/scss/post.scss');

// Combine them together.
return $pre . "\n" . $scss . "\n" . $post;
}
</code>

''scss/pre.scss''
<code scss>
// Pre SCSS for the theme.
</code>

''scss/post.scss''
<code scss>
// Post SCSS for the theme.
</code>

==== Why do we use pre and post SCSS? ====
SCSS/SASS is a powerful language for creating CSS. It supports variables, functions, loops just like php. For lots of information and an introduction to SCSS read about [https://en.wikipedia.org/wiki/Sass_(stylesheet_language) Sass on wikipedia].

'''Pre SCSS'''

In Boost we use many variables when creating style rules.

When declaring a variable in SCSS - it is best practice to define it like this:
<code scss>
$mycoolcolour: #FF0 !default;
</code>

What this means is - if this variable is not defined already - set it to the hex value '#FF0';

So by setting this variable in some PRE scss we can override the default value of this variable everywhere it is used. Boost is built with the [https://v4-alpha.getbootstrap.com/ Bootstrap 4 (Alpha 4)] CSS Framework. This is a framework which uses SCSS to provide many extremely useful layouts and components which can be reused without adding specific CSS rules to style every page. Because bootstrap consistently uses variables we can customise many of these components easily by setting the value of the variables before we include the Bootstrap SCSS files.

Many variables are available in /theme/boost/scss/bootstrap/_variables.scss - as an example we can change the look of all buttons and input fields with this one variable:

<code scss>
$border-radius: 8px;
</code>

'''Post SCSS'''

Post SCSS is useful for defining full CSS rules. Because they are included last, they override any previous matching selector with the same [https://en.wikipedia.org/wiki/Cascading_Style_Sheets#Specificity Specificity].

=== Tips for customising Moodle with SCSS (or CSS) ===
Some handy things to know when you are new to theming is that Moodle adds some classes to every page that helps you target a specific page or set of pages with some style rules.

If you inspect a moodle page and look at the body tag you will see a long list of classes e.g.

<code html>
<body id="page-course-view-weeks" class="format-weeks path-course path-course-view safari dir-ltr lang-en yui-skin-sam yui3-skin-sam damyon-per-in-moodle-com--stable_master pagelayout-course course-11 context-497 category-1 drawer-open-left jsenabled">
</code>

You can see from this example that each page gets an id. This is a simplified representation of the current page in the navigation. In this example we are looking at the course page and this course is using the weeks format.

The classes on the body tag can also be used to target a page or set of pages.
* <code>format-weeks</code> The course format
* <code>path-course path-course-view</code> The parts of the bread-crumb leading up to the current page (The current page is what goes in the id)
* <code>safari</code> Some server side guessing of the browser type - it's not accurate so I would not rely on it
* <code>dir-ltr</code> The direction of the current language for the page ( dir-rtl for RTL languages )
* <code>lang-en</code> The current language of the page
* <code>yui*</code> Legacy yui classes - ignore these
* <code>damyon-per-in-moodle-com--stable_master</code> The current hostname for the site + the site name
* <code>pagelayout-course</code> The layout type for the current page
* <code>course-11</code> The id of the current course
* <code>context-497</code> The current context id
* <code>category-1</code> The category for the current course
* <code>drawer-open-left</code> Added / removed when the navigation drawer is opened / closed in Boost
* <code>jsenabled</code> True if the browser supports javascript

[https://docs.moodle.org/dev/Themes_overview#.3Cbody.3E_CSS_id_and_classes Read about Body id and classes].

In our example the page layout is the most useful here as we have a specific page layout for login pages. We can now craft a rule that applies a background image only to login pages using "body.pagelayout-login".

=== How do we refer to an image in SCSS ? ===
So now we can add a rule to the post.scss which will set the background image for the login page. First we need to know how to construct a url to the background images from our stylesheet.

In stylesheets in Moodle we can use a special pix tag to refer to images from our theme. The rule to attach the background image looks like this:
''scss/post.scss''
<code scss>
body.pagelayout-login {
background-image: url([[pix:theme_photo|loginbackgroundimage]]);
background-size: cover;
}
</code>

There are 2 important parts to this tag (the bit in square brackets). The first is "theme_photo". In this case we are passing a component name, the image serving code in theme_config::resolve_image_location() will then look for an image file in several locations. One of these is in "$CFG->dataroot/pix_plugins/$type/$plugin/$image". We can use this to make sure the image gets served correctly by copying the file saved in the setting to this location every time it is updated. (There is an alterative way we could do this by implementing pluginfile.php in our theme - which you can read about in the [[File API]] ).

If we had just passed the value "theme" the image serving code would have looked for the image in the "pix" folder of our theme.

So - we need this final change to copy the image file into our dataroot each time the setting is changed.

In the settings file we will update the callback to a new function which we will define in our lib.php.
''settings.php''
<code php>

// Login page background setting.
// We use variables for readability.
$name = 'theme_photo/loginbackgroundimage';
$title = get_string('loginbackgroundimage', 'theme_photo');
$description = get_string('loginbackgroundimage_desc', 'theme_photo');
// This creates the new setting.
$setting = new admin_setting_configstoredfile($name, $title, $description, 'loginbackgroundimage');
// This function will copy the image into the data_root location it can be served from.
$setting->set_updatedcallback('theme_photo_update_settings_images');
// We always have to add the setting to a page for it to have any effect.
$page->add($setting);
//This will commit the background image setting. If you do not add this line the Login page background setting will not be shown.
$settings->add($page);
</code>

''lib.php''
<code php>
function theme_photo_update_settings_images($settingname) {
global $CFG;

// The setting name that was updated comes as a string like 's_theme_photo_loginbackgroundimage'.
// We split it on '_' characters.
$parts = explode('_', $settingname);
// And get the last one to get the setting name..
$settingname = end($parts);

// Admin settings are stored in system context.
$syscontext = context_system::instance();
// This is the component name the setting is stored in.
$component = 'theme_photo';

// This is the value of the admin setting which is the filename of the uploaded file.
$filename = get_config($component, $settingname);
// We extract the file extension because we want to preserve it.
$extension = substr($filename, strrpos($filename, '.') + 1);

// This is the path in the moodle internal file system.
$fullpath = "/{$syscontext->id}/{$component}/{$settingname}/0{$filename}";
// Get an instance of the moodle file storage.
$fs = get_file_storage();
// This is an efficient way to get a file if we know the exact path.
if ($file = $fs->get_file_by_hash(sha1($fullpath))) {
// We got the stored file - copy it to dataroot.
// This location matches the searched for location in theme_config::resolve_image_location.
$pathname = $CFG->dataroot . '/pix_plugins/theme/photo/' . $settingname . '.' . $extension;

// This pattern matches any previous files with maybe different file extensions.
$pathpattern = $CFG->dataroot . '/pix_plugins/theme/photo/' . $settingname . '.*';

// Make sure this dir exists.
@mkdir($CFG->dataroot . '/pix_plugins/theme/photo/', $CFG->directorypermissions, true);

// Delete any existing files for this setting.
foreach (glob($pathpattern) as $filename) {
@unlink($filename);
}

// Copy the current file to this location.
$file->copy_content_to($pathname);
}

// Reset theme caches.
theme_reset_all_caches();
}
</code>

To edit the setting go to '''Site Administration > Appearance > Photo > Advanced setting'''. You will now see the Login page background setting.
It is now easy to add a new background image setting for every layout type. I can re-use this theme_photo_update_settings_images callback for each one - so all I have to do is add the setting to the settings.php file, add the SCSS rule to the scss/post.scss file and add the lang strings to the language file.

Thats it for this tutorial, but there are [[:Category:Themes| more Themes docs]] to browse.

[[Category:Themes]]

Creating a theme based on boost

2020-07-30T10:57:59Z

Meeth: /* How do we refer to an image in SCSS ? */

{{Moodle 3.2}}
{{Template:Themes}}

This is a tutorial for how to create a new theme in any version of Moodle from 3.2 and later.

Moodle 3.2 introduced a new core theme named "Boost" which is a great starting point for themers wanting to build a modern Moodle theme utilising all the latest features available to themes in Moodle. If you aren't sure where to start, then START HERE! :-)

== Getting started ==
What is a theme? A theme in Moodle is just another type of plugin that can be developed. Themes are responsible for setting up the structure of each page and have the ability to customise the output of any page in Moodle.

This tutorial is based on a working theme named "theme_photo" you can download it or view the source code for it here: https://github.com/damyon/moodle-theme_photo

=== Choosing a name ===
Your new theme will need a name. Try and think of something short and memorable - and make sure it is not a name that has already been used by someone else. A quick search on the moodle.org/plugins can save you a lot of work renaming things later.

Lets call our new example theme "photo" as we will add some settings to allow "photos" in various places in Moodle.

=== Starting files ===
As a plugin, themes must start with the basic structure of a plugin in Moodle. See https://docs.moodle.org/dev/Tutorial#The_skeleton_of_your_plugin for an overview of the files common to all plugins in Moodle.

Following this guide we can start creating our theme. First we create the folder for the new theme under "/theme/" folder in the Moodle root directory.

<code>
/theme/photo/
</code>

Now we need to add some standard plugin files to our theme. First is version.php

''/theme/photo/version.php''

<code php>

<?php
// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// This is the version of the plugin.
$plugin->version = '2016102100';

// This is the version of Moodle this plugin requires.
$plugin->requires = '2016070700';

// This is the component name of the plugin - it always starts with 'theme_'
// for themes and should be the same as the name of the folder.
$plugin->component = 'theme_photo';

// This is a list of plugins, this plugin depends on (and their versions).
$plugin->dependencies = [
'theme_boost' => '2016102100'
];

</code>

We also need a language file so that all our strings can be translated into different languages. The name of this file is the component name of our plugin and it sits in the lang/en/ folder for our plugin. We can include translations of our plugin, but we can also provide translations via the https://lang.moodle.org/ website once our plugin has been published to the plugins database at http://www.moodle.org/plugins/.

''/theme/photo/lang/en/theme_photo.php''

<code php>

<?php
// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// A description shown in the admin theme selector.
$string['choosereadme'] = 'Theme photo is a child theme of Boost. It adds the ability to upload background photos.';
// The name of our plugin.
$string['pluginname'] = 'Photo';
// We need to include a lang string for each block region.
$string['region-side-pre'] = 'Right';
</code>

=== Theme specific files ===
Theme plugins have a few more standard files they need to define.

Themes require a favicon file to show in the address bar. See [[http://docs.moodle.org/en/Favicon Favicon]].

''pix/favicon.ico''

(Image file not shown).

Themes also require an example screenshot to be displayed in the theme selector.

''pix/screenshot.jpg''

(Image file not shown).

Themes require a lib.php file. This file contains callbacks used by various API's in Moodle. Initially this file can be empty, but as we add features to our theme we will need to add some functions here.

''lib.php''
<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// We will add callbacks here as we add features to our theme.
</code>

Theme config goes in a config.php file. This is one of the most important files in our theme. Once we add this file we will be ready to test our theme for the first time.

''config.php''

<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// $THEME is defined before this page is included and we can define settings by adding properties to this global object.

// The first setting we need is the name of the theme. This should be the last part of the component name, and the same
// as the directory name for our theme.
$THEME->name = 'photo';

// This setting list the style sheets we want to include in our theme. Because we want to use SCSS instead of CSS - we won't
// list any style sheets. If we did we would list the name of a file in the /style/ folder for our theme without any css file
// extensions.
$THEME->sheets = [];

// This is a setting that can be used to provide some styling to the content in the TinyMCE text editor. This is no longer the
// default text editor and "Atto" does not need this setting so we won't provide anything. If we did it would work the same
// as the previous setting - listing a file in the /styles/ folder.
$THEME->editor_sheets = [];

// This is a critical setting. We want to inherit from theme_boost because it provides a great starting point for SCSS bootstrap4
// themes. We could add more than one parent here to inherit from multiple parents, and if we did they would be processed in
// order of importance (later themes overriding earlier ones). Things we will inherit from the parent theme include
// styles and mustache templates and some (not all) settings.
$THEME->parents = ['boost'];

// A dock is a way to take blocks out of the page and put them in a persistent floating area on the side of the page. Boost
// does not support a dock so we won't either - but look at bootstrapbase for an example of a theme with a dock.
$THEME->enable_dock = false;

// This is an old setting used to load specific CSS for some YUI JS. We don't need it in Boost based themes because Boost
// provides default styling for the YUI modules that we use. It is not recommended to use this setting anymore.
$THEME->yuicssmodules = array();

// Most themes will use this rendererfactory as this is the one that allows the theme to override any other renderer.
$THEME->rendererfactory = 'theme_overridden_renderer_factory';

// This is a list of blocks that are required to exist on all pages for this theme to function correctly. For example
// bootstrap base requires the settings and navigation blocks because otherwise there would be no way to navigate to all the
// pages in Moodle. Boost does not require these blocks because it provides other ways to navigate built into the theme.
$THEME->requiredblocks = '';

// This is a feature that tells the blocks library not to use the "Add a block" block. We don't want this in boost based themes because
// it forces a block region into the page when editing is enabled and it takes up too much room.
$THEME->addblockposition = BLOCK_ADDBLOCK_POSITION_FLATNAV;
</code>

=== Ready set go! ===
If you have been following along - now we are at the point where we can actually install and test our new theme. Try it now by visiting the admin notifications page to install the new plugin, and then choosing the new theme from the theme selector.

[[https://docs.moodle.org/en/Standard_themes#Theme_selector Theme selector]]

When you choose the new theme - you will find that it looks exactly the same as Boost. At this point with our minimal configuration - we are inheriting almost everything from our parent theme including styles and templates. You will notice though that we don't inherit the settings from our parent theme. If you choose a different preset in Boost - it is not applied in this child theme.

<div class="warningbox">
Note: make sure your config.php file contains $THEME->hidefromselector = false; (or at least set to false) or else, your theme wont show up in theme selector.
</div>

=== What if I want the settings too? ===

<div class="warningbox">
This section is included for completeness - but it is not recommended for themes to utilise settings from their parents. To find out how to duplicate the settings from the parent theme so they operate independently skip to [[#Duplicate the settings from Boost]].
</div>

If I want the settings from Boost to apply to my child theme as well I need to know a bit about how each of the settings in Boost is applied to make them work in my child theme.

'''Setting 1 - preset.'''

The "preset" file is the file that is used as the main file for scss compilation. In Boost this is controlled by the theme config value:

''theme_boost/config.php''
<code php>
$THEME->scss = function($theme) {
return theme_boost_get_main_scss_content($theme);
};
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');
} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_boost', 'preset', 0, '/', $filename))) {
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

return $scss;
}
</code>

What this function is doing is checking for a theme setting "preset" and either fetching the file from Moodles internal file storage, or from the /preset/ folder. The function then returns the contents of this file.

It does not automatically work for our child theme because we have no setting named "preset" in our child theme and this code is not searching the theme parents for the setting. If we wanted it to apply we could do this in our child theme:

''config.php''
<code php>
// This setting defines the main scss file for our theme to be compiled. We could set it to a static file in the scss folder or to a function which returns the SCSS based on theme settings.
$THEME->scss = function($theme) {

// We need to load the config for our parent theme because that is where the preset setting is defined.
$parentconfig = theme_config::load('boost');
// Call a function from our parent themes lib.php file to fetch the content of the themes main SCSS file based on it's own config, not ours.
return theme_boost_get_main_scss_content($parentconfig);
};
</code>

'''Settings 2+3 brandcolor + scsspre'''

The way these settings work is they generate a chunk of SCSS to be prepended to the main scss file. In boost they work like this:

''theme_boost/config.php''
<code php>
$THEME->prescsscallback = 'theme_boost_get_pre_scss';
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_pre_scss($theme) {
global $CFG;

$scss = '';
$configurable = [
// Config key => [variableName, ...].
'brandcolor' => ['brand-primary'],
];

// Prepend variables first.
foreach ($configurable as $configkey => $targets) {
$value = isset($theme->settings->{$configkey}) ? $theme->settings->{$configkey} : null;
if (empty($value)) {
continue;
}
array_map(function($target) use (&$scss, $value) {
$scss .= '$' . $target . ': ' . $value . ";\n";
}, (array) $targets);
}

// Prepend pre-scss.
if (!empty($theme->settings->scsspre)) {
$scss .= $theme->settings->scsspre;
}

return $scss;
}
</code>

What this code is doing is:
* looping over a list of theme settings that map to a SCSS variable and building some SCSS to initialise that variable from the setting. In Boost there is only one * brandprimary - but if we wanted to expose more bootstrap variables as theme settings we could use this function as a template in our child theme and add more settings to the $configurable array.
* Adding all of the raw SCSS from the scsspre theme setting
* Returning the whole thing as a string to be added before the main scss file.

If we want this code to work in our child theme, using the settings from Boost we could do this:

''config.php''
<code php>
// This is a function that returns some SCSS as a string to prepend to the main SCSS file.
$THEME->prescsscallback = 'theme_photo_get_pre_scss';
</code>

''lib.php''
<code php>
// Function to return the SCSS to prepend to our main SCSS for this theme.
// Note the function name starts with the component name because this is a global function and we don't want namespace clashes.
function theme_photo_get_pre_scss($theme) {
// Load the settings from the parent.
$theme = theme_config::load('boost');
// Call the parent themes get_pre_scss function.
return theme_boost_get_pre_scss($theme);
}
</code>

'''Setting 4 scss (post)'''

The final setting from Boost is a raw text field which adds SCSS to the end of the main SCSS file. This is a useful place to add style rules as they will override previously defined styles with the same specificity. It is applied in Boost by the following lines:

''theme_boost/config.php''
<code php>
$THEME->extrascsscallback = 'theme_boost_get_extra_scss';
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_extra_scss($theme) {
return !empty($theme->settings->scss) ? $theme->settings->scss : '';
}
</code>

This is just returning the value of the setting as a string.

To make this setting apply in our child theme too - we use similar code to the previous sections.

''config.php''
<code php>
// This is a function that returns some SCSS as a string to append to the main SCSS file.
$THEME->extrascsscallback = 'theme_photo_get_extra_scss';
</code>

''lib.php''
<code php>
// Function to return the SCSS to append to our main SCSS for this theme.
// Note the function name starts with the component name because this is a global function and we don't want namespace clashes.
function theme_photo_get_extra_scss($theme) {
// Load the settings from the parent.
$theme = theme_config::load('boost');
// Call the parent themes get_extra_scss function.
return theme_boost_get_extra_scss($theme);
}
</code>

=== Duplicate the settings from Boost ===

This is the recommended way to extend boost as your child theme will not be affected by changes to the Boost settings, and both themes can be in use with different settings applied.

All that needs to happen is to create theme settings in the child theme that match each of the settings in the parent theme. You will need to add matching language strings for each of these settings in the language file.

This example shows how to do it - We are re-using the nice looking theme_boost_admin_settingspage_tabs class from boost and creating duplicate versions of each of the settings.

''settings.php''

<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// This is used for performance, we don't need to know about these settings on every page in Moodle, only when
// we are looking at the admin settings pages.
if ($ADMIN->fulltree) {

// Boost provides a nice setting page which splits settings onto separate tabs. We want to use it here.
$settings = new theme_boost_admin_settingspage_tabs('themesettingphoto', get_string('configtitle', 'theme_photo'));

// Each page is a tab - the first is the "General" tab.
$page = new admin_settingpage('theme_photo_general', get_string('generalsettings', 'theme_photo'));

// Replicate the preset setting from boost.
$name = 'theme_photo/preset';
$title = get_string('preset', 'theme_photo');
$description = get_string('preset_desc', 'theme_photo');
$default = 'default.scss';

// We list files in our own file area to add to the drop down. We will provide our own function to
// load all the presets from the correct paths.
$context = context_system::instance();
$fs = get_file_storage();
$files = $fs->get_area_files($context->id, 'theme_photo', 'preset', 0, 'itemid, filepath, filename', false);

$choices = [];
foreach ($files as $file) {
$choices[$file->get_filename()] = $file->get_filename();
}
// These are the built in presets from Boost.
$choices['default.scss'] = 'default.scss';
$choices['plain.scss'] = 'plain.scss';

$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Preset files setting.
$name = 'theme_photo/presetfiles';
$title = get_string('presetfiles','theme_photo');
$description = get_string('presetfiles_desc', 'theme_photo');

$setting = new admin_setting_configstoredfile($name, $title, $description, 'preset', 0,
array('maxfiles' => 20, 'accepted_types' => array('.scss')));
$page->add($setting);

// Variable $brand-color.
// We use an empty default value because the default colour should come from the preset.
$name = 'theme_photo/brandcolor';
$title = get_string('brandcolor', 'theme_photo');
$description = get_string('brandcolor_desc', 'theme_photo');
$setting = new admin_setting_configcolourpicker($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Must add the page after definiting all the settings!
$settings->add($page);

// Advanced settings.
$page = new admin_settingpage('theme_photo_advanced', get_string('advancedsettings', 'theme_photo'));

// Raw SCSS to include before the content.
$setting = new admin_setting_configtextarea('theme_photo/scsspre',
get_string('rawscsspre', 'theme_photo'), get_string('rawscsspre_desc', 'theme_photo'), '', PARAM_RAW);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Raw SCSS to include after the content.
$setting = new admin_setting_configtextarea('theme_photo/scss', get_string('rawscss', 'theme_photo'),
get_string('rawscss_desc', 'theme_photo'), '', PARAM_RAW);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

$settings->add($page);
}
</code>

''lang/en/theme_photo.php''
<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();
// The name of the second tab in the theme settings.
$string['advancedsettings'] = 'Advanced settings';
// The brand colour setting.
$string['brandcolor'] = 'Brand colour';
// The brand colour setting description.
$string['brandcolor_desc'] = 'The accent colour.';
// A description shown in the admin theme selector.
$string['choosereadme'] = 'Theme photo is a child theme of Boost. It adds the ability to upload background photos.';
// Name of the settings pages.
$string['configtitle'] = 'Photo settings';
// Name of the first settings tab.
$string['generalsettings'] = 'General settings';
// The name of our plugin.
$string['pluginname'] = 'Photo';
// Preset files setting.
$string['presetfiles'] = 'Additional theme preset files';
// Preset files help text.
$string['presetfiles_desc'] = 'Preset files can be used to dramatically alter the appearance of the theme. See <a href=https://docs.moodle.org/dev/Boost_Presets>Boost presets</a> for information on creating and sharing your own preset files, and see the <a href=http://moodle.net/boost>Presets repository</a> for presets that others have shared.';
// Preset setting.
$string['preset'] = 'Theme preset';
// Preset help text.
$string['preset_desc'] = 'Pick a preset to broadly change the look of the theme.';
// Raw SCSS setting.
$string['rawscss'] = 'Raw SCSS';
// Raw SCSS setting help text.
$string['rawscss_desc'] = 'Use this field to provide SCSS or CSS code which will be injected at the end of the style sheet.';
// Raw initial SCSS setting.
$string['rawscsspre'] = 'Raw initial SCSS';
// Raw initial SCSS setting help text.
$string['rawscsspre_desc'] = 'In this field you can provide initialising SCSS code, it will be injected before everything else. Most of the time you will use this setting to define variables.';
// We need to include a lang string for each block region.
$string['region-side-pre'] = 'Right';
</code>

We aren't quite there yet as you will notice if you try and upload a preset file and then choose it. The "theme_boost_get_main_scss_content" function from Boost is expecting the preset files to be stored in a file area for theme_boost only. We need to add this function to our own theme and tweak it.

''config.php''
<code php>
// This is the function that returns the SCSS source for the main file in our theme. We override the boost version because
// we want to allow presets uploaded to our own theme file area to be selected in the preset list.
$THEME->scss = function($theme) {
return theme_photo_get_main_scss_content($theme);
};
</code>

''lib.php''
<code php>
function theme_photo_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');

} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_photo', 'preset', 0, '/', $filename))) {
// This preset file was fetched from the file area for theme_photo and not theme_boost (see the line above).
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

return $scss;
}
</code>

=== Stop and try it out ===
So now what is working and what isn't. Well - everything should be working and you should have a nice new theme extending boost with it's own settings pages. When Boost gets updates for bug fixes your new theme will inherit those fixes as it inherits all the SCSS and templates from theme boost. In addition your new theme will accept preset files and supports all the same features and settings as boost, ready to add more.

== Take it further ==
Now we have our very nice starting point we can start changing or adding features, customising templates and output or tweaking the SCSS.

=== Add some new settings ===

From this point in the tutorial we will start adding features to our theme to extend it and make it AWESOME!

Lets start with a new setting to set a background image on the login page. As you saw earlier, our theme defines it's list of settings in a file called settings.php. See [[Admin settings]] for more information about adding admin settings to any plugin. All of the different kinds of admin settings can be found in lib/adminlib.php. In our case we will want to add a setting which allows an admin to upload an image file. This is an "admin_setting_configstoredfile" and we add it to our theme by adding this code to the settings.php file (inside the "if ($ADMIN->fulltree) {" condition.

''settings.php''
<code php>
// Login page background setting.
// We use variables for readability.
$name = 'theme_photo/loginbackgroundimage';
$title = get_string('loginbackgroundimage', 'theme_photo');
$description = get_string('loginbackgroundimage_desc', 'theme_photo');
// This creates the new setting.
$setting = new admin_setting_configstoredfile($name, $title, $description, 'loginbackgroundimage');
// This means that theme caches will automatically be cleared when this setting is changed.
$setting->set_updatedcallback('theme_reset_all_caches');
// We always have to add the setting to a page for it to have any effect.
$page->add($setting);
</code>

We also need to add new lang strings to our language file.

"lang/en/theme_photo.php"
<code php>
// Background image for login page.
$string['loginbackgroundimage'] = 'Login page background image';
// Background image for login page.
$string['loginbackgroundimage_desc'] = 'An image that will be stretched to fill the background of the login page.';
</code>

Now we have a new setting that lets us upload a file - but it doesn't actually do anything yet. We need to update the theme to set this image background on the login page.

In order to change the SCSS for our theme we will add 2 additional SCSS files and include them before and after our main scss.

We already have a function in our lib.php file which fetches the main SCSS for our theme. This is a good point to include additional SCSS files. We can add 2 lines to the end of this function to achieve this.

''lib.php''
<code php>
function theme_photo_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');

} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_photo', 'preset', 0, '/', $filename))) {
// This preset file was fetched from the file area for theme_photo and not theme_boost (see the line above).
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

// Pre CSS - this is loaded AFTER any prescss from the setting but before the main scss.
$pre = file_get_contents($CFG->dirroot . '/theme/photo/scss/pre.scss');
// Post CSS - this is loaded AFTER the main scss but before the extra scss from the setting.
$post = file_get_contents($CFG->dirroot . '/theme/photo/scss/post.scss');

// Combine them together.
return $pre . "\n" . $scss . "\n" . $post;
}
</code>

''scss/pre.scss''
<code scss>
// Pre SCSS for the theme.
</code>

''scss/post.scss''
<code scss>
// Post SCSS for the theme.
</code>

==== Why do we use pre and post SCSS? ====
SCSS/SASS is a powerful language for creating CSS. It supports variables, functions, loops just like php. For lots of information and an introduction to SCSS read about [https://en.wikipedia.org/wiki/Sass_(stylesheet_language) Sass on wikipedia].

'''Pre SCSS'''

In Boost we use many variables when creating style rules.

When declaring a variable in SCSS - it is best practice to define it like this:
<code scss>
$mycoolcolour: #FF0 !default;
</code>

What this means is - if this variable is not defined already - set it to the hex value '#FF0';

So by setting this variable in some PRE scss we can override the default value of this variable everywhere it is used. Boost is built with the [https://v4-alpha.getbootstrap.com/ Bootstrap 4 (Alpha 4)] CSS Framework. This is a framework which uses SCSS to provide many extremely useful layouts and components which can be reused without adding specific CSS rules to style every page. Because bootstrap consistently uses variables we can customise many of these components easily by setting the value of the variables before we include the Bootstrap SCSS files.

Many variables are available in /theme/boost/scss/bootstrap/_variables.scss - as an example we can change the look of all buttons and input fields with this one variable:

<code scss>
$border-radius: 8px;
</code>

'''Post SCSS'''

Post SCSS is useful for defining full CSS rules. Because they are included last, they override any previous matching selector with the same [https://en.wikipedia.org/wiki/Cascading_Style_Sheets#Specificity Specificity].

=== Tips for customising Moodle with SCSS (or CSS) ===
Some handy things to know when you are new to theming is that Moodle adds some classes to every page that helps you target a specific page or set of pages with some style rules.

If you inspect a moodle page and look at the body tag you will see a long list of classes e.g.

<code html>
<body id="page-course-view-weeks" class="format-weeks path-course path-course-view safari dir-ltr lang-en yui-skin-sam yui3-skin-sam damyon-per-in-moodle-com--stable_master pagelayout-course course-11 context-497 category-1 drawer-open-left jsenabled">
</code>

You can see from this example that each page gets an id. This is a simplified representation of the current page in the navigation. In this example we are looking at the course page and this course is using the weeks format.

The classes on the body tag can also be used to target a page or set of pages.
* <code>format-weeks</code> The course format
* <code>path-course path-course-view</code> The parts of the bread-crumb leading up to the current page (The current page is what goes in the id)
* <code>safari</code> Some server side guessing of the browser type - it's not accurate so I would not rely on it
* <code>dir-ltr</code> The direction of the current language for the page ( dir-rtl for RTL languages )
* <code>lang-en</code> The current language of the page
* <code>yui*</code> Legacy yui classes - ignore these
* <code>damyon-per-in-moodle-com--stable_master</code> The current hostname for the site + the site name
* <code>pagelayout-course</code> The layout type for the current page
* <code>course-11</code> The id of the current course
* <code>context-497</code> The current context id
* <code>category-1</code> The category for the current course
* <code>drawer-open-left</code> Added / removed when the navigation drawer is opened / closed in Boost
* <code>jsenabled</code> True if the browser supports javascript

[https://docs.moodle.org/dev/Themes_overview#.3Cbody.3E_CSS_id_and_classes Read about Body id and classes].

In our example the page layout is the most useful here as we have a specific page layout for login pages. We can now craft a rule that applies a background image only to login pages using "body.pagelayout-login".

=== How do we refer to an image in SCSS ? ===
So now we can add a rule to the post.scss which will set the background image for the login page. First we need to know how to construct a url to the background images from our stylesheet.

In stylesheets in Moodle we can use a special pix tag to refer to images from our theme. The rule to attach the background image looks like this:
''scss/post.scss''
<code scss>
body.pagelayout-login {
background-image: url([[pix:theme_photo|loginbackgroundimage]]);
background-size: cover;
}
</code>

There are 2 important parts to this tag (the bit in square brackets). The first is "theme_photo". In this case we are passing a component name, the image serving code in theme_config::resolve_image_location() will then look for an image file in several locations. One of these is in "$CFG->dataroot/pix_plugins/$type/$plugin/$image". We can use this to make sure the image gets served correctly by copying the file saved in the setting to this location every time it is updated. (There is an alterative way we could do this by implementing pluginfile.php in our theme - which you can read about in the [[File API]] ).

If we had just passed the value "theme" the image serving code would have looked for the image in the "pix" folder of our theme.

So - we need this final change to copy the image file into our dataroot each time the setting is changed.

In the settings file we will update the callback to a new function which we will define in our lib.php.
''settings.php''
<code php>

// Login page background setting.
// We use variables for readability.
$name = 'theme_photo/loginbackgroundimage';
$title = get_string('loginbackgroundimage', 'theme_photo');
$description = get_string('loginbackgroundimage_desc', 'theme_photo');
// This creates the new setting.
$setting = new admin_setting_configstoredfile($name, $title, $description, 'loginbackgroundimage');
// This function will copy the image into the data_root location it can be served from.
$setting->set_updatedcallback('theme_photo_update_settings_images');
// We always have to add the setting to a page for it to have any effect.
$page->add($setting);
//This will commit the background image setting. If you do not add this line the Login page background setting will not be shown.
$settings->add($page);
</code>

''lib.php''
<code php>
function theme_photo_update_settings_images($settingname) {
global $CFG;

// The setting name that was updated comes as a string like 's_theme_photo_loginbackgroundimage'.
// We split it on '_' characters.
$parts = explode('_', $settingname);
// And get the last one to get the setting name..
$settingname = end($parts);

// Admin settings are stored in system context.
$syscontext = context_system::instance();
// This is the component name the setting is stored in.
$component = 'theme_photo';

// This is the value of the admin setting which is the filename of the uploaded file.
$filename = get_config($component, $settingname);
// We extract the file extension because we want to preserve it.
$extension = substr($filename, strrpos($filename, '.') + 1);

// This is the path in the moodle internal file system.
$fullpath = "/{$syscontext->id}/{$component}/{$settingname}/0{$filename}";
// Get an instance of the moodle file storage.
$fs = get_file_storage();
// This is an efficient way to get a file if we know the exact path.
if ($file = $fs->get_file_by_hash(sha1($fullpath))) {
// We got the stored file - copy it to dataroot.
// This location matches the searched for location in theme_config::resolve_image_location.
$pathname = $CFG->dataroot . '/pix_plugins/theme/photo/' . $settingname . '.' . $extension;

// This pattern matches any previous files with maybe different file extensions.
$pathpattern = $CFG->dataroot . '/pix_plugins/theme/photo/' . $settingname . '.*';

// Make sure this dir exists.
@mkdir($CFG->dataroot . '/pix_plugins/theme/photo/', $CFG->directorypermissions, true);

// Delete any existing files for this setting.
foreach (glob($pathpattern) as $filename) {
@unlink($filename);
}

// Copy the current file to this location.
$file->copy_content_to($pathname);
}

// Reset theme caches.
theme_reset_all_caches();
}
</code>

To edit the setting go to '''Site Administration > Appearance > Photo > Advanced setting'''. You will now see the Login page background setting.
It is now easy to add a new background image setting for every layout type. I can re-use this theme_photo_update_settings_images callback for each one - so all I have to do is add the setting to the settings.php file, add the SCSS rule to the scss/post.scss file and add the lang strings to the language file.

Thats it for this tutorial, but there are [[:Category:Themes| more Themes docs]] to browse.

[[Category:Themes]]

Creating a theme based on boost

2020-07-29T13:40:52Z

Meeth: Undo revision 57724 by Meeth (talk)

Creating a theme based on boost

2020-07-20T15:01:59Z

Meeth:

{{Moodle 3.2}}
{{Template:Themes}}

This is a tutorial for how to create a new theme in any version of Moodle from 3.2 and later.

Moodle 3.2 introduced a new core theme named "Boost" which is a great starting point for themers wanting to build a modern Moodle theme utilising all the latest features available to themes in Moodle. If you aren't sure where to start, then START HERE! :-)

== Getting started ==
What is a theme? A theme in Moodle is just another type of plugin that can be developed. Themes are responsible for setting up the structure of each page and have the ability to customise the output of any page in Moodle.

This tutorial is based on a working theme named "theme_photo" you can download it or view the source code for it here: https://github.com/damyon/moodle-theme_photo

=== Choosing a name ===
Your new theme will need a name. Try and think of something short and memorable - and make sure it is not a name that has already been used by someone else. A quick search on the moodle.org/plugins can save you a lot of work renaming things later.

Lets call our new example theme "photo" as we will add some settings to allow "photos" in various places in Moodle.

=== Starting files ===
As a plugin, themes must start with the basic structure of a plugin in Moodle. See https://docs.moodle.org/dev/Tutorial#The_skeleton_of_your_plugin for an overview of the files common to all plugins in Moodle.

Following this guide we can start creating our theme. First we create the folder for the new theme under "/theme/" folder in the Moodle root directory.

<code>
/theme/photo/
</code>

Now we need to add some standard plugin files to our theme. First is version.php

''/theme/photo/version.php''

<code php>

<?php
// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// This is the version of the plugin.
$plugin->version = '2016102100';

// This is the version of Moodle this plugin requires.
$plugin->requires = '2016070700';

// This is the component name of the plugin - it always starts with 'theme_'
// for themes and should be the same as the name of the folder.
$plugin->component = 'theme_photo';

// This is a list of plugins, this plugin depends on (and their versions).
$plugin->dependencies = [
'theme_boost' => '2016102100'
];

</code>

We also need a language file so that all our strings can be translated into different languages. The name of this file is the component name of our plugin and it sits in the lang/en/ folder for our plugin. We can include translations of our plugin, but we can also provide translations via the https://lang.moodle.org/ website once our plugin has been published to the plugins database at http://www.moodle.org/plugins/.

''/theme/photo/lang/en/theme_photo.php''

<code php>

<?php
// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// A description shown in the admin theme selector.
$string['choosereadme'] = 'Theme photo is a child theme of Boost. It adds the ability to upload background photos.';
// The name of our plugin.
$string['pluginname'] = 'Photo';
// We need to include a lang string for each block region.
$string['region-side-pre'] = 'Right';
</code>

=== Theme specific files ===
Theme plugins have a few more standard files they need to define.

Themes require a favicon file to show in the address bar. See [[http://docs.moodle.org/en/Favicon Favicon]].

''pix/favicon.ico''

(Image file not shown).

Themes also require an example screenshot to be displayed in the theme selector.

''pix/screenshot.jpg''

(Image file not shown).

Themes require a lib.php file. This file contains callbacks used by various API's in Moodle. Initially this file can be empty, but as we add features to our theme we will need to add some functions here.

''lib.php''
<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// We will add callbacks here as we add features to our theme.
</code>

Theme config goes in a config.php file. This is one of the most important files in our theme. Once we add this file we will be ready to test our theme for the first time.

''config.php''

<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// $THEME is defined before this page is included and we can define settings by adding properties to this global object.

// The first setting we need is the name of the theme. This should be the last part of the component name, and the same
// as the directory name for our theme.
$THEME->name = 'photo';

// This setting list the style sheets we want to include in our theme. Because we want to use SCSS instead of CSS - we won't
// list any style sheets. If we did we would list the name of a file in the /style/ folder for our theme without any css file
// extensions.
$THEME->sheets = [];

// This is a setting that can be used to provide some styling to the content in the TinyMCE text editor. This is no longer the
// default text editor and "Atto" does not need this setting so we won't provide anything. If we did it would work the same
// as the previous setting - listing a file in the /styles/ folder.
$THEME->editor_sheets = [];

// This is a critical setting. We want to inherit from theme_boost because it provides a great starting point for SCSS bootstrap4
// themes. We could add more than one parent here to inherit from multiple parents, and if we did they would be processed in
// order of importance (later themes overriding earlier ones). Things we will inherit from the parent theme include
// styles and mustache templates and some (not all) settings.
$THEME->parents = ['boost'];

// A dock is a way to take blocks out of the page and put them in a persistent floating area on the side of the page. Boost
// does not support a dock so we won't either - but look at bootstrapbase for an example of a theme with a dock.
$THEME->enable_dock = false;

// This is an old setting used to load specific CSS for some YUI JS. We don't need it in Boost based themes because Boost
// provides default styling for the YUI modules that we use. It is not recommended to use this setting anymore.
$THEME->yuicssmodules = array();

// Most themes will use this rendererfactory as this is the one that allows the theme to override any other renderer.
$THEME->rendererfactory = 'theme_overridden_renderer_factory';

// This is a list of blocks that are required to exist on all pages for this theme to function correctly. For example
// bootstrap base requires the settings and navigation blocks because otherwise there would be no way to navigate to all the
// pages in Moodle. Boost does not require these blocks because it provides other ways to navigate built into the theme.
$THEME->requiredblocks = '';

// This is a feature that tells the blocks library not to use the "Add a block" block. We don't want this in boost based themes because
// it forces a block region into the page when editing is enabled and it takes up too much room.
$THEME->addblockposition = BLOCK_ADDBLOCK_POSITION_FLATNAV;
</code>

=== Ready set go! ===
If you have been following along - now we are at the point where we can actually install and test our new theme. Try it now by visiting the admin notifications page to install the new plugin, and then choosing the new theme from the theme selector.

[[https://docs.moodle.org/en/Standard_themes#Theme_selector Theme selector]]

When you choose the new theme - you will find that it looks exactly the same as Boost. At this point with our minimal configuration - we are inheriting almost everything from our parent theme including styles and templates. You will notice though that we don't inherit the settings from our parent theme. If you choose a different preset in Boost - it is not applied in this child theme.

<div class="warningbox">
Note: make sure your config.php file contains $THEME->hidefromselector = false; (or at least set to false) or else, your theme wont show up in theme selector.
</div>

=== What if I want the settings too? ===

<div class="warningbox">
This section is included for completeness - but it is not recommended for themes to utilise settings from their parents. To find out how to duplicate the settings from the parent theme so they operate independently skip to [[#Duplicate the settings from Boost]].
</div>

If I want the settings from Boost to apply to my child theme as well I need to know a bit about how each of the settings in Boost is applied to make them work in my child theme.

'''Setting 1 - preset.'''

The "preset" file is the file that is used as the main file for scss compilation. In Boost this is controlled by the theme config value:

''theme_boost/config.php''
<code php>
$THEME->scss = function($theme) {
return theme_boost_get_main_scss_content($theme);
};
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');
} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_boost', 'preset', 0, '/', $filename))) {
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

return $scss;
}
</code>

What this function is doing is checking for a theme setting "preset" and either fetching the file from Moodles internal file storage, or from the /preset/ folder. The function then returns the contents of this file.

It does not automatically work for our child theme because we have no setting named "preset" in our child theme and this code is not searching the theme parents for the setting. If we wanted it to apply we could do this in our child theme:

''config.php''
<code php>
// This setting defines the main scss file for our theme to be compiled. We could set it to a static file in the scss folder or to a function which returns the SCSS based on theme settings.
$THEME->scss = function($theme) {

// We need to load the config for our parent theme because that is where the preset setting is defined.
$parentconfig = theme_config::load('boost');
// Call a function from our parent themes lib.php file to fetch the content of the themes main SCSS file based on it's own config, not ours.
return theme_boost_get_main_scss_content($parentconfig);
};
</code>

'''Settings 2+3 brandcolor + scsspre'''

The way these settings work is they generate a chunk of SCSS to be prepended to the main scss file. In boost they work like this:

''theme_boost/config.php''
<code php>
$THEME->prescsscallback = 'theme_boost_get_pre_scss';
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_pre_scss($theme) {
global $CFG;

$scss = '';
$configurable = [
// Config key => [variableName, ...].
'brandcolor' => ['brand-primary'],
];

// Prepend variables first.
foreach ($configurable as $configkey => $targets) {
$value = isset($theme->settings->{$configkey}) ? $theme->settings->{$configkey} : null;
if (empty($value)) {
continue;
}
array_map(function($target) use (&$scss, $value) {
$scss .= '$' . $target . ': ' . $value . ";\n";
}, (array) $targets);
}

// Prepend pre-scss.
if (!empty($theme->settings->scsspre)) {
$scss .= $theme->settings->scsspre;
}

return $scss;
}
</code>

What this code is doing is:
* looping over a list of theme settings that map to a SCSS variable and building some SCSS to initialise that variable from the setting. In Boost there is only one * brandprimary - but if we wanted to expose more bootstrap variables as theme settings we could use this function as a template in our child theme and add more settings to the $configurable array.
* Adding all of the raw SCSS from the scsspre theme setting
* Returning the whole thing as a string to be added before the main scss file.

If we want this code to work in our child theme, using the settings from Boost we could do this:

''config.php''
<code php>
// This is a function that returns some SCSS as a string to prepend to the main SCSS file.
$THEME->prescsscallback = 'theme_photo_get_pre_scss';
</code>

''lib.php''
<code php>
// Function to return the SCSS to prepend to our main SCSS for this theme.
// Note the function name starts with the component name because this is a global function and we don't want namespace clashes.
function theme_photo_get_pre_scss($theme) {
// Load the settings from the parent.
$theme = theme_config::load('boost');
// Call the parent themes get_pre_scss function.
return theme_boost_get_pre_scss($theme);
}
</code>

'''Setting 4 scss (post)'''

The final setting from Boost is a raw text field which adds SCSS to the end of the main SCSS file. This is a useful place to add style rules as they will override previously defined styles with the same specificity. It is applied in Boost by the following lines:

''theme_boost/config.php''
<code php>
$THEME->extrascsscallback = 'theme_boost_get_extra_scss';
</code>
''theme_boost/lib.php''
<code php>
function theme_boost_get_extra_scss($theme) {
return !empty($theme->settings->scss) ? $theme->settings->scss : '';
}
</code>

This is just returning the value of the setting as a string.

To make this setting apply in our child theme too - we use similar code to the previous sections.

''config.php''
<code php>
// This is a function that returns some SCSS as a string to append to the main SCSS file.
$THEME->extrascsscallback = 'theme_photo_get_extra_scss';
</code>

''lib.php''
<code php>
// Function to return the SCSS to append to our main SCSS for this theme.
// Note the function name starts with the component name because this is a global function and we don't want namespace clashes.
function theme_photo_get_extra_scss($theme) {
// Load the settings from the parent.
$theme = theme_config::load('boost');
// Call the parent themes get_extra_scss function.
return theme_boost_get_extra_scss($theme);
}
</code>

=== Duplicate the settings from Boost ===

This is the recommended way to extend boost as your child theme will not be affected by changes to the Boost settings, and both themes can be in use with different settings applied.

All that needs to happen is to create theme settings in the child theme that match each of the settings in the parent theme. You will need to add matching language strings for each of these settings in the language file.

This example shows how to do it - We are re-using the nice looking theme_boost_admin_settingspage_tabs class from boost and creating duplicate versions of each of the settings.

''settings.php''

<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();

// This is used for performance, we don't need to know about these settings on every page in Moodle, only when
// we are looking at the admin settings pages.
if ($ADMIN->fulltree) {

// Boost provides a nice setting page which splits settings onto separate tabs. We want to use it here.
$settings = new theme_boost_admin_settingspage_tabs('themesettingphoto', get_string('configtitle', 'theme_photo'));

// Each page is a tab - the first is the "General" tab.
$page = new admin_settingpage('theme_photo_general', get_string('generalsettings', 'theme_photo'));

// Replicate the preset setting from boost.
$name = 'theme_photo/preset';
$title = get_string('preset', 'theme_photo');
$description = get_string('preset_desc', 'theme_photo');
$default = 'default.scss';

// We list files in our own file area to add to the drop down. We will provide our own function to
// load all the presets from the correct paths.
$context = context_system::instance();
$fs = get_file_storage();
$files = $fs->get_area_files($context->id, 'theme_photo', 'preset', 0, 'itemid, filepath, filename', false);

$choices = [];
foreach ($files as $file) {
$choices[$file->get_filename()] = $file->get_filename();
}
// These are the built in presets from Boost.
$choices['default.scss'] = 'default.scss';
$choices['plain.scss'] = 'plain.scss';

$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Preset files setting.
$name = 'theme_photo/presetfiles';
$title = get_string('presetfiles','theme_photo');
$description = get_string('presetfiles_desc', 'theme_photo');

$setting = new admin_setting_configstoredfile($name, $title, $description, 'preset', 0,
array('maxfiles' => 20, 'accepted_types' => array('.scss')));
$page->add($setting);

// Variable $brand-color.
// We use an empty default value because the default colour should come from the preset.
$name = 'theme_photo/brandcolor';
$title = get_string('brandcolor', 'theme_photo');
$description = get_string('brandcolor_desc', 'theme_photo');
$setting = new admin_setting_configcolourpicker($name, $title, $description, '');
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Must add the page after definiting all the settings!
$settings->add($page);

// Advanced settings.
$page = new admin_settingpage('theme_photo_advanced', get_string('advancedsettings', 'theme_photo'));

// Raw SCSS to include before the content.
$setting = new admin_setting_configtextarea('theme_photo/scsspre',
get_string('rawscsspre', 'theme_photo'), get_string('rawscsspre_desc', 'theme_photo'), '', PARAM_RAW);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

// Raw SCSS to include after the content.
$setting = new admin_setting_configtextarea('theme_photo/scss', get_string('rawscss', 'theme_photo'),
get_string('rawscss_desc', 'theme_photo'), '', PARAM_RAW);
$setting->set_updatedcallback('theme_reset_all_caches');
$page->add($setting);

$settings->add($page);
}
</code>

''lang/en/theme_photo.php''
<code php>
<?php

// Every file should have GPL and copyright in the header - we skip it in tutorials but you should not skip it for real.

// This line protects the file from being accessed by a URL directly.
defined('MOODLE_INTERNAL') || die();
// The name of the second tab in the theme settings.
$string['advancedsettings'] = 'Advanced settings';
// The brand colour setting.
$string['brandcolor'] = 'Brand colour';
// The brand colour setting description.
$string['brandcolor_desc'] = 'The accent colour.';
// A description shown in the admin theme selector.
$string['choosereadme'] = 'Theme photo is a child theme of Boost. It adds the ability to upload background photos.';
// Name of the settings pages.
$string['configtitle'] = 'Photo settings';
// Name of the first settings tab.
$string['generalsettings'] = 'General settings';
// The name of our plugin.
$string['pluginname'] = 'Photo';
// Preset files setting.
$string['presetfiles'] = 'Additional theme preset files';
// Preset files help text.
$string['presetfiles_desc'] = 'Preset files can be used to dramatically alter the appearance of the theme. See <a href=https://docs.moodle.org/dev/Boost_Presets>Boost presets</a> for information on creating and sharing your own preset files, and see the <a href=http://moodle.net/boost>Presets repository</a> for presets that others have shared.';
// Preset setting.
$string['preset'] = 'Theme preset';
// Preset help text.
$string['preset_desc'] = 'Pick a preset to broadly change the look of the theme.';
// Raw SCSS setting.
$string['rawscss'] = 'Raw SCSS';
// Raw SCSS setting help text.
$string['rawscss_desc'] = 'Use this field to provide SCSS or CSS code which will be injected at the end of the style sheet.';
// Raw initial SCSS setting.
$string['rawscsspre'] = 'Raw initial SCSS';
// Raw initial SCSS setting help text.
$string['rawscsspre_desc'] = 'In this field you can provide initialising SCSS code, it will be injected before everything else. Most of the time you will use this setting to define variables.';
// We need to include a lang string for each block region.
$string['region-side-pre'] = 'Right';
</code>

We aren't quite there yet as you will notice if you try and upload a preset file and then choose it. The "theme_boost_get_main_scss_content" function from Boost is expecting the preset files to be stored in a file area for theme_boost only. We need to add this function to our own theme and tweak it.

''config.php''
<code php>
// This is the function that returns the SCSS source for the main file in our theme. We override the boost version because
// we want to allow presets uploaded to our own theme file area to be selected in the preset list.
$THEME->scss = function($theme) {
return theme_photo_get_main_scss_content($theme);
};
</code>

''lib.php''
<code php>
function theme_photo_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');

} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_photo', 'preset', 0, '/', $filename))) {
// This preset file was fetched from the file area for theme_photo and not theme_boost (see the line above).
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

return $scss;
}
</code>

=== Stop and try it out ===
So now what is working and what isn't. Well - everything should be working and you should have a nice new theme extending boost with it's own settings pages. When Boost gets updates for bug fixes your new theme will inherit those fixes as it inherits all the SCSS and templates from theme boost. In addition your new theme will accept preset files and supports all the same features and settings as boost, ready to add more.

== Take it further ==
Now we have our very nice starting point we can start changing or adding features, customising templates and output or tweaking the SCSS.

=== Add some new settings ===

From this point in the tutorial we will start adding features to our theme to extend it and make it AWESOME!

Lets start with a new setting to set a background image on the login page. As you saw earlier, our theme defines it's list of settings in a file called settings.php. See [[Admin settings]] for more information about adding admin settings to any plugin. All of the different kinds of admin settings can be found in lib/adminlib.php. In our case we will want to add a setting which allows an admin to upload an image file. This is an "admin_setting_configstoredfile" and we add it to our theme by adding this code to the settings.php file (inside the "if ($ADMIN->fulltree) {" condition.

''settings.php''
<code php>
// Login page background setting.
// We use variables for readability.
$name = 'theme_photo/loginbackgroundimage';
$title = get_string('loginbackgroundimage', 'theme_photo');
$description = get_string('loginbackgroundimage_desc', 'theme_photo');
// This creates the new setting.
$setting = new admin_setting_configstoredfile($name, $title, $description, 'loginbackgroundimage');
// This means that theme caches will automatically be cleared when this setting is changed.
$setting->set_updatedcallback('theme_reset_all_caches');
// We always have to add the setting to a page for it to have any effect.
$page->add($setting);
</code>

We also need to add new lang strings to our language file.

"lang/en/theme_photo.php"
<code php>
// Background image for login page.
$string['loginbackgroundimage'] = 'Login page background image';
// Background image for login page.
$string['loginbackgroundimage_desc'] = 'An image that will be stretched to fill the background of the login page.';
</code>

Now we have a new setting that lets us upload a file - but it doesn't actually do anything yet. We need to update the theme to set this image background on the login page.

In order to change the SCSS for our theme we will add 2 additional SCSS files and include them before and after our main scss.

We already have a function in our lib.php file which fetches the main SCSS for our theme. This is a good point to include additional SCSS files. We can add 2 lines to the end of this function to achieve this.

''lib.php''
<code php>
function theme_photo_get_main_scss_content($theme) {
global $CFG;

$scss = '';
$filename = !empty($theme->settings->preset) ? $theme->settings->preset : null;
$fs = get_file_storage();

$context = context_system::instance();
if ($filename == 'default.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
} else if ($filename == 'plain.scss') {
// We still load the default preset files directly from the boost theme. No sense in duplicating them.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/plain.scss');

} else if ($filename && ($presetfile = $fs->get_file($context->id, 'theme_photo', 'preset', 0, '/', $filename))) {
// This preset file was fetched from the file area for theme_photo and not theme_boost (see the line above).
$scss .= $presetfile->get_content();
} else {
// Safety fallback - maybe new installs etc.
$scss .= file_get_contents($CFG->dirroot . '/theme/boost/scss/preset/default.scss');
}

// Pre CSS - this is loaded AFTER any prescss from the setting but before the main scss.
$pre = file_get_contents($CFG->dirroot . '/theme/photo/scss/pre.scss');
// Post CSS - this is loaded AFTER the main scss but before the extra scss from the setting.
$post = file_get_contents($CFG->dirroot . '/theme/photo/scss/post.scss');

// Combine them together.
return $pre . "\n" . $scss . "\n" . $post;
}
</code>

''scss/pre.scss''
<code scss>
// Pre SCSS for the theme.
</code>

''scss/post.scss''
<code scss>
// Post SCSS for the theme.
</code>

==== Why do we use pre and post SCSS? ====
SCSS/SASS is a powerful language for creating CSS. It supports variables, functions, loops just like php. For lots of information and an introduction to SCSS read about [https://en.wikipedia.org/wiki/Sass_(stylesheet_language) Sass on wikipedia].

'''Pre SCSS'''

In Boost we use many variables when creating style rules.

When declaring a variable in SCSS - it is best practice to define it like this:
<code scss>
$mycoolcolour: #FF0 !default;
</code>

What this means is - if this variable is not defined already - set it to the hex value '#FF0';

So by setting this variable in some PRE scss we can override the default value of this variable everywhere it is used. Boost is built with the [https://v4-alpha.getbootstrap.com/ Bootstrap 4 (Alpha 4)] CSS Framework. This is a framework which uses SCSS to provide many extremely useful layouts and components which can be reused without adding specific CSS rules to style every page. Because bootstrap consistently uses variables we can customise many of these components easily by setting the value of the variables before we include the Bootstrap SCSS files.

Many variables are available in /theme/boost/scss/bootstrap/_variables.scss - as an example we can change the look of all buttons and input fields with this one variable:

<code scss>
$border-radius: 8px;
</code>

'''Post SCSS'''

Post SCSS is useful for defining full CSS rules. Because they are included last, they override any previous matching selector with the same [https://en.wikipedia.org/wiki/Cascading_Style_Sheets#Specificity Specificity].

=== Tips for customising Moodle with SCSS (or CSS) ===
Some handy things to know when you are new to theming is that Moodle adds some classes to every page that helps you target a specific page or set of pages with some style rules.

If you inspect a moodle page and look at the body tag you will see a long list of classes e.g.

<code html>
<body id="page-course-view-weeks" class="format-weeks path-course path-course-view safari dir-ltr lang-en yui-skin-sam yui3-skin-sam damyon-per-in-moodle-com--stable_master pagelayout-course course-11 context-497 category-1 drawer-open-left jsenabled">
</code>

You can see from this example that each page gets an id. This is a simplified representation of the current page in the navigation. In this example we are looking at the course page and this course is using the weeks format.

The classes on the body tag can also be used to target a page or set of pages.
* <code>format-weeks</code> The course format
* <code>path-course path-course-view</code> The parts of the bread-crumb leading up to the current page (The current page is what goes in the id)
* <code>safari</code> Some server side guessing of the browser type - it's not accurate so I would not rely on it
* <code>dir-ltr</code> The direction of the current language for the page ( dir-rtl for RTL languages )
* <code>lang-en</code> The current language of the page
* <code>yui*</code> Legacy yui classes - ignore these
* <code>damyon-per-in-moodle-com--stable_master</code> The current hostname for the site + the site name
* <code>pagelayout-course</code> The layout type for the current page
* <code>course-11</code> The id of the current course
* <code>context-497</code> The current context id
* <code>category-1</code> The category for the current course
* <code>drawer-open-left</code> Added / removed when the navigation drawer is opened / closed in Boost
* <code>jsenabled</code> True if the browser supports javascript

[https://docs.moodle.org/dev/Themes_overview#.3Cbody.3E_CSS_id_and_classes Read about Body id and classes].

In our example the page layout is the most useful here as we have a specific page layout for login pages. We can now craft a rule that applies a background image only to login pages using "body.pagelayout-login".

=== How do we refer to an image in SCSS ? ===
So now we can add a rule to the post.scss which will set the background image for the login page. First we need to know how to construct a url to the background images from our stylesheet.

In stylesheets in Moodle we can use a special pix tag to refer to images from our theme. The rule to attach the background image looks like this:
''scss/post.scss''
<code scss>
body.pagelayout-login {
background-image: url([[pix:theme_photo|loginbackgroundimage]]);
background-size: cover;
}
</code>

There are 2 important parts to this tag (the bit in square brackets). The first is "theme_photo". In this case we are passing a component name, the image serving code in theme_config::resolve_image_location() will then look for an image file in several locations. One of these is in "$CFG->dataroot/pix_plugins/$type/$plugin/$image". We can use this to make sure the image gets served correctly by copying the file saved in the setting to this location every time it is updated. (There is an alterative way we could do this by implementing pluginfile.php in our theme - which you can read about in the [[File API]] ).

If we had just passed the value "theme" the image serving code would have looked for the image in the "pix" folder of our theme.

So - we need this final change to copy the image file into our dataroot each time the setting is changed.

In the settings file we will update the callback to a new function which we will define in our lib.php.
''settings.php''
<code php>

// Login page background setting.
// We use variables for readability.
$name = 'theme_photo/loginbackgroundimage';
$title = get_string('loginbackgroundimage', 'theme_photo');
$description = get_string('loginbackgroundimage_desc', 'theme_photo');
// This creates the new setting.
$setting = new admin_setting_configstoredfile($name, $title, $description, 'loginbackgroundimage');
// This function will copy the image into the data_root location it can be served from.
$setting->set_updatedcallback('theme_photo_update_settings_images');
// We always have to add the setting to a page for it to have any effect.
$page->add($setting);
</code>

''lib.php''
<code php>
function theme_photo_update_settings_images($settingname) {
global $CFG;

// The setting name that was updated comes as a string like 's_theme_photo_loginbackgroundimage'.
// We split it on '_' characters.
$parts = explode('_', $settingname);
// And get the last one to get the setting name..
$settingname = end($parts);

// Admin settings are stored in system context.
$syscontext = context_system::instance();
// This is the component name the setting is stored in.
$component = 'theme_photo';

// This is the value of the admin setting which is the filename of the uploaded file.
$filename = get_config($component, $settingname);
// We extract the file extension because we want to preserve it.
$extension = substr($filename, strrpos($filename, '.') + 1);

// This is the path in the moodle internal file system.
$fullpath = "/{$syscontext->id}/{$component}/{$settingname}/0{$filename}";
// Get an instance of the moodle file storage.
$fs = get_file_storage();
// This is an efficient way to get a file if we know the exact path.
if ($file = $fs->get_file_by_hash(sha1($fullpath))) {
// We got the stored file - copy it to dataroot.
// This location matches the searched for location in theme_config::resolve_image_location.
$pathname = $CFG->dataroot . '/pix_plugins/theme/photo/' . $settingname . '.' . $extension;

// This pattern matches any previous files with maybe different file extensions.
$pathpattern = $CFG->dataroot . '/pix_plugins/theme/photo/' . $settingname . '.*';

// Make sure this dir exists.
@mkdir($CFG->dataroot . '/pix_plugins/theme/photo/', $CFG->directorypermissions, true);

// Delete any existing files for this setting.
foreach (glob($pathpattern) as $filename) {
@unlink($filename);
}

// Copy the current file to this location.
$file->copy_content_to($pathname);
}

// Reset theme caches.
theme_reset_all_caches();
}
</code>

Now, create an image called '''loginbackgroundimage''' and upload it to '''/theme/photo/pix'''. You will be able to view the image in the background of your login page.

It is now easy to add a new background image setting for every layout type. I can re-use this theme_photo_update_settings_images callback for each one - so all I have to do is add the setting to the settings.php file, add the SCSS rule to the scss/post.scss file and add the lang strings to the language file.

Thats it for this tutorial, but there are [[:Category:Themes| more Themes docs]] to browse.

[[Category:Themes]]

Blocks

2020-07-08T09:10:01Z

Meeth: /* I Just Hear Static */

''' A Step-by-step Guide To Creating Blocks '''

Original Author: Jon Papaioannou ([mailto:pj@moodle.org pj@moodle.org])

Updated to Moodle 2.0 and above by: Greg J Preece ([mailto:greg.preece@blackboard.com greg.preece@blackboard.com])

{{Moodle 2.0}}

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 2.0 development version of Moodle (and any newer) '''only''', as the blocks API changed significantly enough to warrant new documentation. Those wishing to read the old tutorial for Moodles 1.5 to 1.9 can find it under [[Blocks/Blocks for 1.5 to 1.9| Blocks for 1.5 to 1.9]].

The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It's targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though.

Experienced developers and those who just want a '''programmer's reference''' text should refer to [[Blocks/Appendix_A| Appendix A]] because the main guide has a rather low concentration of pure information in the text.

== Basic Concepts ==

Through this guide, we will be following the creation of an "HTML" block from scratch in order to demonstrate most of the block features at our disposal. Our block will be named "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required.

Whenever we refer to a file or directory name which contains "simplehtml", it's important to remember that ''only'' the "simplehtml" part is up to us to change; the rest is standardised and essential for Moodle to work correctly.

Whenever a file's path is mentioned in this guide, it will always start with a slash. This refers to the Moodle home directory; all files and directories will be referred to with respect to that directory.

== Ready, Set, Go! ==

To define a "block" in Moodle, in the most basic case we need to provide just four PHP files. Remember, in this example we are creating a block called 'simplehtml', replace 'simplehtml' with the name of your custom block. The four files should be located in blocks/simplehtml and are:

=== block_simplehtml.php ===

This file will hold the class definition for the block, and is used both to manage it as a plugin and to render it onscreen.

We start by creating the main object file, 'block_simplehtml.php'. We then begin coding the block:

<code php>
<?php
class block_simplehtml extends block_base {
public function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
}
// The PHP tag and the curly bracket for the class definition
// will only be closed after there is another function added in the next section.
}
</code>

The first line is our block class definition; it must be named exactly in the manner shown. Again, only the "simplehtml" part can (and indeed must) change; everything else is standardised.

Our class is then given a small method: [[Blocks/Appendix_A#init.28.29| init()]]. This is essential for all blocks, and its purpose is to give values to any class member variables that need instantiating.

In this very basic example, we only want to set [[Blocks/Appendix_A#.24this-.3Etitle| $this->title]], which is the title displayed in the header of our block. We can set it to whatever we like; in this case it's set to read the actual title from the language file mentioned below, which is then distributed along with the block. I'll skip ahead a bit here and say that if you want your block to display '''no''' title at all, then you should set this to any descriptive value you want (but '''not''' make it an empty string). We will later see [[Blocks#Eye_Candy|how to disable the title's display]].

=== db/access.php ===

This file will hold the new capabilities created by the block.

Moodle 2.4 onwards introduced the capabilities addinstance and myaddinstance for core blocks. They were introduced so that it was possible to control the use of individual blocks. These capabilities should also be added to your custom block, so in this case to the file blocks/simplehtml/db/access.php. If your block is not going to be used in the 'My Moodle page' (ie, your applicable_formats function (discussed later) has 'my' set to false.) then the myaddinstance capability does not need to be given to any user, but it must still be defined here otherwise you will get errors on certain pages. The following is the capabilities array and how it should look for any new blocks.

<code php>
<?php
$capabilities = array(

'block/simplehtml:myaddinstance' => array(
'captype' => 'write',
'contextlevel' => CONTEXT_SYSTEM,
'archetypes' => array(
'user' => CAP_ALLOW
),

'clonepermissionsfrom' => 'moodle/my:manageblocks'
),

'block/simplehtml:addinstance' => array(
'riskbitmask' => RISK_SPAM | RISK_XSS,

'captype' => 'write',
'contextlevel' => CONTEXT_BLOCK,
'archetypes' => array(
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
),

'clonepermissionsfrom' => 'moodle/site:manageblocks'
),
);
</code>

=== lang/en/block_simplehtml.php ===

This is the English language file for your block. If you are not an English speaker, you can replace 'en' with your appropriate language code (but even then you will need english folder !). All language files for blocks go under the /lang subfolder of the block's installation folder.

Moodle 2.0 and above require a name for our plugin to show in the upgrading page. We set this value, along with the capabilities we created and any other language strings we wish to use within the block, in a language package as previously mentioned (the same file where we put our string for the plugin title).

The capabilities added above need descriptions for pages that allow setting of capabilities. These should also be added to the language file.

<code php>
<?php
$string['pluginname'] = 'Simple HTML block';
$string['simplehtml'] = 'Simple HTML';
$string['simplehtml:addinstance'] = 'Add a new simple HTML block';
$string['simplehtml:myaddinstance'] = 'Add a new simple HTML block to the My Moodle page';
</code>

=== version.php ===

This file will hold version information for the plugin, along '''with other advanced parameters''' (not covered here - see [[version.php]] if you want '''more details''').

Prior to Moodle 2.0, version details for blocks were stored as class fields; as of Moodle 2.0 these are stored in a file called version.php, stored under ''/blocks/simplehtml/'''version.php'''''. The version file is very simple indeed, containing only a few field definitions, depending on your needs. Here is an example:
<code php>
<?php
$plugin->component = 'block_simplehtml'; // Recommended since 2.0.2 (MDL-26035). Required since 3.0 (MDL-48494)
$plugin->version = 2011062800; // YYYYMMDDHH (year, month, day, 24-hr time)
$plugin->requires = 2010112400; // YYYYMMDDHH (This is the release version for Moodle 2.0)
</code>

This file contains object field definitions that denote the full [[Frankenstyle|frankenstyle]] component name in the form of ''plugintype_pluginname'' and the version number of the block, along with the minimum version of Moodle that must be installed in order to use it. Please note that the object being used here is ''always'' called '''$plugin''', and that you do not need to create this object yourself within the version file. Note also we don't include a closing "?>" tag. This is intentional, and a [[Coding_style#PHP_tags | workaround for whitespace issues]].

The exact Moodle version of a release can be found in [[Releases]].

{{Top}}

== I Just Hear Static ==
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file) inside of the block_simplehtml.php script. The new code is:

<code php>
public function get_content() {
if ($this->content !== null) {
return $this->content;
}

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';

return $this->content;
}

</code>

'''Add your block to the front page!'''
Don't forget (especially if you're a new Moodle user) to add your block to the front page. Turn Editing On, and add your block to the page.

It can't get any simpler than that, can it? Let's dissect this method to see what's going on...

First of all, there is a check that returns the current value of [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]] if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it '''will''' be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver.
Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text '''and''' in the footer, if we want to.

It's worth mentioning that this is not the only type of content a block can output. You can also create lists and hierarchical trees, which are better suited for certain types of output, such as menus. These different content types have an impact on the content object and how it is constructed. For more information, see [[Blocks/Appendix A#.24this-.3Econtent_type|Appendix A]]

At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it (Click "Notifications" under the Site Administration Block) and after seeing it in action come back to continue our tutorial.

== Configure That Out ==

The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". Basic instance configuration is automatic in Moodle 2.0; if you put any page with blocks on it into "editing mode", you will notice that each block has an edit button in its title bar. Clicking on this will take you to the block configuration form. The settings that Moodle adds to this form by default relate to the block's appearance and position on Moodle pages.

We can extend this configuration form, and add custom preferences fields, so that users can better tailor our block to a given task or page. To extend the configuration form, create the file <span class="filename">/blocks/simplehtml/'''edit_form.php'''</span>, and fill it with the following code:

<code php>
<?php

class block_simplehtml_edit_form extends block_edit_form {

protected function specific_definition($mform) {

// Section header title according to language file.
$mform->addElement('header', 'config_header', get_string('blocksettings', 'block'));

// A sample string variable with a default value.
$mform->addElement('text', 'config_text', get_string('blockstring', 'block_simplehtml'));
$mform->setDefault('config_text', 'default value');
$mform->setType('config_text', PARAM_RAW);

}
}
</code>
The first line declares a class that inherits '''from block_edit_form''', and this allows Moodle to identify the code to execute in the configuration page. The '''specific_definition()''' method is where your form elements are defined, and these take the same format as with the standard [[lib/formslib.php_Form_Definition|Moodle form library]]. Within our specific_definition method, we have created a header, and an input field which will accept text to be used within the block.

'''NOTE:''' You might want extend language file for your block (lang/en/block_simplehtml.php) and add a value for "blockstring" defined in a code above.

'''IMPORTANT:''' All your field names need to start with "config_", otherwise they will not be saved and will not be available within the block via [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]].

So once our instance configuration form has been saved, we can use the inputted text within the block like so:

<code php>
if (! empty($this->config->text)) {
$this->content->text = $this->config->text;
}
</code>

Note that [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] is available in all block methods ''except'' [[Blocks/Appendix_A#init.28.29|init()]]. This is because [[Blocks/Appendix_A#init.28.29|init()]] is called immediately as the block is being created, with the purpose of setting things up, so [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] has not yet been instantiated.

'''Note about Checkbox:''' You cannot use the 'checkbox' element in the form (once set it will stay set). You must use advcheckbox instead.

{{Top}}

== The Specialists ==

Implementing instance configuration for the block's contents was good enough to whet our appetite, but who wants to stop there? Why not customize the block's title, too?

Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to ''/blocks/simplehtml/'''edit_form.php'''''. Here goes:

<code php>
// A sample string variable with a default value.
$mform->addElement('text', 'config_title', get_string('blocktitle', 'block_simplehtml'));
$mform->setDefault('config_title', 'default value');
$mform->setType('config_title', PARAM_TEXT);
</code>

We save the edited file, go to a course, edit the title of the block and... nothing happens! The instance configuration is saved correctly, all right (editing it once more proves that) but it's not being displayed. All we get is just the simple "SimpleHTML" title.

That's not too weird, if we think back a bit. Do you remember that [[Blocks/Appendix_A#init.28.29|init()]] method, where we set [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]]? We didn't actually change its value from then, and [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]] is definitely not the same as '''$this->config->title''' (to Moodle, at least). What we need is a way to update [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] in all methods ''except'' [[Blocks/Appendix_A#init.28.29|init()]]! So what can we do?

Let's pull out another ace from our sleeve, and add this small method to our block class:

<code php>
public function specialization() {
if (isset($this->config)) {
if (empty($this->config->title)) {
$this->title = get_string('defaulttitle', 'block_simplehtml');
} else {
$this->title = $this->config->title;
}

if (empty($this->config->text)) {
$this->config->text = get_string('defaulttext', 'block_simplehtml');
}
}
}
</code>

Aha, here's what we wanted to do all along! But what's going on with the [[Blocks/Appendix_A#specialization.28.29| specialization()]] method?

This "magic" method has actually a very nice property: it's ''guaranteed'' to be automatically called by Moodle as soon as our instance configuration is loaded and available (that is, immediately after [[Blocks/Appendix_A#init.28.29|init()]] is called). That means before the block's content is computed for the first time, and indeed before ''anything'' else is done with the block. Thus, providing a [[Blocks/Appendix_A#specialization.28.29| specialization()]] method is the natural choice for any configuration data that needs to be acted upon or made available "as soon as possible", as in this case.

{{Top}}

== Now You See Me, Now You Don't ==

Now would be a good time to mention another nifty technique that can be used in blocks, and which comes in handy quite often. Specifically, it may be the case that our block will have something interesting to display some of the time; but in some other cases, it won't have anything useful to say. An example here would be the "Recent Activity" block, in the case where no recent activity in fact exists.

However in that case the block chooses to explicitly inform you of the lack of said activity, which is arguably useful. It would be nice, then, to be able to have our block "disappear" if it's not needed to display it.

This is indeed possible, and the way to do it is to make sure that after the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method is called, the block has no content to display. This means that all fields in $this->content should be equal to the empty string (<nowiki>''</nowiki>). In the case of our HTML-based block, these fields are $this->content->text and $this->content->footer. Moodle performs this check by calling the block's [[Blocks/Appendix_A#is_empty.28.29| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.

Note that the exact value of the block's title and the presence or absence of a [[Blocks/Appendix_A#hide_header.28.29| hide_header()]] method do ''not'' affect this behavior. A block is considered empty if it has no content, irrespective of anything else.

{{Top}}

== We Are Legion ==

Right now our block is fully configurable, both in title and content. It's so versatile, in fact, that we could make pretty much anything out of it. It would be really nice to be able to add multiple blocks of this type to a single course. And, as you might have guessed, doing that is as simple as adding another small method to our block class:

<code php>
public function instance_allow_multiple() {
return true;
}
</code>

This tells Moodle that it should allow any number of instances of the SimpleHTML block in any course. After saving the changes to our file, Moodle immediately allows us to add multiple copies of the block without further ado!

Please note that even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.

{{Top}}

== The Effects of Globalization ==

Configuring each block instance with its own personal data is cool enough, but sometimes administrators need some way to "touch" all instances of a specific block at the same time. In the case of our SimpleHTML block, a few settings that would make sense to apply to all instances aren't that hard to come up with.

For example, we might want to limit the contents of each block to only so many characters, or we might have a setting that filters HTML out of the block's contents, only allowing pure text in. Granted, such a feature wouldn't win us any awards for naming our block "SimpleHTML" but some tormented administrator somewhere might actually find it useful.

This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents. To enable global configuration for the block, we create a new file, ''/blocks/simplehtml/'''settings.php''''', and populate it with form field definitions for each setting, which Moodle will use to generate and handle a global settings form. This is quite similar in concept to how we generated the instance configuration form earlier, but the actual code used to generate the form and fields is somewhat different.

Place the following in your settings.php file:

<code php>
<?php
$settings->add(new admin_setting_heading(
'headerconfig',
get_string('headerconfig', 'block_simplehtml'),
get_string('descconfig', 'block_simplehtml')
));

$settings->add(new admin_setting_configcheckbox(
'simplehtml/Allow_HTML',
get_string('labelallowhtml', 'block_simplehtml'),
get_string('descallowhtml', 'block_simplehtml'),
'0'
));
</code>

As you can see, to generate a global configuration form, we simply create admin setting objects and add them to an array. This array is then stepped over to create the settings form, and the inputted data is automatically saved to the database. Full details of the setting types available and how to add them can be found under [[Admin_settings#Individual_settings]].

We've now created a header and checkbox form element to accept configuration details from the site admin. You should pay extra attention to the name of our checkbox element, ''' 'simplehtml/Allow_HTML' ''', as it specifies not only the name of the configuration option, but also how it should be stored. If you simply specify a name for the config option, it will be stored in the global $CFG object, and in the ''<prefix>_config'' database table. This will make your config variable available immediately via $CFG without requiring an additional database call, but will also increase the size of the $CFG object. In addition, we must prefix the variable with the name of our block, otherwise we run the risk of our config variable sharing its name with a similar variable in another plugin, or within Moodle itself.

The preferred method of storing your block's configuration data is to prefix each config variable name in your settings.php file with your block's name, followed by a slash ( / ), and the name of the configuration variable, as we have done above. If you write your settings.php file in this way, then your variables will be stored in the ''<prefix>_config_plugin'' table, under your block's name. Your config data will still be available via a '''get_config()''' call, and name collision will be impossible between plugins.

Finally, if you're wondering why there are two language tags specified for each element, the first tag is for the element's label or primary text, and the second tag is for its description. And that's it. Pretty easy, huh?

=== Enabling Global Configuration ===
{{Moodle 2.4}}Since version 2.4, the following line must be added to the /blocks/simplehtml/block_simplehtml.php file in order to enable global configuration:
<code>
function has_config() {return true;}
</code>
This line tells Moodle that the block has a settings.php file.

'''NOTE FOR UPGRADERS'''

You'll notice that the settings.php file and parsed element names replaces Moodle's old storage method, wherein it would send all the configuration data to your block's [[Blocks/Appendix_A#config_save.28.29|config_save()]] method, and allow you to override how the data is saved. The [[Blocks/Appendix_A#config_save.28.29|config_save()]] method is no longer used in Moodle 2.x; however the [[Blocks/Appendix_A#instance_config_save.28.29|instance_config_save()]] method is very much alive and well, as you will see shortly.

{{Top}}

=== Accessing Global Config Data ===

Now that we have global data defined for the plugin, we need to know how to access it within our code. If you saved your config variables in the global namespace, you can access them from the global $CFG object, like so:

<code php>
$allowHTML = $CFG->Allow_HTML;
</code>

If, as recommended, you saved your config variables in a custom namespace for your block, then you can access them via a call to '''get_config()''':

<code php>
$allowHTML = get_config('simplehtml', 'Allow_HTML');
</code>

{{Top}}

=== Rolling It All Together ===

OK, so we now have an instance configuration form that allows users to enter custom content text for a block, and a global configuration option that dictates whether or not that user should be allowed to enter HTML tags as part of the content. Now we just need to tie the two together. But if Moodle takes care of the form processing for our instance configuration in edit_form.php, how can we capture it and remove the HTML tags where required?

Well, fortunately, there is a way this can be done. By overriding the [[Blocks/Appendix_A#instance_config_save.28.29| instance_config_save()]] method in our block class, we can modify the way in which instance configuration data is stored after input. The default implementation is as follows:

<code php>
public function instance_config_save($data, $nolongerused = false) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance',
'configdata',
base64_encode(serialize($data)),
'id',
$this->instance->id);
}
</code>

This may look intimidating at first (what's all this stripslashes_recursive() and base64_encode() and serialize() stuff?) but do not despair; we won't have to touch any of it. We will only add some extra validation code in the beginning and then instruct Moodle to additionally call this default implementation to do the actual storing of the data. Specifically, we will add a method to our class which goes like this:

<code php>
public function instance_config_save($data,$nolongerused =false) {
if(get_config('simplehtml', 'Allow_HTML') == '1') {
$data->text = strip_tags($data->text);
}

// And now forward to the default implementation defined in the parent class
return parent::instance_config_save($data,$nolongerused);
}
</code>

(This example assumes you are using a custom namespace for the block.)

At last! Now the administrator has absolute power of life and death over what type of content is allowed in our "SimpleHTML" block! Absolute? Well... not exactly. In fact, if we think about it for a while, it will become apparent that if at some point in time HTML is allowed and some blocks have saved their content with HTML included, and afterwards the administrator changes the setting to "off", this will only prevent subsequent content changes from including HTML. Blocks which already had HTML in their content would continue to display it!

Following that train of thought, the next stop is realizing that we wouldn't have this problem if we had chosen the lazy approach a while back, because in that case we would "sanitize" each block's content just before it was displayed.

The only thing we can do with the eager approach is strip all the tags from the content of all SimpleHTML instances as soon as the admin setting is changed to "HTML off"; but even then, turning the setting back to "HTML on" won't bring back the tags we stripped away. On the other hand, the lazy approach might be slower, but it's more versatile; we can choose whether to strip or keep the HTML before displaying the content, and we won't lose it at all if the admin toggles the setting off and on again. Isn't the life of a developer simple and wonderful?

=== Exercise ===
We will let this part of the tutorial come to a close with the obligatory exercise for the reader:
In order to have the SimpleHTML block work "correctly", find out how to strengthen the eager approach to strip out all tags from the existing configuration of all instances of our block, '''or''' go back and implement the lazy approach instead.
(Hint: Do that in the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method.)

{{Top}}

== Eye Candy ==

Our block is just about complete functionally, so now let's take a look at some of the tricks we can use to make its behavior customized in a few more useful ways.

First of all, there are a couple of ways we can adjust the visual aspects of our block. For starters, it might be useful to create a block that doesn't display a header (title) at all. You can see this effect in action in the Course Description block that comes with Moodle. This behavior is achieved by, you guessed it, adding one more method to our block class:

<code php>
public function hide_header() {
return true;
}
</code>

One more note here: we cannot just set an empty title inside the block's [[Blocks/Appendix_A#init.28.29| init()]] method; it's necessary for each block to have a unique, non-empty title after [[Blocks/Appendix_A#init.28.29| init()]] is called so that Moodle can use those titles to differentiate between all of the installed blocks.

Next, we can affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <div> or <table> elements, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This is generally done to give us freedom to customize the end result using CSS (this is in fact done by default as we'll see below).

The default behavior of this feature in our case will modify our block's "class" HTML attribute by appending the value "block_simplehtml" (the prefix "block_" followed by the name of our block, lowercased). We can then use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".block_simplehtml { border: 1px black solid}").

To change the default behavior, we will need to define a method which returns an associative array of attribute names and values. For example:

<code php>
public function html_attributes() {
$attributes = parent::html_attributes(); // Get default values
$attributes['class'] .= ' block_'. $this->name(); // Append our class to class attribute
return $attributes;
}
</code>

This results in the block having all its normal HTML attributes, as inherited from the base block class, plus our additional class name. We can now use this class name to change the style of the block, add JavaScript events to it via YUI, and so on. And for one final elegant touch, we have not set the class to the hard-coded value "block_simplehtml", but instead used the [[Blocks/Appendix_A#name.28.29| name()]] method to make it dynamically match our block's name.

{{Top}}

== Authorized Personnel Only ==

Some blocks are useful in some circumstances, but not in others. An example of this would be the "Social Activities" block, which is useful in courses with the "social" course format, but not courses with the "weeks" format. What we need to be able to do is limit our block's availability, so that it can only be selected on pages where its content or abilities are appropriate.

Moodle allows us to declare which page formats a block is available on, and enforces these restrictions as set by the block's developer at all times. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.

Notice the deliberate use of the term ''page'' instead of ''course'' in the above paragraph. This is because in Moodle 1.5 and onwards, blocks can be displayed in any page that supports them. The best example of such pages are the course pages, but we are not restricted to them. For instance, the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks.

The format names we can use for the pages derive from the name of the script which is actually used to display that page. For example, when we are looking at a course, the script is <span class="filename">/course/view.php</span> (this is evident from the browser's address line). Thus, the format name of that page is '''course-view'''. It follows easily that the format name for a quiz view page is '''mod-quiz-view'''. This rule of thumb does have a few exceptions, however:

# The format name for the front page of Moodle is '''site-index'''.
# The format name for courses is actually not just '''course-view'''<nowiki>; it is </nowiki>'''course-view-weeks''', '''course-view-topics''', etc.
# Even though there is no such page, the format name '''all''' can be used as a catch-all option.

We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":

# Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
# The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
# The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
# The order that the format names appear does not make any difference.
All of the above are enough to make the situation sound complex, so let's look at some specific examples. First of all, to have our block appear '''only''' in the site front page, we would use:

<code php>
public function applicable_formats() {
return array('site-index' => true);
}
</code>

Since '''all''' is missing, the block is disallowed from appearing in ''any'' course format; but then '''site''' is set to TRUE, so it's explicitly allowed to appear in the site front page (remember that '''site''' matches '''site-index''' because it's a prefix).

For another example, if we wanted to allow the block to appear in all course formats ''except'' social, and also to ''not'' be allowed anywhere but in courses, we would use:

<code php>
public function applicable_formats() {
return array(
'course-view' => true,
'course-view-social' => false);
}
</code>

This time, we first allow the block to appear in all courses and then we explicitly disallow the social format.
For our final, most complicated example, suppose that a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, ''except'' quiz. This would be:

<code php>
public function applicable_formats() {
return array(
'site-index' => true,
'course-view' => true,
'course-view-social' => false,
'mod' => true,
'mod-quiz' => false
);
}
</code>

It is not difficult to realize that the above accomplishes the objective if we remember that there is a "best match" policy to determine the end result.

{{Top}}

== Background Processing ==

If you want to do some background processing in your block - use the [[Task API]] to create a background task that can be scheduled to run at regular intervals and can be displayed and configured by an administrator (this is the same regardless of the plugin type).

{{Top}}

== Additional Content Types ==

=== Lists ===

In this final part of the guide we will briefly discuss several additional capabilities of Moodle's block system, namely the ability to create blocks that display different kinds of content to the user. The first of these creates a list of options and displays them to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.

As we have seen so far, blocks use two properties of [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]]: "text" and "footer". The text is displayed as-is as the block content, and the footer is displayed below the content in a smaller font size. List blocks use $this->content->footer in the exact same way, but they ignore $this->content->text.

Instead, Moodle expects such blocks to set two other properties when the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method is called: $this->content->items and $this->content->icons. $this->content->items should be a numerically indexed array containing elements that represent the HTML for each item in the list that is going to be displayed. Usually these items will be HTML anchor tags which provide links to some page. $this->content->icons should also be a numerically indexed array, with exactly as many items as $this->content->items has. Each of these items should be a fully qualified HTML <img> tag, with "src", "height", "width" and "alt" attributes. Obviously, it makes sense to keep the images small and of a uniform size. We would recommend standard 16x16 images for this purpose.

In order to tell Moodle that we want to have a list block instead of the standard text block, we need to make a small change to our block class declaration. Instead of extending class '''block_base''', our block will extend class '''block_list'''. For example:

<code php>
class block_my_menu extends block_list {
// The init() method does not need to change at all
}
</code>

In addition to making this change, we must of course also modify the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method to construct the [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]] variable as discussed above:

<code php>
public function get_content() {
if ($this->content !== null) {
return $this->content;
}

$this->content = new stdClass;
$this->content->items = array();
$this->content->icons = array();
$this->content->footer = 'Footer here...';

$this->content->items[] = html_writer::tag('a', 'Menu Option 1', array('href' => 'some_file.php'));
$this->content->icons[] = html_writer::empty_tag('img', array('src' => 'images/icons/1.gif', 'class' => 'icon'));

// Add more list items here

return $this->content;
}
</code>

To summarise, if we want to create a list block instead of a text block, we just need to change the block class declaration and the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method. Adding the mandatory [[Blocks/Appendix_A#init.28.29| init()]] method as discussed earlier will then give us our first list block in no time!

=== Trees ===

As of 23rd December 2011, this functionality remains inoperable in all Moodle 2.x versions. It appears that classes are missing from the code base. This has been added to the tracker at the URL below. Please upvote this issue if you require this functionality.

[http://tracker.moodle.org/browse/MDL-28289 Visit this issue on the tracker @ MDL28289]

{{Top}}

== Database support ==
In case we need to have a database table that holds some specific information used within our block, we will need to create the file ''/blocks/simplehtml/'''install.xml''''' with the table schema contained within it.

To create the install.xml file, use the [[XMLDB editor]]. See [[Database_FAQ#XMLDB|Database FAQ > XMLDB]] for further details.

Up-to-date documentation on upgrading our block, as well as providing new capabilities and events to the system, can be found under [https://docs.moodle.org/dev/Installing_and_upgrading_plugin_database_tables#install.php Installing and Upgrading Plugin Database Tables]

== See also ==
* [[Blocks Advanced]] A continuation of this tutorial.
* [http://dev.moodle.org/mod/resource/view.php?id=48 Unit 7 of the Introduction to Moodle Programming course] is a follow up to this course. (But you should follow the forum discussions of that course closely as there are still some bugs and inconsistencies.)
* Daniel Neis Araujo's [https://github.com/danielneis/moodle-block_newblock NEWBLOCK template].

== Appendices ==

The appendices have been moved to separate pages:

* Appendix A: [[Blocks/Appendix A|''block_base'' Reference]]

{{Top}}

[[Category:Blocks]]
[[Category:Tutorial]]

[[es:Desarrollo de bloques]]
[[ja:開発:ブロック]]
[[:en:Blocks|Blocks]]

[[Category:Plugins]]

Creating a theme based on boost

2020-06-14T15:52:05Z

Meeth: