MDL-80945 add access rule override base

docs/apis/plugintypes/quizaccess/_examples/access_override_rule_base.md

@@ -0,0 +1,4 @@
+<!-- markdownlint-disable first-line-heading -->
+Most quiz settings can be overridden on a per user and/or group level and you can extend this ability to your rule as well. To make your rule overridable, you must extend the `access_override_rule_base` class in your rule class definition.
+
+Please refer to the inline phpdocs of the [mod_quiz::access_override_rule_base](https://github.com/moodle/moodle/blob/main/mod/quiz/classes/local/access_override_rule_base.php) class for detailed descriptions of the functions and meaning.

docs/apis/plugintypes/quizaccess/_examples/rule_overridable.php → docs/apis/plugintypes/quizaccess/_examples/access_override_rule_base.php

@@ -1,15 +1,10 @@
 use mod_quiz\form\edit_override_form;
-use mod_quiz\local\access_rule_base;
-use mod_quiz\local\rule_overridable;
+use mod_quiz\local\access_override_rule_base;
 use MoodleQuickForm;
 
-class quizaccess_pluginname extends access_rule_base implements rule_overridable {
+class quizaccess_pluginname extends access_override_rule_base  {
 
-    /**
-     * All of the below rule_overridable interface functions will need to be implemented.
-     */
-
-    public static function add_override_form_fields(edit_override_form $quizform, MoodleQuickForm $mform): void {
+    public static function add_form_fields(edit_override_form $quizform, MoodleQuickForm $mform): void {
         // Use the $mform to add the rule override fields...
         $mform->addElement(
             'select',
@@ -26,25 +21,13 @@ public static function add_override_form_fields(edit_override_form $quizform, Mo
         );
     }
 
-    public static function get_override_form_section_header(): array {
-        // Return the label and content of the section header in an array.
-        return ['name' => 'pluginname', 'title' => get_string('pluginname', 'quizaccess_pluginname')];
-    }
-
-    public static function get_override_form_section_expand(edit_override_form $quizform): bool {
-        // Determine if rule section in override form should load expanded.
-        // Should typically return true if the quiz has existing rule settings.
-        global $DB;
-        return $DB->record_exists('quizaccess_pluginname', ['quiz' => $quizform->get_quiz()->id]);
-    }
-
-    public static function validate_override_form_fields(array $errors,
+    public static function validate_form_fields(array $errors,
             array $data, array $files, edit_override_form $quizform): array {
         // Check and push to $errors array...
         return $errors;
     }
 
-    public static function save_override_settings(array $override): void {
+    public static function save_settings(array $override): void {
         // Save $override data to plugin settings table...
         global $DB;
 
@@ -62,25 +45,25 @@ public static function save_override_settings(array $override): void {
         }
     }
 
-    public static function delete_override_settings($quizid, $overrides): void {
+    public static function delete_settings($quizid, $overrides): void {
         // Remove $overrides from $quiz.
         global $DB;
         $ids = array_column($overrides, 'id');
         list($insql, $inparams) = $DB->get_in_or_equal($ids);
         $DB->delete_records_select('quizaccess_pluginname_overrides', "id $insql", $inparams);
     }
 
-    public static function get_override_setting_keys(): array {
+    public static function get_settings(): array {
         // Return string array of all override form setting keys.
         return ['plgnm_setting1', 'plgnm_setting2'];
     }
 
-    public static function get_override_required_setting_keys(): array {
+    public static function get_required_settings(): array {
         // Return string array of override form setting keys that are required.
         return ['plgnm_setting1'];
     }
 
-    public static function get_override_settings_sql($overridetablename): array {
+    public static function get_settings_sql($overridetablename): array {
         // Return an array of selects, joins and parameters to be used to query relevant rule overrides...
         return [
             "plgnm.setting1 plgnm_setting1, plgnm.setting2 plgnm_setting2",
@@ -89,12 +72,20 @@ public static function get_override_settings_sql($overridetablename): array {
         ];
     }
 
-    public static function add_override_table_fields($override, $fields, $values, $context): array {
+    public static function add_table_fields($override, $fields, $values, $context): array {
         // Extend the override table view by adding fields and values that display the rule's overrides.
         if (!empty($override->plgnm_setting1)) {
             $fields[] = get_string('pluginname', 'quizaccess_pluginname');
             $values[] = "{$override->plgnm_setting1}, {$override->plgnm_setting2}";
         }
         return [$fields, $values];
     }
+
+    public static function clean_form_data(array $formdata): array {
+        // Clean and normalise submitted values for the rule.
+        if (isset($formdata['plugin_enabled']) && $formdata['plugin_enabled'] === '0') {
+            $formdata['plugin_enabled'] = null;
+        }
+        return $formdata;
+    }
 }

docs/apis/plugintypes/quizaccess/index.md

@@ -67,8 +67,8 @@ import RuleDescription from './_examples/rule.md';
     description={RuleDescription}
 />
 
-import RuleOverridableFile from '!!raw-loader!./_examples/rule_overridable.php';
-import RuleOverridableDescription from './_examples/rule_overridable.md';
+import RuleOverridableFile from '!!raw-loader!./_examples/access_override_rule_base.php';
+import RuleOverridableDescription from './_examples/access_override_rule_base.md';
 
 <ComponentFileSummary
     filepath="/rule.php"
@@ -81,6 +81,6 @@ import RuleOverridableDescription from './_examples/rule_overridable.md';
 
 :::info
 
-Implementing `rule_overridable` is not required but can enhance the usability of the rule.
+Basing your rule on `access_override_rule_base` is not required but can enhance the usability of the rule.
 
 :::