Cleanup and enhance the codebase for adoption and publication by Mood…

…le an Hochschulen e.V.

CHANGES.md

@@ -0,0 +1,11 @@
+moodle-theme_boost_union_child
+==============================
+
+Changes
+-------
+
+### Rolling release
+
+* 2024-02-20 - Cleanup and enhance the codebase for adoption and publication by Moodle an Hochschulen e.V.
+* 2024-01-10 - Add Github actions
+* 2023-09-15 - Initial boilerplate by Daniel Poggenpohl

README.md

@@ -1,20 +1,177 @@
 moodle-theme_boost_union_child
-========================
+==============================
 
-Theme Boost Union Child is a template to use for Boost Union child themes.
+[![Moodle Plugin CI](https://github.com/moodle-an-hochschulen/moodle-theme_boost_union_child/workflows/Moodle%20Plugin%20CI/badge.svg?branch=master)](https://github.com/moodle-an-hochschulen/moodle-theme_boost_union_child/actions?query=workflow%3A%22Moodle+Plugin+CI%22+branch%3Amaster)
+
+Boost Union Child is a boilerplate for enhancing Boost Union with custom or local functionality.
+
+
+Motivation for this plugin
+--------------------------
+
+If you ever wanted to benefit from all the / only the Boost Union features you need, but you also had to realize additional local features or settings at the same time, do not look further: Boost Union Child is your friend.
+
+With Boost Union Child, it is quite easy to create a grandchild theme of Boost Union. It will save you the time-consuming and headache-triggering first steps to create a grandchild theme, allowing you to start directly with the implementation of your local features.
+
+But please note: While Boost Union Child will surely help you to realize all your local Boost Union dreams, please do yourself and the whole community a favour and verify that your planned features are indeed not interesting as a pull request or feature request for the whole Boost Union community and could be contributed to Boost Union directly instead.
 
 
 Requirements
 ------------
 
-This theme requires a version of the [theme_boost_union](https://github.com/moodle-an-hochschulen/moodle-theme_boost_union) plugin installed
-which corresponds to this plugin's release.
+Boost Union Child does not have a real requirement for a particular Boost Union or Moodle core release.
+
+The code which you find in this repository is more or less release-agnostic. It is meant to be used in conjunction with the latest Boost Union release which goes with your Moodle core release.
 
 
 Installation
 ------------
 
-Install the theme like any other theme to folder
+Install Boost Union Child like any other plugin to folder
 /theme/boost_union_child
 
 See http://docs.moodle.org/en/Installing_plugins for details on installing Moodle plugins
+
+
+Usage
+-----
+
+After installing Boost Union Child, it does not do anything to Moodle or Boost Union yet.
+
+Boost Union Child integrates into the Boost Union settings as an additional settings page which you find on:
+Site administration -> Appearance -> Boost Union -> Boost Union Child.
+
+There, you find some settings:
+
+### Settings page "Boost Union Child"
+
+#### Tab "General settings"
+
+In this tab there are the following settings:
+
+##### Pre SCSS inheritance
+
+With this setting, you control if the pre SCSS code from Boost Union should be inherited or duplicated.
+
+Most of the time, inheriting will be perfectly fine. However, it may happen that imperfect code is integrated into Boost Union which prevents simple SCSS inheritance for particular Boost Union features. If you encounter any issues with Boost Union features which seem not to work in Boost Union Child as well, try to switch this setting to 'Dupliate' and, if this solves the problem, report an issue on Github (see the 'Bug and problem reports' section below for details how to report an issue).
+
+##### Extra SCSS inheritance
+
+With this setting, you control if the extra SCSS code from Boost Union should be inherited or duplicated.
+
+The reason behind this setting is the same as for the 'Pre SCSS inheritance' setting.
+
+
+Building your local theme with this boilerplate
+-----------------------------------------------
+
+Even though Boost Union Child is a fully working theme, it looks and feels exactly the same as Boost Union itself (well, this is why we build Boost Union Child).
+
+To build your own grandchild theme of Boost with this boilerplate, you have to go further.
+
+### Renaming the grandchild theme (optional)
+
+If you want to run your grandchild theme with a different name than theme_boost_union_child, for example theme_boost_union_foo, you have to take some actions:
+
+* In the whole codebase of Boost Union Child below /theme/boost_union_child,
+ * search all occurrences of 'boost_union_child' and replace them with 'boost_union_foo'
+ * search all occurrences of 'Boost Union Child' and replace them with 'Boost Union Foo'
+* In the language pack directory /theme/boost_union_child/lang,
+ * rename the language pack file from en/theme_boost_union.php to en/theme_boost_foo.php
+* In the tests directory /theme/boost_union_child/tests/behat,
+ * rename the Behat step definition files from behat_theme_boost_union_child_behat_\*.php to behat_theme_boost_union_foo_behat_\*.php
+
+### Add your Boost Union Child features
+
+To add your local features to Boost Union Child, you can more or less follow all coding guidelines for Boost theme development which you find on the net. A good and official starting point is https://docs.moodle.org/dev/Themes.
+
+To help you with the first steps, we have added some markers to Boost Union Child's codebase at the places where you can add your own features. Just search for EXTENSION POINT and you will find the places where you can add your settings, language strings, SCSS code and so on.
+
+In addition to that, have a look at the 'Extensiopn examples' section below.
+
+### Finishing your grandchild theme (optional)
+
+If you want to use Moodle plugin updates properly and especially if you intend to publish your grandchild theme, you set your plugin version information properly:
+
+* In the version file /theme/boost_union_child/version.php,
+ * raise $plugin->version to a proper version of your choice (see https://docs.moodle.org/dev/Moodle_versions for an explanation how Moodle version numbers are composed)
+ * set $plugin->release to a release string of your choice (in Boost Union, we use release strings like 'v4.3-r1' which means 'First release for Moodle 4.3')
+ * set $plugin->requires to the version number of the miniumum Moodle core version which you would like to support (see https://moodledev.io/general/releases for the list of Moodle core versions)
+ * likewise, set $plugin->supported to an array with the range of Moodle core versions which you would like to support (for example, to support Moodle 4.3 only officially, set it to '[403, 403]')
+ * raise the entry for theme_boost_union in $plugin->dependencies to the version number of the Boost Union version which you tested your grandchild theme against, just to avoid any hickups if someone tries to combine your grandchild theme with a much older version of Boost Union
+
+As an orientation how all these settings should look like, you can compare /theme/boost_union_child/version.php with /theme/boost_union/version.php, of course.
+
+### Congratulate yourself
+
+Now your grandchild theme should be ready to be used in production. Well done!
+
+
+Extension examples
+------------------
+
+### General
+
+Developing for Boost Union means to apply similar techniques for every new feature. In this section, we try to collect some of these techniques for you.
+
+### Call for proposals
+
+If you have another good extension example for Boost Union Child, we would be grateful if you would contribute it!
+
+Just fork this repo, compose a branch with the extension example and create an issue in this repository to tell us the URL of your branch. We will then do our best to pick and publish your proposal.
+
+
+Plugin repositories
+-------------------
+
+This boilerplate is not published in the Moodle plugins repository.
+
+The latest development version can be found on Github:
+https://github.com/moodle-an-hochschulen/moodle-theme_boost_union_child
+
+
+Bug and problem reports / Support requests
+------------------------------------------
+
+This boilerplate is carefully developed and thoroughly tested, but bugs and problems can always appear.
+
+Please report bugs and problems on Github:
+https://github.com/moodle-an-hochschulen/moodle-theme_boost_union_child/issues
+
+We will do our best to solve your problems, but please note that due to limited resources we can't always provide per-case support.
+
+
+Feature proposals
+-----------------
+
+Due to limited resources, the functionality of this boilerplate is primarily implemented for our own local needs and published as-is to the community. We are aware that members of the community will have other needs and would love to see them solved by this boilerplate.
+
+Please issue feature proposals on Github:
+https://github.com/moodle-an-hochschulen/moodle-theme_boost_union_child/issues
+
+Please create pull requests on Github:
+https://github.com/moodle-an-hochschulen/moodle-theme_boost_union_child/pulls
+
+We are always interested to read about your feature proposals or even get a pull request from you, but please accept that we can handle your issues only as feature _proposals_ and not as feature _requests_.
+
+
+Maintainers
+-----------
+
+The boilerplate is maintained by\
+Moodle an Hochschulen e.V.
+
+
+Credits
+-------
+
+This boilerplate is heavily inspired by the work of Daniel Poggenpohl from FernUniversität in Hagen who was the first to create a Boost Union Child boilerplate.
+
+
+Copyright
+---------
+
+The copyright of this boilerplate is held by\
+Moodle an Hochschulen e.V.
+
+Individual copyrights of individual developers are tracked in PHPDoc comments and Git commits.

privacy/provider.php → classes/privacy/provider.php

@@ -18,6 +18,7 @@
  * Theme Boost Union Child - Privacy provider
  *
  * @package theme_boost_union_child
+ * @copyright 2023 Daniel Poggenpohl <[email protected]> and Alexander Bias <[email protected]>
  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
@@ -27,6 +28,7 @@
  * Privacy Subsystem implementing null_provider.
  *
  * @package theme_boost_union_child
+ * @copyright 2023 Daniel Poggenpohl <[email protected]> and Alexander Bias <[email protected]>
  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class provider implements \core_privacy\local\metadata\null_provider {
@@ -37,7 +39,7 @@ class provider implements \core_privacy\local\metadata\null_provider {
  *
  * @return string
  */
- public static function get_reason():string {
+ public static function get_reason(): string {
  return 'privacy:metadata';
  }
 }

config.php

@@ -18,36 +18,57 @@
  * Theme Boost Union Child - Theme config
  *
  * @package theme_boost_union_child
+ * @copyright 2024 Alexander Bias <[email protected]>
+ * based on code by Lars Bonczek
  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
 
+// @codingStandardsIgnoreFile
+// Let codechecker ignore this file. It would complain about a missing login check.
+
+// As a start, inherit the whole theme config from Boost Union.
+// This move will save us from duplicating all lines from Boost Union's config.php into Boost Union Child's config.php.
+require_once($CFG->dirroot . '/theme/boost_union/config.php');
+
+// Then, we require Boost Union Child's locallib.php to make sure that it's always loaded.
+require_once($CFG->dirroot . '/theme/boost_union_child/locallib.php');
+
+// Next, we overwrite only the settings which differ between Boost Union and Boost Union Child.
 $THEME->name = 'boost_union_child';
-$THEME->parents = ['boost_union','boost'];
-$THEME->prescsscallback = 'theme_boost_union_child_get_pre_scss';
-$THEME->scss = function() {
- return theme_boost_union_child_get_main_scss_content();
+$THEME->scss = function($theme) {
+ return theme_boost_union_child_get_main_scss_content($theme);
 };
-// Note: This is necessary as long as MDL-77657 isn't done, as the order for grandchild themes is mixed up
+$THEME->parents = ['boost_union','boost'];
 $THEME->extrascsscallback = 'theme_boost_union_child_get_extra_scss';
-# This is for fallback compiled scss if compilation fails (use Boost Union's)
-$THEME->precompiledcsscallback = 'theme_boost_union_get_precompiled_css';
-# We don't provide our own fallback CSS file
-$THEME->usefallback = false;
-
-// The $THEME->layouts setting is not duplicated here as they are properly inherited from theme_boost_union.
-// Note: layouts are taken youngest to oldest, first found
-$THEME->enable_dock = false;
-$THEME->yuicssmodules = [];
+$THEME->prescsscallback = 'theme_boost_union_child_get_pre_scss';
+
+// We need to duplicate the rendererfactory even if it is set to the same value as in Boost Union.
+// The theme_config::get_renderer() method needs it to be directly in the theme_config object.
 $THEME->rendererfactory = 'theme_overridden_renderer_factory';
-$THEME->requiredblocks = '';
-$THEME->addblockposition = BLOCK_ADDBLOCK_POSITION_FLATNAV;
-$THEME->iconsystem = \core\output\icon_system::FONTAWESOME;
-$THEME->haseditswitch = true;
-$THEME->usescourseindex = true;
-$THEME->removedprimarynavitems = explode(',', get_config('theme_boost_union', 'hidenodesprimarynavigation'));
-// By default, all boost theme do not need their titles displayed.
-$THEME->activityheaderconfig = [
- 'notitle' => true
-];
+
+// Lastly, we replicate some settings from Boost Union at runtime into Boost Union Child's settings.
+// This becomes necessary if Moodle core code accesses a theme setting at $this->page->theme->settings->*.
+// In this case, the setting must exist in the currently active theme, otherwise it won't be found.
+// While Boost Union duplicates all settings from Boost Core and does not suffer from this issue,
+// it would be quite ugly to duplicate all of these settings again to Boost Union Child.
+// Currently, this affects these Boost Core settings:
+// unaddableblocks - called from blocklib.php.
+$unaddableblocks = get_config('theme_boost_union', 'unaddableblocks');
+if (!empty($unaddableblocks)) {
+ $THEME->settings->unaddableblocks = $unaddableblocks;
+}
+unset($unaddableblocks);
+// scss - called in theme_boost_get_extra_scss.
+$scss = get_config('theme_boost_union', 'scss');
+if (!empty($scss)) {
+ $THEME->settings->scss = $scss;
+}
+unset($scss);
+// scsspre - called in theme_boost_get_pre_scss.
+$scsspre = get_config('theme_boost_union', 'scsspre');
+if (!empty($scsspre)) {
+ $THEME->settings->scsspre = $scsspre;
+}
+unset($scsspre);

lang/en/theme_boost_union_child.php

@@ -1,16 +1,51 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
+
 /**
  * Theme Boost Union Child - Language pack
  *
  * @package theme_boost_union_child
+ * @copyright 2023 Daniel Poggenpohl <[email protected]> and Alexander Bias <[email protected]>
  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
 
 // General.
-$string['pluginname'] = 'Boost Union Child Theme Template';
+$string['pluginname'] = 'Boost Union Child';
 $string['choosereadme'] = 'This plugin is just a boilerplate template one can use to develop Boost Union child themes.';
+$string['configtitle'] = 'Boost Union Child';
+
+// Settings: General settings tab.
+// ... Section: Inheritance.
+$string['inheritanceheading'] = 'Inheritance';
+$string['inheritanceinherit'] = 'Inherit';
+$string['inheritanceduplicate'] = 'Duplicate';
+$string['inheritanceoptionsexplanation'] = 'Most of the time, inheriting will be perfectly fine. However, it may happen that imperfect code is integrated into Boost Union which prevents simple SCSS inheritance for particular Boost Union features. If you encounter any issues with Boost Union features which seem not to work in Boost Union Child as well, try to switch this setting to \'Dupliate\' and, if this solves the problem, report an issue on Github (see the README.md file for details how to report an issue).';
+// ... ... Setting: Pre SCSS inheritance setting.
+$string['prescssinheritancesetting'] = 'Pre SCSS inheritance';
+$string['prescssinheritancesetting_desc'] = 'With this setting, you control if the pre SCSS code from Boost Union should be inherited or duplicated.';
+// ... ... Setting: Extra SCSS inheritance setting.
+$string['extrascssinheritancesetting'] = 'Extra SCSS inheritance';
+$string['extrascssinheritancesetting_desc'] = 'With this setting, you control if the extra SCSS code from Boost Union should be inherited or duplicated.';
+
+/**************************************************************
+ * EXTENSION POINT:
+ * Add your language strings for your settings here.
+ *************************************************************/
 
 // Privacy API.
-$string['privacy:metadata'] = 'The Boost Union Child Theme Template does not store any personal data about any user.';
+$string['privacy:metadata'] = 'The Boost Union Child theme does not store any personal data about any user.';