MDL-32188 quiz/question: behaviours can add to the review summary.

At the top of the quiz reivew page, there is a table that summarises
infomration about the quiz attempt as a whole. For some question
behaviours, we would like to be able to add additional information to
that summary.

This commit introduces a generic method for the behaviour to provide
summary information about an entire question usage.

mod/quiz/attemptlib.php

@@ -745,6 +745,28 @@ public function is_review_allowed() {
                 array_intersect(array_keys($teachersgroups), array_keys($studentsgroups));
     }
 
+    /**
+     * Get extra summary information about this attempt.
+     *
+     * Some behaviours may be able to provide interesting summary information
+     * about the attempt as a whole, and this method provides access to that data.
+     * To see how this works, try setting a quiz to one of the CBM behaviours,
+     * and then look at the extra information displayed at the top of the quiz
+     * review page once you have sumitted an attempt.
+     *
+     * In the return value, the array keys are identifiers of the form
+     * qbehaviour_behaviourname_meaningfullkey. For qbehaviour_deferredcbm_highsummary.
+     * The values are arrays with two items, title and content. Each of these
+     * will be either a string, or a renderable.
+     *
+     * @param question_display_options $options display options. Indicates what types
+     *      of information should, or should not, be returned.
+     * @return array as described above.
+     */
+    public function get_additional_summary_data(question_display_options $options) {
+        return $this->quba->get_summary_information($options);
+    }
+
     /**
      * Get the overall feedback corresponding to a particular mark.
      * @param $grade a particular grade.

mod/quiz/lang/en/quiz.php

@@ -527,7 +527,7 @@
 $string['orderingquiz'] = 'Order and paging';
 $string['orderingquizx'] = 'Order and paging: {$a}';
 $string['outcomesadvanced'] = 'Outcomes are advanced settings';
-$string['outof'] = '{$a->grade} out of a maximum of {$a->maxgrade}';
+$string['outof'] = '{$a->grade} out of {$a->maxgrade}';
 $string['outofpercent'] = '{$a->grade} out of a maximum of {$a->maxgrade} ({$a->percent}%)';
 $string['outofshort'] = '{$a->grade}/{$a->maxgrade}';
 $string['overallfeedback'] = 'Overall feedback';

mod/quiz/review.php

@@ -228,6 +228,9 @@
     }
 }
 
+// Any additional summary data from the behaviour.
+$summarydata = array_merge($summarydata, $attemptobj->get_additional_summary_data($options));
+
 // Feedback if there is any, and the user is allowed to see it now.
 $feedback = $attemptobj->get_overall_feedback($grade);
 if ($options->overallfeedback && $feedback) {

question/behaviour/behaviourtypebase.php

@@ -69,6 +69,31 @@ public function get_unused_display_options() {
     public function adjust_random_guess_score($fraction) {
         return $fraction;
     }
+
+    /**
+     * Get summary information about a queston usage.
+     *
+     * Behaviours are not obliged to do anything here, but this is an opportunity
+     * to provide additional information that can be displayed in places like
+     * at the top of the quiz review page.
+     *
+     * In the return value, the array keys should be identifiers of the form
+     * qbehaviour_behaviourname_meaningfullkey. For qbehaviour_deferredcbm_highsummary.
+     * The values should be arrays with two items, title and content. Each of these
+     * should be either a string, or a renderable.
+     *
+     * To understand how to implement this method, look at the CBM behaviours,
+     * and their unit tests.
+     *
+     * @param question_usage_by_activity $quba the usage to provide summary data for.
+     * @param question_display_options $options display options. Indicates what types
+     *      of information should, or should not, be returned.
+     * @return array as described above.
+     */
+    public function summarise_usage(question_usage_by_activity $quba,
+            question_display_options $options) {
+        return array();
+    }
 }
 
 

question/engine/questionusage.php

@@ -326,6 +326,29 @@ public function get_total_mark() {
         return $mark;
     }
 
+    /**
+     * Get summary information about this usage.
+     *
+     * Some behaviours may be able to provide interesting summary information
+     * about the attempt as a whole, and this method provides access to that data.
+     * To see how this works, try setting a quiz to one of the CBM behaviours,
+     * and then look at the extra information displayed at the top of the quiz
+     * review page once you have sumitted an attempt.
+     *
+     * In the return value, the array keys are identifiers of the form
+     * qbehaviour_behaviourname_meaningfullkey. For qbehaviour_deferredcbm_highsummary.
+     * The values are arrays with two items, title and content. Each of these
+     * will be either a string, or a renderable.
+     *
+     * @param question_display_options $options display options. Indicates what types
+     *      of information should, or should not, be returned.
+     * @return array as described above.
+     */
+    public function get_summary_information(question_display_options $options) {
+        return question_engine::get_behaviour_type($this->preferredbehaviour)
+                ->summarise_usage($this, $options);
+    }
+
     /**
      * @return string a simple textual summary of the question that was asked.
      */