Вывод в Moodle устроен слоями, и каждый слой отвечает за своё. Страница знает свой контекст и заголовок, renderer собирает HTML из данных, шаблон Mustache описывает разметку. Если смешать эти слои, страницу приходится править в трёх местах, а любая попытка поменять оформление в теме превращается в правку плагина. Ниже разбор, как слои связаны, на примере списка заметок из плагина local_hello. Предыдущие статьи серии, на которые опирается пример: каркас local-плагина и формы.
Слои вывода
| Слой | Кто это | За что отвечает |
|---|---|---|
$PAGE | Объект страницы | URL, контекст, заголовок, подключение JavaScript и CSS, раскладка |
$OUTPUT | Основной renderer ядра | Шапка и подвал, заголовки, уведомления, кнопки, render_from_template() |
| Renderer плагина | Класс, унаследованный от plugin_renderer_base | Превращает renderable-объекты плагина в HTML |
| Renderable и templatable | Классы данных в classes/output/ | Хранят данные и готовят их в виде структуры для шаблона |
| Шаблон Mustache | Файл в templates/ | Только разметка и подстановка значений |
| Тема | Boost или дочерняя | Может переопределить любой шаблон и метод renderer |
Идея в том, что логика (какие данные, в каком виде) остаётся в PHP, а HTML лежит в шаблоне. Тема меняет оформление, не затрагивая данные. Такой порядок удобен и мне как разработчику: когда заказчик просит поменять расположение блоков, я правлю шаблон, а не логику.
Renderable и templatable: готовим данные
Класс страницы со списком заметок реализует два интерфейса. renderable сообщает, что объект можно передать renderer-у. templatable требует метод export_for_template(), который возвращает данные для шаблона.
<?php
namespace local_hello\output;
defined('MOODLE_INTERNAL') || die();
class notes_page implements \renderable, \templatable {
private array $notes;
public function __construct(array $notes) {
$this->notes = $notes;
}
public function export_for_template(\renderer_base $output): array {
$items = [];
foreach ($this->notes as $note) {
$items[] = [
'id' => (int) $note->id,
'title' => format_string($note->title),
'created' => userdate($note->timecreated),
];
}
return [
'hasnotes' => !empty($items),
'notes' => $items,
];
}
}
Все преобразования сосредоточены здесь: format_string() для заголовков, чтобы сработали фильтры и экранирование, userdate() для даты в часовом поясе пользователя. Шаблону достаются только готовые строки и числа. Объекты с методами в шаблон передавать нельзя, Mustache не вызывает их, как PHP.
Шаблон Mustache
Шаблон лежит в templates/notes_page.mustache. В начале принято ставить комментарий с описанием и примером данных в JSON: по нему работает библиотека шаблонов в режиме разработки, и сразу видно, какие данные ожидает шаблон.
{{!
@template local_hello/notes_page
Список заметок пользователя.
Example context (json):
{
"hasnotes": true,
"notes": [
{"id": 1, "title": "Первая заметка", "created": "10 ноября 2026, 10:00"}
]
}
}}
{{#hasnotes}}
<ul class="list-unstyled">
{{#notes}}
<li class="mb-2">
<strong>{{title}}</strong>
<span class="text-muted small">{{created}}</span>
</li>
{{/notes}}
</ul>
{{/hasnotes}}
{{^hasnotes}}
<p>{{#str}} nonotes, local_hello {{/str}}</p>
{{/hasnotes}}
| Конструкция | Значение |
|---|---|
{{title}} | Подстановка значения с экранированием HTML |
{{{html}}} | Подстановка без экранирования, только для уже безопасного HTML |
{{#список}} … {{/список}} | Цикл по массиву или блок, который показывается, если значение истинно |
{{^список}} … {{/список}} | Блок, который показывается, если значения нет или массив пуст |
{{#str}} ключ, компонент {{/str}} | Строка языка, аналог get_string() |
{{#pix}} i/edit, core {{/pix}} | Иконка Moodle |
{{! … }} | Комментарий, в вывод не попадает |
Обратите внимание на флаг hasnotes. Пустой массив в Mustache считается ложным, но явный булев флаг делает шаблон понятнее и позволяет показать сообщение «записей нет» без догадок.
Renderer плагина
Renderer связывает класс данных и шаблон. Его кладут в classes/output/renderer.php; ядро находит такой класс по имени компонента, когда вы просите renderer у страницы.
<?php
namespace local_hello\output;
defined('MOODLE_INTERNAL') || die();
class renderer extends \plugin_renderer_base {
public function render_notes_page(notes_page $page): string {
$data = $page->export_for_template($this);
return $this->render_from_template('local_hello/notes_page', $data);
}
}
Имя метода строится как render_ плюс имя класса данных: так $output->render($page) понимает, какую функцию вызвать. Первый аргумент render_from_template() это идентификатор шаблона в форме «компонент/имя файла без расширения».
На странице всё сводится к трём строкам:
$output = $PAGE->get_renderer('local_hello');
$notes = $DB->get_records('local_hello_note', ['userid' => $USER->id], 'timecreated DESC');
echo $OUTPUT->header();
echo $output->render(new \local_hello\output\notes_page(array_values($notes)));
echo $OUTPUT->footer();
Обратите внимание на array_values(): результат get_records() индексирован идентификаторами, а Mustache лучше работает с обычным списком.
Переопределение в теме
Преимущество шаблонов в том, что любую разметку можно заменить, не трогая плагин. Для этого файл с тем же именем кладут в тему: theme/имя_темы/templates/local_hello/notes_page.mustache. Дочерняя тема на базе Boost подхватит его автоматически после очистки кэша. Поэтому ставить шаблоны плагина в зависимость от конкретной темы не нужно; оформление под бренд организации делают в теме. Как это устроено на практике, будет в отдельной статье про дочернюю тему Boost.
Кэш шаблонов и отладка
Moodle кэширует скомпилированные шаблоны, и это главная причина вопросов «я правлю файл, а страница не меняется». На тестовом сервере включите режим разработки темы в разделе администрирования внешнего вида: тогда кэш шаблонов и стилей не используется. На рабочем сайте этот режим выключен, там достаточно «Очистить все кэши» после выкладки. Для проверки шаблона отдельно от страницы в Moodle есть библиотека шаблонов: страница в разделе разработки администрирования, которая рисует шаблон по примеру данных из комментария.
Частые ошибки
| Симптом | Причина | Решение |
|---|---|---|
| Шаблон не найден | Опечатка в идентификаторе или файл не в templates/ | Проверить формат «компонент/имя», очистить кэш |
| Значение не показывается | Ключ в данных не совпадает с именем в шаблоне, или передан объект с методом | Передавать массивы и скаляры, сверить имена |
| В тексте видны теги HTML | Текст экранирован двойными скобками | Обработать через format_text() в PHP и вывести тройными скобками |
| XSS через пользовательский ввод | Сырой текст выведен тройными скобками | Никогда не выводить необработанные данные пользователя без экранирования |
| Список показывается пустым | Передан массив с нечисловыми ключами | Применить array_values() |
| Дата в UTC вместо времени пользователя | Использован date() | Применять userdate() |
Подготовка страницы: что задать через $PAGE
Перед выводом шапки страница должна сообщить ядру, чем она является. Объект $PAGE собирает эти сведения, и от них зависят навигация, заголовок вкладки, подключаемые стили и даже то, какой шаблон оформления выберет тема.
| Метод | Что задаёт | Если пропустить |
|---|---|---|
set_url() | Адрес страницы | Предупреждение отладки, ломаются хлебные крошки и переключение языка |
set_context() | Контекст страницы | Ядро не знает, какие права и блоки применять |
set_title() | Заголовок вкладки браузера | В заголовке окажется адрес или название сайта |
set_heading() | Заголовок в шапке страницы | Пустая шапка |
set_pagelayout() | Раскладка: standard, admin, report и другие | Применяется раскладка по умолчанию |
Для страниц администрирования функция admin_externalpage_setup() выставляет всё сразу, для остальных вы вызываете методы самостоятельно. Раскладку выбирайте по смыслу: для таблиц на всю ширину подойдёт report, для обычного контента standard.
JavaScript рядом с шаблоном
Динамике нужен JavaScript, и подключается он в современном Moodle только в виде AMD-модулей. Из PHP модуль подключают одной строкой, передавая параметры:
$PAGE->requires->js_call_amd('local_hello/notes', 'init', [
['selector' => '[data-region="notes"]'],
]);
Модуль лежит в amd/src/notes.js, а собранный файл в amd/build. Элементы, к которым привязан скрипт, помечайте атрибутами data-region и data-action, а не классами оформления: классы меняет тема, а атрибуты остаются. То же можно сделать из самого шаблона блоком {{#js}}, если скрипт относится только к этому шаблону. Сборка и ошибки AMD-модулей будут в отдельной статье следующей партии про JavaScript в плагине.
Сообщения пользователю и редиректы
Результат действия показывайте стандартными уведомлениями, а не самодельным HTML. Метод $OUTPUT->notification() выводит сообщение сразу, а при редиректе текст передают третьим аргументом функции redirect() вместе с типом уведомления. Тема отрисует их единообразно, а пользователи привыкнут к знакомому виду. Тексты берите из языковых файлов, как в статье про локализацию.
Доступность и семантика
Шаблоны проверяют на доступность: у кнопок-иконок должен быть текст для программ чтения с экрана, у таблиц заголовки с атрибутом scope, у форм подписи. Для образовательных организаций это не прихоть: версия для слабовидящих входит в требования к сайту и СДО, о них я писала в статье про доступность Moodle. Для иконки без подписи добавляйте скрытый текст или атрибут aria-label. Классы Bootstrap, которые использует Boost, можно применять в шаблонах: они уже стилизованы темой.
Как добавить шаблон в существующий проект без переписывания
В работающем плагине обычно уже есть вывод через echo и html_writer. Переписывать всё сразу не нужно. Я перевожу экраны по одному: берётся самый часто редактируемый, под него создаются renderable-класс и шаблон, а остальное остаётся как есть. При каждой правке плагина старый экран по возможности переносится на новую схему. Через несколько релизов остаётся лишь пара служебных страниц. Такой путь безопаснее полной переделки и сразу даёт выигрыш там, где заказчик чаще всего просит поправить внешний вид.
Если вывод плагина большой, полезно сначала нарисовать данные: записать на бумаге, какие поля нужны шаблону, и только затем писать export_for_template(). Хорошо спроектированная структура данных часто упрощает и сам шаблон, который превращается в последовательность простых блоков без вложенных условий.
Когда хватит html_writer
Класс html_writer остаётся удобным для мелких вставок: ссылка, абзац, таблица из десятка строк. Для нового экрана с несколькими блоками я выбираю шаблоны, потому что тогда заказчик может изменить внешний вид, не заказывая правку плагина. Если вам нужен кабинет или отчёт с аккуратным интерфейсом под ваш бренд, посмотрите, как я делаю печатные формы и интерфейсы на странице доработки Moodle.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.