MDL-30453 New renderable classes for assessments of example submissions

The patch introduces two new classes for rendering assessments of
example submission - both the training one and the reference one.
Together with the cooking functions for obtaining instances of these
classes.

mod/workshop/locallib.php

@@ -713,6 +713,7 @@ class workshop {
      * showauthor - should the author user info be available for the renderer
      * showreviewer - should the reviewer user info be available for the renderer
      * showform - show the assessment form if it is available
+     * showweight - should the assessment weight be available for the renderer
      *
      * @param stdClass $record as returned by eg {@link self::get_assessment_by_id()}
      * @param workshop_assessment_form|null $form as returned by {@link workshop_strategy::get_assessment_form()}
@@ -744,6 +745,77 @@ class workshop {
         return $assessment;
     }
 
+    /**
+     * Prepares renderable example submission's assessment component
+     *
+     * The $options array supports the following keys:
+     * showauthor - should the author user info be available for the renderer
+     * showreviewer - should the reviewer user info be available for the renderer
+     * showform - show the assessment form if it is available
+     *
+     * @param stdClass $record as returned by eg {@link self::get_assessment_by_id()}
+     * @param workshop_assessment_form|null $form as returned by {@link workshop_strategy::get_assessment_form()}
+     * @param array $options
+     * @return workshop_example_assessment
+     */
+    public function prepare_example_assessment(stdClass $record, $form = null, array $options = array()) {
+
+        $assessment             = new workshop_example_assessment($record, $options);
+        $assessment->url        = $this->exassess_url($record->id);
+        $assessment->maxgrade   = $this->real_grade(100);
+
+        if (!empty($options['showform']) and !($form instanceof workshop_assessment_form)) {
+            debugging('Not a valid instance of workshop_assessment_form supplied', DEBUG_DEVELOPER);
+        }
+
+        if (!empty($options['showform']) and ($form instanceof workshop_assessment_form)) {
+            $assessment->form = $form;
+        }
+
+        if (!is_null($record->grade)) {
+            $assessment->realgrade = $this->real_grade($record->grade);
+        }
+
+        $assessment->weight = null;
+
+        return $assessment;
+    }
+
+    /**
+     * Prepares renderable example submission's reference assessment component
+     *
+     * The $options array supports the following keys:
+     * showauthor - should the author user info be available for the renderer
+     * showreviewer - should the reviewer user info be available for the renderer
+     * showform - show the assessment form if it is available
+     *
+     * @param stdClass $record as returned by eg {@link self::get_assessment_by_id()}
+     * @param workshop_assessment_form|null $form as returned by {@link workshop_strategy::get_assessment_form()}
+     * @param array $options
+     * @return workshop_example_reference_assessment
+     */
+    public function prepare_example_reference_assessment(stdClass $record, $form = null, array $options = array()) {
+
+        $assessment             = new workshop_example_reference_assessment($record, $options);
+        $assessment->maxgrade   = $this->real_grade(100);
+
+        if (!empty($options['showform']) and !($form instanceof workshop_assessment_form)) {
+            debugging('Not a valid instance of workshop_assessment_form supplied', DEBUG_DEVELOPER);
+        }
+
+        if (!empty($options['showform']) and ($form instanceof workshop_assessment_form)) {
+            $assessment->form = $form;
+        }
+
+        if (!is_null($record->grade)) {
+            $assessment->realgrade = $this->real_grade($record->grade);
+        }
+
+        $assessment->weight = null;
+
+        return $assessment;
+    }
+
     /**
      * Removes the submission and all relevant data
      *
@@ -2713,6 +2785,8 @@ abstract class workshop_assessment_base {
      */
     public function __construct(stdClass $record, array $options = array()) {
 
+        $this->validate_raw_record($record);
+
         foreach ($this->fields as $field) {
             if (!property_exists($record, $field)) {
                 throw new coding_exception('Assessment record must provide public property ' . $field);
@@ -2748,6 +2822,16 @@ abstract class workshop_assessment_base {
 
         $this->actions[] = $action;
     }
+
+    /**
+     * Makes sure that we can cook the renderable component from the passed raw database record
+     *
+     * @param stdClass $assessment full assessment record
+     * @throws coding_exception if the caller passed unexpected data
+     */
+    protected function validate_raw_record(stdClass $record) {
+        // nothing to do here
+    }
 }
 
 
@@ -2785,6 +2869,41 @@ class workshop_assessment extends workshop_assessment_base implements renderable
         'timemodified', 'grade', 'gradinggrade', 'gradinggradeover');
 }
 
+
+/**
+ * Represents a renderable training assessment of an example submission
+ */
+class workshop_example_assessment extends workshop_assessment implements renderable {
+
+    /**
+     * @see parent::validate_raw_record()
+     */
+    protected function validate_raw_record(stdClass $record) {
+        if ($record->weight != 0) {
+            throw new coding_exception('Invalid weight of example submission assessment');
+        }
+        parent::validate_raw_record($record);
+    }
+}
+
+
+/**
+ * Represents a renderable reference assessment of an example submission
+ */
+class workshop_example_reference_assessment extends workshop_assessment implements renderable {
+
+    /**
+     * @see parent::validate_raw_record()
+     */
+    protected function validate_raw_record(stdClass $record) {
+        if ($record->weight != 1) {
+            throw new coding_exception('Invalid weight of the reference example submission assessment');
+        }
+        parent::validate_raw_record($record);
+    }
+}
+
+
 /**
  * Renderable message to be displayed to the user
  *

mod/workshop/simpletest/testlocallib.php

@@ -374,4 +374,54 @@ class workshop_internal_api_test extends UnitTestCase {
         // verify
         $this->assertEqual($lcm, 15);
     }
+
+    public function test_prepare_example_assessment() {
+        // fixture setup
+        $fakerawrecord = (object)array(
+            'id'                => 42,
+            'submissionid'      => 56,
+            'weight'            => 0,
+            'timecreated'       => time() - 10,
+            'timemodified'      => time() - 5,
+            'grade'             => null,
+            'gradinggrade'      => null,
+            'gradinggradeover'  => null,
+        );
+        // excersise SUT
+        $a = $this->workshop->prepare_example_assessment($fakerawrecord);
+        // verify
+        $this->assertTrue($a instanceof workshop_example_assessment);
+        $this->assertTrue($a->url instanceof moodle_url);
+
+        // modify setup
+        $fakerawrecord->weight = 1;
+        $this->expectException('coding_exception');
+        // excersise SUT
+        $a = $this->workshop->prepare_example_assessment($fakerawrecord);
+    }
+
+    public function test_prepare_example_reference_assessment() {
+        global $USER;
+        // fixture setup
+        $fakerawrecord = (object)array(
+            'id'                => 38,
+            'submissionid'      => 56,
+            'weight'            => 1,
+            'timecreated'       => time() - 100,
+            'timemodified'      => time() - 50,
+            'grade'             => 0.75000,
+            'gradinggrade'      => 1.00000,
+            'gradinggradeover'  => null,
+        );
+        // excersise SUT
+        $a = $this->workshop->prepare_example_reference_assessment($fakerawrecord);
+        // verify
+        $this->assertTrue($a instanceof workshop_example_reference_assessment);
+
+        // modify setup
+        $fakerawrecord->weight = 0;
+        $this->expectException('coding_exception');
+        // excersise SUT
+        $a = $this->workshop->prepare_example_reference_assessment($fakerawrecord);
+    }
 }