MDL-36135 Give the grading evaluation methods control over their sett…

…ings forms

From now on, the evaluator's method get_settings_form() should return a
subclass of workshop_evaluation_settings_form. The evaluation subplugins
are expected to use the define_sub() method to add their own fields into
the base form, although they can override the main define() method, too.

The former interface workshop_evaluation has been refactored into a
superclass with abstract methods which seems to be more robust.

Oh, by the way, I'm in Perth - yay!

AMOS BEGIN
 MOV [settings,workshopeval_best],[evaluationsettings,mod_workshop]
AMOS END

mod/workshop/eval/best/lang/en/workshopeval_best.php

@@ -33,4 +33,3 @@
 $string['comparisonlevel9'] = 'very lax';
 $string['configcomparison'] = 'Default value of the factor that influence the grading evaluation.';
 $string['pluginname'] = 'Comparison with the best assessment';
-$string['settings'] = 'Grading evaluation settings';

mod/workshop/eval/best/lib.php

@@ -33,7 +33,7 @@
 /**
  * Defines the computation login of the grading evaluation subplugin
  */
-class workshop_best_evaluation implements workshop_evaluation {
+class workshop_best_evaluation extends workshop_evaluation {
 
     /** @var workshop the parent workshop instance */
     protected $workshop;
@@ -67,7 +67,7 @@ public function __construct(workshop $workshop) {
     public function update_grading_grades(stdclass $settings, $restrict=null) {
         global $DB;
 
-        // remember the recently used settings for this workshop
+        // Remember the recently used settings for this workshop.
         if (empty($this->settings)) {
             $record = new stdclass();
             $record->workshopid = $this->workshop->id;
@@ -78,7 +78,7 @@ public function update_grading_grades(stdclass $settings, $restrict=null) {
                     array('workshopid' => $this->workshop->id));
         }
 
-        // get the grading strategy instance
+        // Get the grading strategy instance.
         $grader = $this->workshop->grading_strategy_instance();
 
         // get the information about the assessment dimensions
@@ -109,14 +109,11 @@ public function update_grading_grades(stdclass $settings, $restrict=null) {
     }
 
     /**
-     * TODO: short description.
+     * Returns an instance of the form to provide evaluation settings.
      *
-     * @return TODO
+     * @return workshop_best_evaluation_settings_form
      */
     public function get_settings_form(moodle_url $actionurl=null) {
-        global $CFG;    // needed because the included files use it
-        global $DB;
-        require_once(dirname(__FILE__) . '/settings_form.php');
 
         $customdata['workshop'] = $this->workshop;
         $customdata['current'] = $this->settings;
@@ -403,3 +400,30 @@ protected function assessments_distance(stdclass $assessment, stdclass $referent
         }
     }
 }
+
+
+/**
+ * Represents the settings form for this plugin.
+ */
+class workshop_best_evaluation_settings_form extends workshop_evaluation_settings_form {
+
+    /**
+     * Defines specific fields for this evaluation method.
+     */
+    protected function definition_sub() {
+        $mform = $this->_form;
+
+        $plugindefaults = get_config('workshopeval_best');
+        $current = $this->_customdata['current'];
+
+        $options = array();
+        for ($i = 9; $i >= 1; $i = $i-2) {
+            $options[$i] = get_string('comparisonlevel' . $i, 'workshopeval_best');
+        }
+        $mform->addElement('select', 'comparison', get_string('comparison', 'workshopeval_best'), $options);
+        $mform->addHelpButton('comparison', 'comparison', 'workshopeval_best');
+        $mform->setDefault('comparison', $plugindefaults->comparison);
+
+        $this->set_data($current);
+    }
+}

mod/workshop/eval/lib.php

@@ -26,12 +26,37 @@
 
 defined('MOODLE_INTERNAL') || die();
 
+require_once($CFG->dirroot . '/lib/formslib.php');
+
 /**
- * Defines all methods that grading evaluation subplugins has to implement
- *
- * @todo the final interface is not decided yet as we have only one implementation so far
+ * Base class for all grading evaluation subplugins.
  */
-interface workshop_evaluation {
+abstract class workshop_evaluation {
+
+    /**
+     * Calculates grades for assessment and updates 'gradinggrade' fields in 'workshop_assessments' table
+     *
+     * @param stdClass $settings settings for this round of evaluation
+     * @param null|int|array $restrict if null, update all reviewers, otherwise update just grades for the given reviewers(s)
+     */
+    abstract public function update_grading_grades(stdClass $settings, $restrict=null);
+
+    /**
+     * Returns an instance of the form to provide evaluation settings.
+      *
+     * This is called by view.php (to display) and aggregate.php (to process and dispatch).
+     * It returns the basic form with just the submit button by default. Evaluators may
+     * extend or overwrite the default form to include some custom settings.
+     *
+     * @return workshop_evaluation_settings_form
+     */
+    public function get_settings_form(moodle_url $actionurl=null) {
+
+        $customdata = array('workshop' => $this->workshop);
+        $attributes = array('class' => 'evalsettingsform');
+
+        return new workshop_evaluation_settings_form($actionurl, $customdata, 'post', '', $attributes);
+    }
 
     /**
      * Delete all data related to a given workshop module instance
@@ -41,5 +66,35 @@ interface workshop_evaluation {
      * @param int $workshopid id of the workshop module instance being deleted
      * @return void
      */
-    public static function delete_instance($workshopid);
+    public static function delete_instance($workshopid) {
+
+    }
+}
+
+
+/**
+ * Base form to hold eventual evaluation settings.
+ */
+class workshop_evaluation_settings_form extends moodleform {
+
+    /**
+     * Defines the common form fields.
+     */
+    public function definition() {
+        $mform = $this->_form;
+
+        $workshop = $this->_customdata['workshop'];
+
+        $mform->addElement('header', 'general', get_string('evaluationsettings', 'mod_workshop'));
+
+        $this->definition_sub();
+
+        $mform->addElement('submit', 'submit', get_string('aggregategrades', 'workshop'));
+    }
+
+    /**
+     * Defines the subplugin specific fields.
+     */
+    protected function definition_sub() {
+    }
 }

mod/workshop/lang/en/workshop.php

@@ -101,6 +101,7 @@
 $string['evaluation'] = 'Grading evaluation';
 $string['evaluationmethod'] = 'Grading evaluation method';
 $string['evaluationmethod_help'] = 'The grading evaluation method determines how the grade for assessment is calculated. You can let it re-calculate grades repeatedly with different settings unless you are happy with the result.';
+$string['evaluationsettings'] = 'Grading evaluation settings';
 $string['example'] = 'Example submission';
 $string['exampleadd'] = 'Add example submission';
 $string['exampleassess'] = 'Assess example submission';

mod/workshop/locallib.php

@@ -1272,16 +1272,27 @@ public function grading_evaluation_instance() {
         global $CFG;    // because we require other libs here
 
         if (is_null($this->evaluationinstance)) {
+            if (empty($this->evaluation)) {
+                $this->evaluation = 'best';
+            }
             $evaluationlib = dirname(__FILE__) . '/eval/' . $this->evaluation . '/lib.php';
             if (is_readable($evaluationlib)) {
                 require_once($evaluationlib);
             } else {
-                throw new coding_exception('the grading evaluation subplugin must contain library ' . $evaluationlib);
+                // Fall back in case the subplugin is not available.
+                $this->evaluation = 'best';
+                $evaluationlib = dirname(__FILE__) . '/eval/' . $this->evaluation . '/lib.php';
+                if (is_readable($evaluationlib)) {
+                    require_once($evaluationlib);
+                } else {
+                    // Fall back in case the subplugin is not available any more.
+                    throw new coding_exception('Missing default grading evaluation library ' . $evaluationlib);
+                }
             }
             $classname = 'workshop_' . $this->evaluation . '_evaluation';
             $this->evaluationinstance = new $classname($this);
-            if (!in_array('workshop_evaluation', class_implements($this->evaluationinstance))) {
-                throw new coding_exception($classname . ' does not implement workshop_evaluation interface');
+            if (!in_array('workshop_evaluation', class_parents($this->evaluationinstance))) {
+                throw new coding_exception($classname . ' does not extend workshop_evaluation class');
             }
         }
         return $this->evaluationinstance;