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

JavaScript в плагине Moodle: AMD-модули, сборка Grunt и вызов из PHP

Как подключить JavaScript в плагине Moodle: AMD-модуль в amd/src, сборка Grunt, вызов через js_call_amd и обращение к серверу. Разбор типичных ошибок.

Как подключить JavaScript в плагине Moodle: AMD-модуль в amd/src, сборка Grunt, вызов через js_call_amd и обращение к серверу. Разбор типичных ошибок.

В 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. Тогда разметка одна, а тема может её переопределить. Эта практика заодно избавляет от ошибок вставки пользовательского текста в разметку.

Что проверить перед релизом

  1. Файлы amd/build соответствуют исходникам: пересоберите на чистой копии и убедитесь, что разницы нет.
  2. На рабочем сайте включено кэширование JavaScript и страница работает после очистки всех кэшей.
  3. Консоль браузера чиста на странице под студентом и под преподавателем.
  4. Внешняя функция проверяет контекст и права, а попытка вызвать её без права возвращает ошибку.
  5. Скрипт не падает, если элемента нет на странице.

Отладка модулей в браузере

Карта соответствия, которая собирается вместе с минифицированным файлом, позволяет видеть в инструментах разработчика исходный код, а не одну длинную строку. Если карты нет или она не подгружается, остановка по строке попадает в нечитаемый текст. Поэтому файл .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.

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

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