В Moodle JavaScript плагина — это не файл, который подключают тегом, а модуль в формате AMD: у него есть имя, он собирается инструментом и вызывается из PHP по этому имени. Если сделать иначе, скрипт либо не загрузится, либо загрузится в неверном порядке, либо сломается после очистки кэша. Ниже путь от исходника до работающей кнопки и разбор ошибок, с которыми я сталкивалась сама. Для общего представления о структуре плагина смотрите страницу про разработку плагинов.
Где что лежит
| Путь | Назначение |
|---|---|
amd/src/stats.js | Исходник модуля. Его вы пишете |
amd/build/stats.min.js | Собранный и минимизированный файл. Его загружает Moodle |
amd/build/stats.min.js.map | Карта соответствия для отладки в браузере |
templates/*.mustache | Шаблоны, которые JavaScript может отрисовать |
db/services.php | Описание внешних функций, доступных из JavaScript |
classes/external/ | Классы внешних функций |
Имя модуля строится из компонента и имени файла: файл amd/src/stats.js в плагине local_gradebook называется local_gradebook/stats. Так же его вызывают из PHP.
Пишем модуль
Современные версии Moodle принимают модули в синтаксисе ES6: импорты и экспорт. Сборка превращает их в AMD. Пример: кнопка, по нажатию которой запрашиваются данные и показывается сообщение об ошибке, если запрос не удался.
import Ajax from 'core/ajax';
import Notification from 'core/notification';
export const init = (courseId) => {
const button = document.querySelector('[data-action="gb-refresh"]');
if (!button) {
return;
}
button.addEventListener('click', async(e) => {
e.preventDefault();
try {
const result = await Ajax.call([{
methodname: 'local_gradebook_get_stats',
args: {courseid: courseId},
}])[0];
button.textContent = result.total;
} catch (error) {
Notification.exception(error);
}
});
};
Обратите внимание на три вещи. Модуль не обращается к элементам страницы при загрузке, а делает это внутри init, который вызывает PHP. Селектор строится по атрибуту data-action, а не по классу оформления: классы меняются вместе с темой. Ошибки отдаёт Notification.exception, поэтому пользователь видит стандартное окно Moodle, а не молчание.
Сборка
Сборкой занимается Grunt. Он запускается из корня Moodle, поэтому понадобится Node нужной версии и установленные зависимости. Версия Node записана в файле .nvmrc.
cd /var/www/moodle
nvm use
npm ci
npx grunt amd --root=local/gradebook
Параметр --root ограничивает сборку каталогом вашего плагина, без него Grunt проверит и пересоберёт модули всего Moodle, а на большой установке это долго. После сборки проверьте, что в amd/build появились .min.js и .map и что в списке изменённых файлов только ваши. Если в список попали чужие модули, значит, ваша версия Node или зависимостей отличается от той, под которую собиралось ядро.
Во время разработки удобно запускать npx grunt watch: он пересобирает файлы при сохранении. Параллельно на тестовой копии отключают кэширование JavaScript параметром $CFG->cachejs = false;, иначе Moodle и браузер будут отдавать старую версию. На рабочем сайте этот параметр должен стоять включённым.
Вызов из PHP
Модуль подключают на странице вызовом js_call_amd: имя модуля, имя экспортированной функции и массив аргументов.
$PAGE->requires->js_call_amd('local_gradebook/stats', 'init', [$course->id]);
Аргументы превращаются в JSON, поэтому передавайте числа, строки и массивы, а не объекты с поведением. Вызов делают до вывода подвала страницы. Если вы строите страницу и забыли про подвал, скрипт не будет подключён, и в консоли не окажется никаких сообщений: это одна из самых неприятных причин «ничего не происходит».
Обращение к серверу
Для запросов с JavaScript используют внешние функции. Вы описываете функцию в db/services.php с признаком ajax и пишете класс в classes/external.
$functions = [
'local_gradebook_get_stats' => [
'classname' => 'local_gradebook\external\get_stats',
'description' => 'Сводка по курсу',
'type' => 'read',
'ajax' => true,
],
];
Класс описывает три метода: параметры, выполнение и описание ответа. Базовый класс внешних функций в версиях с 4.2 находится в пространстве core_external, в более ранних — в external_api из библиотеки веб-служб. Внутри выполнения проверяют параметры, контекст и права через стандартные вызовы, как в любом коде Moodle. Если права не проверены, функция доступна любому вошедшему пользователю, и JavaScript здесь ничего не защищает.
После добавления или изменения db/services.php нужно поднять версию в version.php и выполнить обновление, иначе Moodle не узнает о новой функции.
Разбор ошибок
| Симптом | Причина | Решение |
|---|---|---|
| Модуль не найден, ошибка загрузки в консоли | Не собран файл в amd/build или неверное имя модуля | Собрать, сверить компонент и имя файла, очистить кэши |
| Правка исходника не действует | Грузится старый собранный файл или кэш браузера | Пересобрать, отключить cachejs на тесте, жёсткая перезагрузка |
| Ничего не происходит, ошибок нет | Вызов js_call_amd не выполнился до подвала или элемент не найден | Проверить порядок вывода и селектор, добавить проверку на пустой результат |
Функция init не определена | Не экспортирована или в вызове другое имя | Проверить export и аргумент вызова |
| Ошибка о неизвестном методе при AJAX | Функция не зарегистрирована | Поднять версию плагина и выполнить обновление |
| Строки не переводятся | Строка запрошена без загрузки | Получать через модуль core/str и не вшивать в код |
| Сборка показывает изменения в чужих файлах | Другая версия Node или зависимостей | Вернуть версию из .nvmrc и выполнить npm ci |
Шаблоны на стороне клиента
Если JavaScript должен вывести список или таблицу, не склеивайте HTML строками. Подключите модуль core/templates и отрисуйте тот же шаблон Mustache, который использует PHP. Тогда разметка одна, а тема может её переопределить. Эта практика заодно избавляет от ошибок вставки пользовательского текста в разметку.
Что проверить перед релизом
- Файлы
amd/buildсоответствуют исходникам: пересоберите на чистой копии и убедитесь, что разницы нет. - На рабочем сайте включено кэширование JavaScript и страница работает после очистки всех кэшей.
- Консоль браузера чиста на странице под студентом и под преподавателем.
- Внешняя функция проверяет контекст и права, а попытка вызвать её без права возвращает ошибку.
- Скрипт не падает, если элемента нет на странице.
Отладка модулей в браузере
Карта соответствия, которая собирается вместе с минифицированным файлом, позволяет видеть в инструментах разработчика исходный код, а не одну длинную строку. Если карты нет или она не подгружается, остановка по строке попадает в нечитаемый текст. Поэтому файл .map не удаляют из каталога сборки. Перед проверкой откройте вкладку сети: убедитесь, что запрошен нужный файл модуля и сервер вернул его без ошибки. Если вернулась страница с ошибкой, дело в пути или правах на файл. Если запрошен старый файл, это кэш.
Ещё один приём: временно вызвать функцию модуля из консоли. Для этого используют загрузчик Moodle, а не обращение к переменной, потому что модуль не лежит в глобальной области.
require(['local_gradebook/stats'], function(stats) {
stats.init(2);
});
Этот фрагмент вводят прямо в консоль браузера на нужной странице. Если он отрабатывает, а при обычной загрузке ничего не происходит, значит, не хватает вызова из PHP, и искать надо там.
Передача строк и переводов
Любой текст, который видит пользователь, не должен жить в JavaScript строкой на русском. Строки берут из языковых файлов плагина через модуль core/str: он запрашивает их у сервера и кэширует в браузере. Если строка нужна сразу при загрузке, её передают заранее, перечислив при подключении страницы, чтобы не ждать запроса. Тогда интерфейс работает и на английском, и на русском без изменений кода, а переводчик правит один файл.
import {get_string as getString} from 'core/str';
const label = await getString('refresh', 'local_gradebook');
button.setAttribute('title', label);
Случай из практики
Типичная история при доработке чужого плагина: кнопка «обновить» в отчёте работает у разработчика и не работает на рабочем сайте. Причин три, и они повторяются. Первая: собранный файл не закоммичен, и на сервер попал только исходник. Вторая: на рабочем сайте включён кэш JavaScript, а версию плагина не подняли, поэтому браузеры продолжают получать прежний файл. Третья: другая версия Node дала при сборке файл с иными именами зависимостей. Проверяю в таком порядке: есть ли файл в amd/build, поднята ли версия, что показывает вкладка сети. Чаще всего разбор укладывается в несколько минут, если идти по списку, а не по догадкам. Похожие ситуации я разбираю как срочную помощь программиста.
Если нужно оживить форму или отчёт в уже существующем плагине, а хорошо знающего JavaScript разработчика Moodle под рукой нет, пишите: объём такой доработки обычно небольшой. Подробности — на странице доработки Moodle.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.