Дочерняя тема нужна, когда настроек Boost уже не хватает, а править файлы самого Boost нельзя: при обновлении они вернутся к исходным. Тема в таком виде — это каталог с несколькими файлами, который наследует всё от родителя и переопределяет только своё. Ниже схема, которой я пользуюсь, и места, где темы ломаются при переходах между версиями. О том, какие цвета и логотип выбирать, написано в статье про брендирование под вуз, здесь только код.
Состав темы
| Файл | Зачем нужен |
|---|---|
theme/имя/version.php | Компонент theme_имя, версия, зависимость от theme_boost |
config.php | Имя темы, родитель, способ сборки стилей, фабрика рендереров |
lib.php | Функции, которые отдают SCSS при сборке |
scss/post.scss | Ваши стили, подключаемые после основных |
templates/ | Переопределённые шаблоны Mustache, по подкаталогам компонентов |
classes/output/core_renderer.php | Переопределение методов вывода ядра |
lang/ru/theme_имя.php | Название темы и строки настроек |
pix/ | Изображения темы, например заставка входа |
settings.php | Страница настроек: цвета, логотип, дополнительный SCSS (необязательно) |
config.php и lib.php
В config.php задают имя, родителя и источник стилей. Родитель указывается массивом, потому что цепочка наследования может быть длиннее одного звена.
defined('MOODLE_INTERNAL') || die();
$THEME->name = 'college';
$THEME->parents = ['boost'];
$THEME->sheets = [];
$THEME->scss = function($theme) {
return theme_college_get_main_scss_content($theme);
};
$THEME->prescsscallback = 'theme_college_get_pre_scss';
$THEME->rendererfactory = 'theme_overridden_renderer_factory';
Раскладки страниц не нужно переписывать: если вы не объявляете их в своей теме, она берёт раскладки родителя. Объявляйте их только когда меняете состав областей страницы.
В version.php укажите зависимость от родителя, иначе Moodle даст установить дочернюю тему на сайт, где родитель отсутствует. Для этого служит массив $plugin->dependencies с ключом theme_boost.
function theme_college_get_main_scss_content($theme) {
global $CFG;
require_once($CFG->dirroot . '/theme/boost/lib.php');
$scss = theme_boost_get_main_scss_content($theme);
$scss .= file_get_contents($CFG->dirroot . '/theme/college/scss/post.scss');
return $scss;
}
function theme_college_get_pre_scss($theme) {
return '$primary: #1f4e79;';
}
Так Boost собирает свои стили сам, а вы добавляете хвост. Переменные Bootstrap вроде $primary задаются в функции «до»: их значения подхватывают все компоненты. Это экономит десятки строк переопределения цветов в post.scss. Если вы предпочитаете собирать стили иначе, например брать готовый пресет, сверьтесь с документацией для вашей версии: порядок подключения файлов я бы не угадывала.
Переопределение шаблонов
Шаблоны Mustache ищутся сначала в теме, затем в родителях, затем в плагине. Чтобы изменить шаблон, положите файл с тем же именем по пути templates/компонент/имя.mustache внутри каталога темы. Например, шаблон формы входа ядра лежит в templates/core/loginform.mustache. Создавать копию нужно с самой новой версии из ядра вашего Moodle и менять в ней только нужное место.
Главный риск именно здесь. Скопированный шаблон не обновляется вместе с ядром. После обновления Moodle он может потерять новые атрибуты, кнопки и доступность. Поэтому я веду в теме список переопределённых шаблонов с версией Moodle, из которой их взяли, и после каждого обновления сравниваю с актуальными версиями ядра. Где можно, предпочитайте стили: скрыть блок через CSS проще и безопаснее, чем держать копию шаблона.
Рендерер и классы вывода
Если нужно изменить не разметку, а логику, например состав навигации, переопределяют метод рендерера. В каталоге classes/output создают класс с пространством имён темы, который наследует рендерер Boost, и в нём меняют нужный метод.
namespace theme_college\output;
class core_renderer extends \theme_boost\output\core_renderer {
public function standard_footer_html() {
$html = parent::standard_footer_html();
return $html . $this->render_from_template('theme_college/footer_links', []);
}
}
Обязательно вызывайте родительский метод и дополняйте его результат, а не пишите заново. Тогда при обновлении вы продолжите получать исправления родителя. Фабрика рендереров из config.php включает этот механизм, без неё ваш класс будет проигнорирован.
Работа с кэшем при разработке
| Симптом | Причина | Что сделать |
|---|---|---|
| Стили не меняются | Кэш собранного CSS | Очистить кэши через интерфейс или командой php admin/cli/purge_caches.php |
| Правка шаблона не видна | Кэш шаблонов | Очистить кэши, на отладочной копии включить режим разработчика тем |
| Страницы медленнее после правок | Включён режим разработчика тем | Выключить на рабочем сайте |
| Ошибка компиляции SCSS | Опечатка или переменная, которой нет в этой версии Bootstrap | Посмотреть сообщение, оно указывает файл и строку |
| Пропала часть интерфейса после правки стилей | Слишком широкий селектор задел чужие элементы | Откатить правку и сузить селектор до своего блока |
Режим разработчика включается в config.php сайта параметром $CFG->themedesignermode = true; и нужен только на тестовой копии.
Bootstrap 5 и Moodle 5.0
Если тема писалась под 4.x и сайт переходит на 5.0, главная работа будет не в SCSS, а в разметке. Moodle 5.0 использует новую версию Bootstrap, и в ней переименованы многие классы и атрибуты. Типичные замены перечислены в таблице.
| Было | Стало |
|---|---|
data-toggle, data-target | data-bs-toggle, data-bs-target |
ml-*, mr-* | ms-*, me-* |
pl-*, pr-* | ps-*, pe-* |
float-left, text-left | float-start, text-start |
sr-only | visually-hidden |
font-weight-bold | fw-bold |
Копии шаблонов в теме не получают этих замен сами, поэтому после перехода их приходится править вручную. Это ещё одна причина держать как можно меньше переопределений. При обновлении СДО центра ДПО до 5.2 я именно так оценивала объём работы: сначала считала, сколько шаблонов и стилей в теме и плагинах, завязанных на старые имена. Порядок такой работы описан на странице про обновление Moodle.
Когда дочерняя тема не нужна
Типичные ошибки дочерних тем
| Ошибка | Последствие | Решение |
|---|---|---|
| Правка файлов Boost напрямую | Изменения пропадают при обновлении | Переносить правки в дочернюю тему |
| Копия шаблона целиком ради одной строки | Шаблон устаревает, теряет новые атрибуты | Если можно, использовать стили; менять шаблон только когда без этого нельзя |
Жёсткие цвета в post.scss | Не меняются от настроек, не подходят под тёмные элементы | Задавать переменные Bootstrap в функции «до» |
| Селекторы по классам оформления вместо ролей | Ломаются при смене версии Bootstrap | Привязываться к структуре и атрибутам, где возможно |
Нет зависимости от theme_boost в version.php | Тему можно поставить без родителя, сайт ломается | Объявить зависимость |
| Режим разработчика оставлен на рабочем сайте | Страницы грузятся медленно | Включать только на тестовой копии |
Список переопределённых шаблонов
Я веду в каталоге темы короткий файл, который не участвует в работе, но нужен людям: список шаблонов и классов вывода, которые тема заменяет, с причиной и версией Moodle, из которой был взят оригинал. Выглядит это как обычная таблица. Через год она отвечает на вопрос, который иначе остаётся без ответа: почему в этом месте шаблон отличается от ядра, и можно ли вернуть штатный.
| Шаблон | Причина замены | Версия ядра оригинала | Проверено после обновления |
|---|---|---|---|
core/loginform | Добавлена пояснительная ссылка | Указывается номер версии | Дата проверки |
theme_college/footer_links | Собственный шаблон, оригинала нет | Не применимо | Дата проверки |
После каждого обновления я сравниваю замененные шаблоны с оригиналами нового выпуска. Команда сравнения каталогов покажет различия за минуты. Если в оригинале появились новые атрибуты или блоки, их переносят в копию.
Проверка темы перед релизом
- Откройте главную, курс, страницу входа, личную панель, профиль, тест и форум. На этих страницах тема встречается чаще всего.
- Проверьте телефон и планшет. Закреплённые боковые панели и выпадающие меню ломаются на узких экранах первыми.
- Проверьте контраст текста и фона. Это требование доступности, и для образовательных организаций оно не формальность.
- Включите режим редактирования: новые панели и кнопки не должны перекрываться элементами темы.
- Очистите кэши и убедитесь, что стили не зависят от того, что осталось в кэше.
Для проверки доступности пригодится материал о доступности Moodle для слабовидящих: именно тема чаще всего определяет, пройдёт ли сайт проверку.
Как я передаю тему заказчику
Вместе с темой заказчик получает короткую памятку: где лежат переменные цвета, как собрать стили заново, какие шаблоны заменены и что проверять после обновления Moodle. Без неё тема через год становится чёрным ящиком, а любой новый специалист начинает с того, что переписывает её с нуля. Памятка занимает страницу, и именно она позволяет сопровождать тему без меня. Если же сопровождение поручено мне, она помогает быстро вернуться к проекту после перерыва и не искать, что и почему было сделано.
Если нужны цвет, логотип и шрифт, настроек Boost достаточно. Если нужно нечто большее, сначала посмотрите готовые темы с расширенными настройками, например Boost Union: они закрывают много задач без собственного кода. Свою тему пишут, когда нужна точная разметка или нестандартные элементы. Заказать такую работу можно на странице доработки Moodle.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.