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

Вывод в Moodle: Output API, renderer и шаблоны Mustache

Как устроен вывод в Moodle: $PAGE и $OUTPUT, renderer плагина, renderable и templatable классы, шаблоны Mustache, переопределение в теме и отладка кэша шаблонов.

Как устроен вывод в Moodle: $PAGE и $OUTPUT, renderer плагина, renderable и templatable классы, шаблоны Mustache, переопределение в теме и отладка кэша шаблонов.

Вывод в 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.

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

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