Плагину нужна ссылка: «Отчёт по группе» внутри курса, «Мои документы» в профиле, страница настроек в администрировании. В Moodle такие места называются точками расширения навигации, и подходящая зависит от того, кому и где показывать. В версиях 4.0 и новее навигация была перестроена, и многие инструкции времён Moodle 3 в ней неактуальны. Ниже — какие точки есть, как в них добавлять узлы и где у системы жёсткие границы.
Что изменилось в Moodle 4
До версии 4.0 был блок «Навигация» и блок «Настройки» со вложенными деревьями. Теперь интерфейс устроен иначе: сверху основная (primary) навигация с несколькими фиксированными пунктами, ниже вторичная (secondary) для текущего контекста — курса или модуля (вкладки «Курс», «Участники», «Оценки» и «Ещё»), слева выдвижной индекс курса. Деревья навигации в коде остались, но выводятся по-новому: часть узлов, добавленных плагином, попадает во вторичную навигацию, остальное — в выпадающий пункт «Ещё». Справочная информация — в документации по Navigation API.
Точки расширения
Каждая точка — функция в lib.php плагина с именем из компонента и суффикса. Ядро ищет её само, регистрировать ничего не нужно.
| Функция в lib.php | Где проявляется | Для чего |
|---|---|---|
local_имя_extend_navigation(global_navigation $nav) | Глобальная навигация | Узлы на уровне сайта; в 4.x основное меню этим способом не наполняется |
local_имя_extend_navigation_course($navigation, $course, $context) | Вторичная навигация курса | Ссылки на страницы плагина внутри курса |
local_имя_extend_navigation_user($navigation, $user, $usercontext, $course, $coursecontext) | Профиль пользователя | Ссылки вроде «Документы» в профиле |
local_имя_extend_navigation_user_settings($navigation, $user, $usercontext, $course, $coursecontext) | Настройки пользователя | Личные настройки плагина |
local_имя_extend_navigation_category_settings(...) | Настройки категории курсов | Административные ссылки категории |
имя_модуля_extend_settings_navigation($settings, $node) | Настройки элемента курса | Дополнительные пункты в меню модуля |
Приставка local_ заменяется на тип и имя вашего плагина: для блока это block_имя_..., для модуля mod_имя_.... Список поддерживаемых функций и их сигнатуры сверяйте в документации вашей версии: набор сохранялся в 4.x, но детали отдельных параметров могут отличаться.
Ссылка в курсе
Пример: преподавателю курса нужен пункт «Отчёт по группе»:
function local_example_extend_navigation_course(
navigation_node $navigation,
stdClass $course,
context_course $context
) {
if (!has_capability('local/example:viewgroupreport', $context)) {
return;
}
$url = new moodle_url('/local/example/groupreport.php', ['id' => $course->id]);
$navigation->add(
get_string('groupreport', 'local_example'),
$url,
navigation_node::TYPE_CUSTOM,
null,
'local_example_groupreport',
new pix_icon('i/report', '')
);
}
Ключ (пятый параметр) должен быть уникальным: по нему узел можно найти, а также обращаться к нему из других плагинов. Проверка права обязательна: функция вызывается на каждой странице курса, и без неё ссылка увидят все. Но и этого недостаточно. Целевая страница groupreport.php должна сама вызывать require_login() и require_capability(): узел меню скрывает ссылку, а не закрывает доступ. Прямой адрес можно ввести вручную.
Узел добавляется для текущего пользователя и текущего курса, поэтому результат зависит от кэша навигации. Если после изменения условий пункт не появляется или не пропадает, очистите кэши и проверьте, что вы не кэшируете собственный результат: про MUC в соседней статье.
Ссылка в профиле и пользовательских настройках
Структура похожая, меняются параметры. Для профиля подходит extend_navigation_user: если пользователь смотрит чужой профиль, проверьте, имеет ли он право видеть эту ссылку, и вспомните, что в $user лежит просматриваемый пользователь, а не текущий. Так делают, например, ссылку «Документы слушателя», которую видит сам слушатель и методист, но не соседний слушатель. Для личного кабинета, заменяющего стандартную панель, обычно хватает отдельной страницы и пункта в пользовательском меню.
Главное меню и пользовательское меню
Главное меню в 4.x не расширяется функциями плагина: в него попадают фиксированные пункты ядра и то, что администратор добавил в «Внешний вид → Темы → Настройки темы → Пользовательское меню». Туда можно вписать ссылку на страницу плагина в простом формате «текст|адрес». Это работает и для меню пользователя (настройка пользовательских пунктов меню профиля). Более сложную логику, например показывать пункт только определённой роли, придётся решать на уровне темы или собственной темы, которую вы контролируете. Если вам для этого нужна тема, её доработку удобнее вести как отдельный проект: доработка Moodle.
Страница в администрировании
Страницы плагина для администратора добавляются не через lib.php, а через settings.php. Пример страницы отчёта в разделе локальных плагинов:
defined('MOODLE_INTERNAL') || die();
if ($hassiteconfig) {
$ADMIN->add('localplugins', new admin_externalpage(
'local_example_report',
get_string('adminreport', 'local_example'),
new moodle_url('/local/example/admin/report.php'),
'local/example:viewreport'
));
}
Четвёртый параметр — право, при котором страница показывается. На самой странице используют admin_externalpage_setup('local_example_report'): этот вызов проверяет вход, права и встраивает страницу в административную навигацию. Подробнее про страницы настроек писала в статье про settings.php и admin tree.
Ошибки, которые встречаются чаще всего
| Симптом | Причина | Что делать |
|---|---|---|
| Пункт не появляется | Неверное имя функции или компонента, не очищен кэш | Проверить имя, очистить кэши, включить отладку |
| Пункт виден всем, включая студентов | Нет проверки права в функции | Добавить has_capability для нужного контекста |
| Ссылка есть, страница открывается без прав | Целевая страница не проверяет доступ | require_login и require_capability в начале скрипта |
| Пункт ушёл в раздел «Ещё» | Особенность вторичной навигации 4.x | Принять поведение или обсудить настройки темы |
| Нет иконки | Неверный ключ иконки или тема её не поддерживает | Выбрать иконку из стандартного набора |
| Пункт не пропадает после смены роли | Результат навигации закэширован | Очистить кэши и перелогиниться |
Помните, что экраны для мобильного приложения Moodle устроены иначе: расширять его меню через navigation нельзя, для приложения нужны отдельные настройки и веб-сервисы, о чём можно прочитать в материале про мобильное приложение.
Узел навигации изнутри
Все точки расширения работают с объектами класса navigation_node. Узел имеет текст, адрес, тип, ключ и иконку, умеет иметь потомков и искать их по ключу. Метод add() создаёт и возвращает новый узел, а add_node() принимает готовый. Положение узла в новой навигации определяют несколько свойств: например, можно управлять тем, показывать ли узел во вторичной навигации, и принудительно отправлять ли его в раздел «Ещё». Названия таких свойств лучше сверять с классом в вашей версии Moodle, потому что в ветках 4.x их набор расширялся. По сути вы описываете «что и где», а «как выглядит» решает тема.
Если нужно найти уже существующий узел, чтобы добавить свой рядом или под ним, используйте поиск по ключу из навигационного дерева. Но привязываться к чужим ключам рискованно: после обновления ядра ключ может исчезнуть, и ваш код перестанет находить опору. Всегда проверяйте результат поиска на null и в крайнем случае добавляйте узел в корень.
Блок как альтернатива
Если пункт навигации не подходит, потому что нужен постоянно заметный элемент на странице курса (прогресс, быстрые ссылки, баннер), используют блок. Плагин блока размещается на нужных страницах, имеет собственные настройки и права добавления. Блок виден всем, кому доступна страница, поэтому содержимое выбирают с учётом роли внутри кода блока. Для кабинета слушателя, где ссылки нужны на главной, блок и страница удобнее, чем меню, закопанное в раздел «Ещё». Какие бывают типы плагинов и как выбрать нужный, разобрано в статье про типы плагинов.
Проверка и доступность
Добавленный узел нужно проверить под разными ролями: преподаватель, студент, гость, администратор. Удобно открыть сайт «от имени» тестового пользователя через вход под другой ролью и посмотреть меню курса. В автоматических тестах для этого есть сценарии Behat, но для небольших плагинов хватает ручной проверки по списку ролей. Названия пунктов делайте короткими и понятными без контекста: в разделе «Ещё» они выстраиваются в столбец, а скринридер читает их подряд. Это же относится к доступности для слабовидящих: описательный текст ссылки важнее иконки. Требования к доступности СДО обсуждались в отдельной статье про ГОСТ Р 52872.
Второй пример: пункт в настройках элемента
Для модулей действует своя точка: функция имя_модуля_extend_settings_navigation получает навигацию настроек и узел, в который можно добавить пункты. Так добавляют, например, ссылку на отчёт по конкретному заданию:
function mod_example_extend_settings_navigation(settings_navigation $settings, navigation_node $node) {
global $PAGE;
if (!has_capability('mod/example:viewreport', $PAGE->cm->context)) {
return;
}
$url = new moodle_url('/mod/example/report.php', ['id' => $PAGE->cm->id]);
$node->add(get_string('report', 'mod_example'), $url, navigation_node::TYPE_SETTING);
}
Здесь тоже проверка права идёт до добавления узла, а целевой скрипт повторяет её сам.
Методы узла: справка
| Метод | Для чего |
|---|---|
navigation_node::create() | Создать узел без добавления в дерево |
add() | Создать дочерний узел и вернуть его |
add_node() | Добавить уже созданный узел |
find() | Найти узел по ключу и типу |
make_active() | Подсветить узел как текущий |
get() | Получить дочерний узел по ключу |
С чего начать
Перед написанием кода ответьте на три вопроса: кто видит пункт, в каком контексте (сайт, курс, профиль, категория) и какой странице он ведёт. Из ответов выбирается точка расширения и условие в функции. Если в вашей СДО нужны новые разделы для кураторов, методистов или слушателей, начните со списка ролей и страниц, а реализацию можно обсудить на странице программиста Moodle.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.