From beb0dd74f226cbacc123dc400274a3d32b84ed37 Mon Sep 17 00:00:00 2001 From: Jun Pataleta Date: Tue, 16 Feb 2021 10:04:41 +0800 Subject: [PATCH] MDL-70815 core_completion: Activity custom completion details base class * Base class for defining an activity module's custom completion details --- completion/classes/activity_custom_completion.php | 175 ++++++++++++++++++++++ lib/upgrade.txt | 9 ++ 2 files changed, 184 insertions(+) create mode 100644 completion/classes/activity_custom_completion.php diff --git a/completion/classes/activity_custom_completion.php b/completion/classes/activity_custom_completion.php new file mode 100644 index 00000000000..7c7806a5f7c --- /dev/null +++ b/completion/classes/activity_custom_completion.php @@ -0,0 +1,175 @@ +. + +declare(strict_types = 1); + +namespace core_completion; + +use cm_info; +use coding_exception; +use moodle_exception; + +/** + * Base class for defining an activity module's custom completion rules. + * + * Class for defining an activity module's custom completion rules and fetching the completion statuses + * of the custom completion rules for a given module instance and a user. + * + * @package core_completion + * @copyright 2021 Jun Pataleta + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ +abstract class activity_custom_completion { + + /** @var cm_info The course module information object. */ + protected $cm; + + /** @var int The user's ID. */ + protected $userid; + + /** + * activity_custom_completion constructor. + * + * @param cm_info $cm + * @param int $userid + */ + public function __construct(cm_info $cm, int $userid) { + $this->cm = $cm; + $this->userid = $userid; + } + + /** + * Validates that the custom rule is defined by this plugin and is enabled for this activity instance. + * + * @param string $rule The custom completion rule. + */ + public function validate_rule(string $rule): void { + // Check that this custom completion rule is defined. + if (!$this->is_defined($rule)) { + throw new coding_exception("Undefined custom completion rule '$rule'"); + } + + // Check that this custom rule is included in the course module's custom completion rules. + if (!$this->is_available($rule)) { + throw new moodle_exception("Custom completion rule '$rule' is not used by this activity."); + } + } + + /** + * Whether this module defines this custom rule. + * + * @param string $rule The custom completion rule. + * @return bool + */ + public function is_defined(string $rule): bool { + return in_array($rule, static::get_defined_custom_rules()); + } + + /** + * Checks whether the custom completion rule is being used by the activity module instance. + * + * @param string $rule The custom completion rule. + * @return bool + */ + public function is_available(string $rule): bool { + return in_array($rule, $this->get_available_custom_rules()); + } + + /** + * Fetches the list of custom completion rules that are being used by this activity module instance. + * + * @return array + */ + public function get_available_custom_rules(): array { + $rules = static::get_defined_custom_rules(); + $availablerules = []; + foreach ($rules as $rule) { + $customrule = $this->cm->customdata['customcompletionrules'][$rule] ?? false; + if (!empty($customrule)) { + $availablerules[] = $rule; + } + } + return $availablerules; + } + + /** + * Fetches the overall completion status of this activity instance for a user based on its available custom completion rules. + * + * @return int The completion state (e.g. COMPLETION_COMPLETE, COMPLETION_INCOMPLETE). + */ + public function get_overall_completion_state(): int { + foreach ($this->get_available_custom_rules() as $rule) { + $state = $this->get_state($rule); + // Return early if one of the custom completion rules is not yet complete. + if ($state == COMPLETION_INCOMPLETE) { + return $state; + } + } + // If this was reached, then all custom rules have been marked complete. + return COMPLETION_COMPLETE; + } + + /** + * Fetches the description for a given custom completion rule. + * + * @param string $rule The custom completion rule. + * @return string + */ + public function get_custom_rule_description(string $rule): string { + $descriptions = $this->get_custom_rule_descriptions(); + if (!isset($descriptions[$rule])) { + // Lang string not found for this custom completion rule. Just return it. + return $rule; + } + return $descriptions[$rule]; + } + + /** + * Fetches the module's custom completion class implementation if it's available. + * + * @param string $modname The activity module name. Usually from cm_info::modname. + * @return string|null + */ + public static function get_cm_completion_class(string $modname): ?string { + $cmcompletionclass = "mod_{$modname}\\completion\\custom_completion"; + if (class_exists($cmcompletionclass) && is_subclass_of($cmcompletionclass, self::class)) { + return $cmcompletionclass; + } + return null; + } + + /** + * Fetches the completion state for a given completion rule. + * + * @param string $rule The completion rule. + * @return int The completion state. + */ + public abstract function get_state(string $rule): int; + + /** + * Fetch the list of custom completion rules that this module defines. + * + * @return array + */ + public abstract static function get_defined_custom_rules(): array; + + /** + * Returns an associative array of the descriptions of custom completion rules. + * + * @return array + */ + public abstract function get_custom_rule_descriptions(): array; +} diff --git a/lib/upgrade.txt b/lib/upgrade.txt index 53ca66805d3..384419f410e 100644 --- a/lib/upgrade.txt +++ b/lib/upgrade.txt @@ -33,6 +33,15 @@ information provided here is intended especially for developers. * New DML driver method `$DB->sql_group_concat` for performing group concatenation of a field within a SQL query * Added new class, AMD modules and WS that allow displaying forms in modal popups or load and submit in AJAX requests. See https://docs.moodle.org/dev/Modal_and_AJAX_forms for more details. +* New base class for defining an activity's custom completion requirements: \core_completion\activity_custom_completion. + Activity module plugins that define custom completion conditions should implement a mod_[modname]\completion\custom_completion + subclass and the following methods: + - get_state(): Provides the completion state for a given custom completion rule. + - get_defined_custom_rules(): Returns an array of the activity module's custom completion rules. + e.g. ['completionsubmit'] + - get_custom_rule_descriptions(): Returns an associative array with values containing the user-facing textual description + of the custom completion rules (which serve as the keys to these values). + e.g. ['completionsubmit' => 'Must submit'] === 3.10 === * PHPUnit has been upgraded to 8.5. That comes with a few changes: -- 2.11.4.GIT