Перейти к содержимому
M
Все статьи
Технологии 8 мин чтения

Завершение курса и элементов в Moodle: Completion API и свои условия

Как устроено отслеживание завершения в Moodle: completion_info, состояния элементов, свои правила завершения для модуля и критерии завершения курса.

Как устроено отслеживание завершения в Moodle: completion_info, состояния элементов, свои правила завершения для модуля и критерии завершения курса.

В интерфейсе завершение выглядит как галочка рядом с элементом курса и строка «Курс завершён» в отчёте. Под ним сразу три сущности: настройки завершения элемента, состояние пользователя по каждому элементу и критерии завершения курса, которые все это собирают. Разработчику плагина важно понимать границы: что читается и записывается через completion_info, что решает сам модуль, и что делает cron, а что происходит мгновенно.

Уровни: элемент и курс

УровеньГде настраиваетсяГде хранится состояниеКто считает
Элемент курса (activity)Настройки модуля, блок «Отслеживание выполнения»Таблица course_modules_completionСам модуль и ядро при действиях пользователя
Курс«Завершение курса» в настройках курсаТаблицы course_completions и course_completion_crit_complКритерии и агрегация; обновляется при событиях и по cron

Функциональность включается сайтом («Администрирование → Дополнительные возможности → Отслеживание выполнения») и курсом. Описание на стороне разработчика — в разделе Activity completion API.

Состояния элемента

Для каждого пользователя и элемента ядро хранит состояние:

  • COMPLETION_INCOMPLETE — не выполнено;
  • COMPLETION_COMPLETE — выполнено;
  • COMPLETION_COMPLETE_PASS — выполнено, проходной балл достигнут;
  • COMPLETION_COMPLETE_FAIL — выполнено, но балл не проходной.

Условия, по которым элемент считается выполненным, в штатной форме модуля бывают разными: ручная отметка студентом, просмотр, получение оценки, проходной балл и правила конкретного модуля (например, «отправить минимум столько сообщений» в форуме).

Чтение состояния

$course = get_course($courseid);
$modinfo = get_fast_modinfo($course, $userid);
$cm = $modinfo->get_cm($cmid);

$completion = new completion_info($course);

if ($completion->is_enabled($cm)) {
    $data = $completion->get_data($cm, false, $userid);
    if ($data->completionstate == COMPLETION_COMPLETE
            || $data->completionstate == COMPLETION_COMPLETE_PASS) {
        // Элемент выполнен.
    }
}

Проверка is_enabled() отсекает элементы, для которых отслеживание не включено. Для вывода на странице в виде привычной галочки пользуйтесь готовыми шаблонами, а не рисуйте свою: тема уже умеет показывать состояние. Для отчётов, где нужно знать завершение у многих пользователей сразу, есть методы, получающие данные пакетом: вызывать get_data() для каждой пары «пользователь × элемент» в цикле дорого.

Изменение состояния

Отметка выполнения выставляется методом update_state():

$completion->update_state($cm, COMPLETION_COMPLETE, $userid);

Но слово «выставляется» обманчиво. Для элемента с автоматическими правилами (оценка, просмотр, пользовательские условия) update_state() не принимает значение вслепую, а сам проверяет правила и приводит состояние в соответствие. Передавать COMPLETION_COMPLETE имеет смысл для ручной отметки или как «подсказку пересчитать». Типичная ошибка новичка — выставить завершение прямым INSERT в course_modules_completion: события не создаются, кэш не сбрасывается, критерии курса о нём не узнают, и в интерфейсе галочка появится не сразу или не появится вовсе.

Если пользователь выполнил действие (отправил ответ, посмотрел страницу), модуль сам вызывает пересчёт. Для просмотра есть отдельный метод set_module_viewed(), который вызывают в скрипте просмотра. Поэтому у собственных модулей важно не забывать про вызов в view.php: без него условие «Просмотреть» не сработает никогда.

Свои условия для модуля

В Moodle 4.0 появилась структура для пользовательских правил элемента: класс custom_completion. Её суть: модуль объявляет правила, а класс по запросу ядра сообщает, выполнено ли правило у пользователя. В supports модуля включается признак наличия правил завершения, в форме настроек появляются поля условий, а в каталоге classes/completion лежит класс.

namespace mod_example\completion;

use core_completion\activity_custom_completion;

class custom_completion extends activity_custom_completion {

    public function get_state(string $rule): int {
        $this->validate_rule($rule);
        $done = $this->is_rule_done($rule);   // ваша проверка по данным плагина
        return $done ? COMPLETION_COMPLETE : COMPLETION_INCOMPLETE;
    }

    public static function get_defined_custom_rules(): array {
        return ['completionreport'];
    }

    public function get_custom_rule_descriptions(): array {
        return ['completionreport' => get_string('completionreportdesc', 'mod_example')];
    }

    public function get_sort_order(): array {
        return ['completionview', 'completionreport'];
    }
}

Метод is_rule_done() здесь условный: это ваша функция, которая сверяется с таблицами модуля. Названия остальных методов фиксированы базовым классом, и список обязательных методов зависит от версии: сверьтесь с классом activity_custom_completion в вашем Moodle. Когда данные, от которых зависит правило, меняются (скажем, преподаватель принял отчёт), модуль должен вызвать пересчёт состояния для пользователя, иначе галочка не обновится до следующего действия.

Для плагинов не-модулей (local, block) собственных правил завершения нет. Пути обхода: вынести логику в простой модуль-элемент курса; использовать события для реакции; применить условия доступности (плагины availability), которые ограничивают доступ к элементам по произвольной логике.

Завершение курса

Критерии курса определены ядром: завершение элементов, дата, длительность записи, оценка за курс, ручное завершение, подтверждение преподавателем. Набор нельзя расширить стороннему плагину, и это следует учитывать при проектировании: нестандартные условия моделируются через элементы курса с собственными правилами. Агрегация критериев настраивается: «все» или «любой».

Часть критериев вычисляется не мгновенно. Условия по дате и длительности проверяются плановой задачей, а при завершении элементов в тот же момент ставится отметка, по которой система пересчитает курс при ближайшей возможности. Поэтому «курс не завершился сразу» не всегда ошибка, и сначала нужно проверить cron.

СимптомПричинаЧто проверить
Все элементы выполнены, курс не завершёнНе пересчитан статус, есть иной обязательный критерийСтраница «Завершение курса», задачи cron, отчёт о выполнении
Галочка не появляется после действияВ модуле нет вызова обновления состоянияview.php и обработчики действий модуля
Элемент не засчитан по оценкеНе достигнут проходной балл или оценка скрыта/ожидает пересчётаЖурнал оценок и настройки проходного балла
Завершение сбросилось у студентаПреподаватель сбросил попытку или изменил настройки элементаЖурнал событий, настройки «Заблокировать»
Нет события завершения курсаКурс завершён вручную или критерии не заданыНастройки курса и события по пользователю

Что хранится в настройках элемента

Условия завершения лежат прямо в записи элемента курса, в таблице course_modules. Поле completion показывает режим: отслеживание выключено, ручная отметка или автоматическое выполнение по условиям. Остальные поля уточняют условия: требование просмотра (completionview), номер оценки, по которой судят о выполнении (completiongradeitemnumber), проходной балл как отдельное условие (completionpassgrade) и ожидаемая дата завершения (completionexpected), которая нужна только для напоминаний и отображения в календаре. Пользовательские правила модуля хранятся в его собственных колонках. Для отчёта, который объясняет, почему элемент не засчитан, придётся прочитать все эти поля вместе с состоянием.

Что хотим узнатьОткуда читать
Включено ли отслеживание для элементаПоле completion в course_modules и метод is_enabled()
Состояние пользователя по элементуМетод get_data() или таблица course_modules_completion
Описание условий для показа студентуШаблоны и функции информации о модуле, а не самодельный текст
Завершил ли пользователь курсОбъект завершения курса и таблица course_completions

Сброс и повторное прохождение

Состояние завершения не вечно. Преподаватель может сбросить попытку теста, и состояние пересчитается. Функция «Сброс курса» в настройках удаляет данные пользователей и в том числе отметки завершения. При восстановлении курса из резервной копии с данными пользователей состояние тоже переносится. Это важно для зачётных книжек и отчётов: завершение, на которое вы опираетесь как на факт, может измениться. Поэтому события завершения, как и итоговые оценки, стоит фиксировать в своей таблице на момент наступления, если плагин создаёт документ (сертификат, ведомость), который нельзя менять задним числом.

Ещё одна тонкость: приостановленное или неактивное зачисление. Отчёты по завершению обычно строят по активным участникам, и студент, отчисленный, а затем восстановленный, может появиться в статистике не сразу. При проектировании отчёта заранее решите, кого считать участником курса на отчётную дату, и сделайте это явным условием запроса.

Классы и методы завершения: справка

Метод или классДля чего
new completion_info($course)Точка входа для работы с завершением курса
is_enabled($cm)Включено ли отслеживание для элемента
get_data($cm, $wholecourse, $userid)Состояние завершения элемента у пользователя
update_state($cm, $state, $userid)Пересчитать и записать состояние
set_module_viewed($cm, $userid)Отметить просмотр элемента
is_course_complete($userid)Проверить завершение курса пользователем
\core_completion\progressРасчёт процента выполнения для отображения
\core_completion\activity_custom_completionБазовый класс пользовательских правил модуля

Типичные ошибки разработчика

Первая ошибка уже описана: запись в таблицы напрямую. Вторая: в скрипте просмотра модуля нет вызова отметки просмотра, и условие «Просмотреть» не выполняется никогда. Третья: пользовательское правило проверяют по данным, которые ещё не сохранены на момент вызова пересчёта, и состояние отстаёт на одно действие. Четвёртая: отчёт считает «завершено» только по значению COMPLETION_COMPLETE и теряет вариант с проходным баллом. Для проверки полезно завести тестового пользователя и пройти элемент всеми способами, которые допускают настройки: вручную, по просмотру, по оценке, по проходному баллу.

Реакция на завершение

Для действий «после завершения» (сертификат, письмо, отметка в зачётной книжке) подписываются на события: на уровне элемента это \core\event\course_module_completion_updated, на уровне курса — \core\event\course_completed. Наблюдателю достаточно поставить фоновую задачу, а основную работу сделать вне запроса. На той же связке строятся выдача сертификатов и обработка слушателей по окончании обучения. Если нужно собрать такую цепочку под вашу СДО, пишите через страницу разработки плагинов Moodle.

Завершение влияет и на оценки: в курсе с обязательными условиями проходной балл часто определяет, будет ли элемент засчитан. Как журнал хранит такие значения, описано в статье про Grade API.

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

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