Тип вопроса — один из немногих плагинов, у которых есть чёткая граница: у вопроса три задачи, и каждая задача лежит в отдельном классе. Как показать вопрос студенту. Как сохранить ответ. Как поставить оценку. Если помнить об этом разделении, плагин пишется спокойно. Ниже порядок, в котором я его собираю, и места, где ошибки обнаруживаются не сразу. Контекст дополнительной разработки для СДО — на странице доработки Moodle.
Пример задачи
Для примера возьму простой тип «Набор ключевых слов». Студент пишет развёрнутый короткий ответ, преподаватель задаёт список слов, которые должны в нём встретиться, оценка пропорциональна доле найденных. Штатный короткий ответ сравнивает строку целиком, поэтому для такого случая не подходит. Тип несложный, но на нём видны все части плагина.
Из чего состоит плагин
Каталог называется question/type/keywords, компонент — qtype_keywords.
| Файл | Что внутри |
|---|---|
version.php | Версия и компонент |
questiontype.php | Класс qtype_keywords (наследует question_type): сохранение настроек вопроса, загрузка из базы |
question.php | Класс qtype_keywords_question: поведение вопроса в попытке, проверка ответа |
renderer.php | Класс qtype_keywords_renderer: HTML вопроса и обратной связи |
edit_keywords_form.php | Форма создания и редактирования вопроса преподавателем |
db/install.xml | Таблица с настройками вопроса |
backup/moodle2/ | Классы резервного копирования и восстановления |
lang/ | Строки интерфейса |
Шаг 1. Хранение настроек
Настройки вопроса, то есть список слов и порог, хранят в своей таблице qtype_keywords_options с полем questionid. Стандартные поля вопроса (название, текст, общая обратная связь) Moodle сохраняет сам. Для простых типов достаточно перечислить свои поля в методе extra_question_fields: базовый класс тогда сам прочитает и запишет строку в таблицу.
public function extra_question_fields() {
return ['qtype_keywords_options', 'keywords', 'casesensitive'];
}
Первый элемент массива — имя таблицы, остальные — поля. Если настройки сложнее, например отдельные строки для каждого слова с весом, переопределяют save_question_options и get_question_options и работают с таблицами вручную. Помните, что при редактировании вопроса сохранённые строки надо обновлять, а не создавать заново: от идентификаторов строк могут зависеть история попыток и статистика.
Метод initialise_question_instance переносит данные из базы в объект вопроса. Здесь вы копируете свои поля в свойства класса вопроса, чтобы проверка работала без обращения к базе.
Шаг 2. Класс вопроса и проверка ответа
Класс вопроса наследует question_graded_automatically. Он должен ответить на вопросы, которые движок задаёт во время попытки.
| Метод | Что должен вернуть |
|---|---|
get_expected_data() | Имена полей ответа и их типы очистки, например ['answer' => PARAM_RAW] |
summarise_response(array $response) | Краткий текст ответа для отчётов |
is_complete_response(array $response) | Достаточно ли введено, чтобы проверять |
is_gradable_response(array $response) | Можно ли ставить оценку |
get_validation_error(array $response) | Сообщение, если ответ неполный |
is_same_response(array $prevresponse, array $newresponse) | Совпадают ли два ответа; от этого зависит, считать ли сохранение новым шагом |
get_correct_response() | Пример правильного ответа или пусто |
grade_response(array $response) | Оценка |
Метод оценки возвращает массив из двух элементов: долю от единицы и состояние, которое получается вызовом question_state::graded_state_for_fraction. Основная логика умещается в несколько строк.
public function grade_response(array $response) {
$text = $response['answer'] ?? '';
$found = 0;
foreach ($this->wordlist as $word) {
if (mb_stripos($text, $word) !== false) {
$found++;
}
}
$fraction = count($this->wordlist)
? $found / count($this->wordlist)
: 0;
return [$fraction, question_state::graded_state_for_fraction($fraction)];
}
Заметьте, что поиск идёт многобайтовой функцией: кириллица и обычный stripos вместе работают непредсказуемо. Пустой список слов не должен приводить к делению на ноль, иначе вопрос с ошибкой в настройках положит страницу попытки студента.
Шаг 3. Рендер
Класс отрисовки наследует qtype_renderer. Главный метод — formulation_and_controls, он получает попытку и параметры показа и возвращает HTML.
public function formulation_and_controls(
question_attempt $qa, question_display_options $options) {
$question = $qa->get_question();
$name = $qa->get_qt_field_name('answer');
$current = $qa->get_last_qt_var('answer');
$input = html_writer::tag('textarea', s($current), [
'name' => $name,
'rows' => 4,
'class' => 'form-control',
'readonly' => $options->readonly ? 'readonly' : null,
]);
return html_writer::tag('div',
$question->format_questiontext($qa), ['class' => 'qtext']) .
html_writer::tag('div', $input, ['class' => 'ablock']);
}
Имя поля нельзя придумывать: его выдаёт get_qt_field_name, иначе ответ не дойдёт до движка. Значение из базы выводят через s(), чтобы введённый текст не превратился в разметку. В режиме просмотра результатов параметры показа сообщают, что поле должно быть только для чтения.
Шаг 4. Форма преподавателя
Форма наследует question_edit_form. Достаточно переопределить definition_inner и добавить свои элементы, а общие поля вопроса форма создаст сама.
protected function definition_inner($mform) {
$mform->addElement('textarea', 'keywords',
get_string('keywords', 'qtype_keywords'), ['rows' => 4]);
$mform->addRule('keywords', null, 'required', null, 'client');
$mform->addElement('advcheckbox', 'casesensitive',
get_string('casesensitive', 'qtype_keywords'));
$this->add_hints($mform);
}
public function qtype() {
return 'keywords';
}
Названия полей формы должны совпадать с именами полей, которые вы перечислили в extra_question_fields. Расхождение в одну букву даёт самую неприятную ошибку: форма сохраняется без сообщений, а при повторном открытии поле пустое.
Шаг 5. Резервные копии
Этот шаг пропускают, потому что без него тестирование на живом курсе ничем не отличается. А вот при восстановлении курса из копии настройки вопроса теряются. В каталоге backup/moodle2 нужно объявить класс копирования и класс восстановления, которые перечисляют вашу таблицу и её поля. Образцом может служить любой штатный простой тип, например числовой вопрос.
Проверка перед релизом
- Создать вопрос, пройти тест в режиме с отложенной обратной связью и в режиме с немедленной проверкой.
- Оставить ответ пустым и неполным, убедиться, что проверка не падает.
- Сохранить курс в копию и восстановить его на другом сайте.
- Проверить вопрос в отчётах теста и в статистике: если метод краткого описания ответа возвращает пустоту, отчёт становится бесполезным.
- Написать тест PHPUnit на метод оценки с крайними значениями: пустой ответ, все слова, часть слов.
Частые ошибки при разработке типа вопроса
| Симптом | Причина | Решение |
|---|---|---|
| Настройки пропадают при повторном открытии вопроса | Имена полей формы не совпадают с extra_question_fields | Сверить имена посимвольно |
| Ответ студента не сохраняется | Имя поля придумано вручную, а не выдано get_qt_field_name | Использовать метод попытки |
| Ошибка при открытии вопроса из банка | Нет метода initialise_question_instance или он не копирует поля | Скопировать все нужные свойства |
| В отчёте теста пустые ответы | Метод summarise_response возвращает пустоту | Вернуть читаемую строку ответа |
| Оценка выше единицы или ниже нуля | Не ограничен результат расчёта | Ограничивать долю в диапазоне от нуля до единицы |
| После восстановления курса настройки пусты | Не описаны классы резервного копирования | Добавить классы в backup/moodle2 |
Версии вопросов и жизнь вопроса в банке
Начиная с версии 4.0 вопросы в банке версионируются: при редактировании создаётся новая версия, а попытки студентов остаются привязаны к той, на которую отвечали. Для плагина это значит, что настройки вопроса должны принадлежать конкретной версии, а не «вопросу вообще». Если вы храните свои данные по идентификатору вопроса, который меняется между версиями, и обновляете строку на месте, то у старых попыток изменятся правила оценки задним числом. Для простых типов с extra_question_fields об этом заботится ядро, для собственных таблиц с несколькими строками придётся проверять поведение вручную: отредактируйте вопрос после попытки и убедитесь, что результат прошлой попытки не изменился.
Случай: когда штатного типа не хватило
В вступительном тестировании и проверке знаний часто нужны ответы, которые штатные типы оценивают плохо: строка, где порядок слов неважен, но важен их набор; ввод в нескольких полях сразу. Прежде чем писать плагин, я проверяю, нельзя ли обойтись вычисляемым типом, вопросом на соответствие или коротким ответом с шаблонами. Пример, который закрывается штатным коротким ответом: вопрос с несколькими допустимыми написаниями. Он не требует кода, только внимательной настройки вариантов и регистра. Свой тип вопроса оправдан тогда, когда без него преподаватель вынужден проверять ответы вручную, а число таких ответов велико. Поддержка такого плагина потом ложится на того, кто его написал, и об этом нужно говорить заранее.
Про сам банк вопросов и организацию больших тестов у меня есть отдельная статья про банк вопросов в Moodle. Когда типа вопроса не хватает для ваших тестов, пришлите пример одного такого задания: часто видно, что делается штатным типом, а что без плагина не обойти.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.