Перейти к содержимому
M
Все статьи
Разработка 8 мин чтения

Дочерняя тема Moodle на базе Boost: SCSS, переопределение шаблонов и обновляемость

Как сделать дочернюю тему Moodle на базе Boost: config.php, SCSS, переопределение шаблонов Mustache и рендерера, переход на Bootstrap 5 и работа с обновлениями.

Как сделать дочернюю тему Moodle на базе Boost: config.php, SCSS, переопределение шаблонов Mustache и рендерера, переход на Bootstrap 5 и работа с обновлениями.

Дочерняя тема нужна, когда настроек 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-targetdata-bs-toggle, data-bs-target
ml-*, mr-*ms-*, me-*
pl-*, pr-*ps-*, pe-*
float-left, text-leftfloat-start, text-start
sr-onlyvisually-hidden
font-weight-boldfw-bold

Копии шаблонов в теме не получают этих замен сами, поэтому после перехода их приходится править вручную. Это ещё одна причина держать как можно меньше переопределений. При обновлении СДО центра ДПО до 5.2 я именно так оценивала объём работы: сначала считала, сколько шаблонов и стилей в теме и плагинах, завязанных на старые имена. Порядок такой работы описан на странице про обновление Moodle.

Когда дочерняя тема не нужна

Типичные ошибки дочерних тем

ОшибкаПоследствиеРешение
Правка файлов Boost напрямуюИзменения пропадают при обновленииПереносить правки в дочернюю тему
Копия шаблона целиком ради одной строкиШаблон устаревает, теряет новые атрибутыЕсли можно, использовать стили; менять шаблон только когда без этого нельзя
Жёсткие цвета в post.scssНе меняются от настроек, не подходят под тёмные элементыЗадавать переменные Bootstrap в функции «до»
Селекторы по классам оформления вместо ролейЛомаются при смене версии BootstrapПривязываться к структуре и атрибутам, где возможно
Нет зависимости от theme_boost в version.phpТему можно поставить без родителя, сайт ломаетсяОбъявить зависимость
Режим разработчика оставлен на рабочем сайтеСтраницы грузятся медленноВключать только на тестовой копии

Список переопределённых шаблонов

Я веду в каталоге темы короткий файл, который не участвует в работе, но нужен людям: список шаблонов и классов вывода, которые тема заменяет, с причиной и версией Moodle, из которой был взят оригинал. Выглядит это как обычная таблица. Через год она отвечает на вопрос, который иначе остаётся без ответа: почему в этом месте шаблон отличается от ядра, и можно ли вернуть штатный.

ШаблонПричина заменыВерсия ядра оригиналаПроверено после обновления
core/loginformДобавлена пояснительная ссылкаУказывается номер версииДата проверки
theme_college/footer_linksСобственный шаблон, оригинала нетНе применимоДата проверки

После каждого обновления я сравниваю замененные шаблоны с оригиналами нового выпуска. Команда сравнения каталогов покажет различия за минуты. Если в оригинале появились новые атрибуты или блоки, их переносят в копию.

Проверка темы перед релизом

  1. Откройте главную, курс, страницу входа, личную панель, профиль, тест и форум. На этих страницах тема встречается чаще всего.
  2. Проверьте телефон и планшет. Закреплённые боковые панели и выпадающие меню ломаются на узких экранах первыми.
  3. Проверьте контраст текста и фона. Это требование доступности, и для образовательных организаций оно не формальность.
  4. Включите режим редактирования: новые панели и кнопки не должны перекрываться элементами темы.
  5. Очистите кэши и убедитесь, что стили не зависят от того, что осталось в кэше.

Для проверки доступности пригодится материал о доступности Moodle для слабовидящих: именно тема чаще всего определяет, пройдёт ли сайт проверку.

Как я передаю тему заказчику

Вместе с темой заказчик получает короткую памятку: где лежат переменные цвета, как собрать стили заново, какие шаблоны заменены и что проверять после обновления Moodle. Без неё тема через год становится чёрным ящиком, а любой новый специалист начинает с того, что переписывает её с нуля. Памятка занимает страницу, и именно она позволяет сопровождать тему без меня. Если же сопровождение поручено мне, она помогает быстро вернуться к проекту после перерыва и не искать, что и почему было сделано.

Если нужны цвет, логотип и шрифт, настроек Boost достаточно. Если нужно нечто большее, сначала посмотрите готовые темы с расширенными настройками, например Boost Union: они закрывают много задач без собственного кода. Свою тему пишут, когда нужна точная разметка или нестандартные элементы. Заказать такую работу можно на странице доработки Moodle.

Нужна помощь с Moodle?

Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.