MDL-53034 mod_quiz: New WS mod_quiz_get_quiz_feedback_for_grade

mod/quiz/classes/external.php

@@ -1555,4 +1555,77 @@ class mod_quiz_external extends external_api {
         );
     }
 
+    /**
+     * Describes the parameters for view_quiz.
+     *
+     * @return external_external_function_parameters
+     * @since Moodle 3.1
+     */
+    public static function get_quiz_feedback_for_grade_parameters() {
+        return new external_function_parameters (
+            array(
+                'quizid' => new external_value(PARAM_INT, 'quiz instance id'),
+                'grade' => new external_value(PARAM_FLOAT, 'the grade to check'),
+            )
+        );
+    }
+
+    /**
+     * Get the feedback text that should be show to a student who got the given grade in the given quiz.
+     *
+     * @param int $quizid quiz instance id
+     * @param float $grade the grade to check
+     * @return array of warnings and status result
+     * @since Moodle 3.1
+     * @throws moodle_exception
+     */
+    public static function get_quiz_feedback_for_grade($quizid, $grade) {
+        global $DB;
+
+        $params = array(
+            'quizid' => $quizid,
+            'grade' => $grade,
+        );
+        $params = self::validate_parameters(self::get_quiz_feedback_for_grade_parameters(), $params);
+        $warnings = array();
+
+        // Request and permission validation.
+        $quiz = $DB->get_record('quiz', array('id' => $params['quizid']), '*', MUST_EXIST);
+        list($course, $cm) = get_course_and_cm_from_instance($quiz, 'quiz');
+
+        $context = context_module::instance($cm->id);
+        self::validate_context($context);
+
+        $result = array();
+        $result['feedbacktext'] = '';
+        $result['feedbacktextformat'] = FORMAT_MOODLE;
+
+        $feedback = quiz_feedback_record_for_grade($params['grade'], $quiz);
+        if (!empty($feedback->feedbacktext)) {
+            list($text, $format) = external_format_text($feedback->feedbacktext, $feedback->feedbacktextformat, $context->id,
+                                                        'mod_quiz', 'feedback', $feedback->id);
+            $result['feedbacktext'] = $text;
+            $result['feedbacktextformat'] = $format;
+        }
+
+        $result['warnings'] = $warnings;
+        return $result;
+    }
+
+    /**
+     * Describes the get_quiz_feedback_for_grade return value.
+     *
+     * @return external_single_structure
+     * @since Moodle 3.1
+     */
+    public static function get_quiz_feedback_for_grade_returns() {
+        return new external_single_structure(
+            array(
+                'feedbacktext' => new external_value(PARAM_RAW, 'the comment that corresponds to this grade (empty for none)'),
+                'feedbacktextformat' => new external_format_value('feedbacktext', VALUE_OPTIONAL),
+                'warnings' => new external_warnings(),
+            )
+        );
+    }
+
 }

mod/quiz/db/services.php

@@ -155,4 +155,13 @@ $functions = array(
         'capabilities'  => 'mod/quiz:reviewmyattempts',
         'services'      => array(MOODLE_OFFICIAL_MOBILE_SERVICE)
     ),
+
+    'mod_quiz_get_quiz_feedback_for_grade' => array(
+        'classname'     => 'mod_quiz_external',
+        'methodname'    => 'get_quiz_feedback_for_grade',
+        'description'   => 'Get the feedback text that should be show to a student who got the given grade in the given quiz.',
+        'type'          => 'read',
+        'capabilities'  => 'mod/quiz:view',
+        'services'      => array(MOODLE_OFFICIAL_MOBILE_SERVICE)
+    ),
 );

mod/quiz/locallib.php

@@ -544,6 +544,27 @@ function quiz_rescale_grade($rawgrade, $quiz, $format = true) {
     return $grade;
 }
 
+/**
+ * Get the feedback object for this grade on this quiz.
+ *
+ * @param float $grade a grade on this quiz.
+ * @param object $quiz the quiz settings.
+ * @return false|stdClass the record object or false if there is not feedback for the given grade
+ * @since  Moodle 3.1
+ */
+function quiz_feedback_record_for_grade($grade, $quiz) {
+    global $DB;
+
+    // With CBM etc, it is possible to get -ve grades, which would then not match
+    // any feedback. Therefore, we replace -ve grades with 0.
+    $grade = max($grade, 0);
+
+    $feedback = $DB->get_record_select('quiz_feedback',
+            'quizid = ? AND mingrade <= ? AND ? < maxgrade', array($quiz->id, $grade, $grade));
+
+    return $feedback;
+}
+
 /**
  * Get the feedback text that should be show to a student who
  * got this grade on this quiz. The feedback is processed ready for diplay.
@@ -554,18 +575,12 @@ function quiz_rescale_grade($rawgrade, $quiz, $format = true) {
  * @return string the comment that corresponds to this grade (empty string if there is not one.
  */
 function quiz_feedback_for_grade($grade, $quiz, $context) {
-    global $DB;
 
     if (is_null($grade)) {
         return '';
     }
 
-    // With CBM etc, it is possible to get -ve grades, which would then not match
+    $feedback = quiz_feedback_record_for_grade($grade, $quiz);
-    // any feedback. Therefore, we replace -ve grades with 0.
-    $grade = max($grade, 0);
-
-    $feedback = $DB->get_record_select('quiz_feedback',
-            'quizid = ? AND mingrade <= ? AND ? < maxgrade', array($quiz->id, $grade, $grade));
 
     if (empty($feedback->feedbacktext)) {
         return '';

mod/quiz/tests/external_test.php

@@ -1362,4 +1362,41 @@ class mod_quiz_external_testcase extends externallib_advanced_testcase {
 
     }
 
+    /**
+     * Test get_quiz_feedback_for_grade
+     */
+    public function test_get_quiz_feedback_for_grade() {
+        global $DB;
+
+        // Add feedback to the quiz.
+        $feedback = new stdClass();
+        $feedback->quizid = $this->quiz->id;
+        $feedback->feedbacktext = 'Feedback text 1';
+        $feedback->feedbacktextformat = 1;
+        $feedback->mingrade = 49;
+        $feedback->maxgrade = 100;
+        $feedback->id = $DB->insert_record('quiz_feedback', $feedback);
+
+        $feedback->feedbacktext = 'Feedback text 2';
+        $feedback->feedbacktextformat = 1;
+        $feedback->mingrade = 30;
+        $feedback->maxgrade = 49;
+        $feedback->id = $DB->insert_record('quiz_feedback', $feedback);
+
+        $result = mod_quiz_external::get_quiz_feedback_for_grade($this->quiz->id, 50);
+        $result = external_api::clean_returnvalue(mod_quiz_external::get_quiz_feedback_for_grade_returns(), $result);
+        $this->assertEquals('Feedback text 1', $result['feedbacktext']);
+        $this->assertEquals(FORMAT_HTML, $result['feedbacktextformat']);
+
+        $result = mod_quiz_external::get_quiz_feedback_for_grade($this->quiz->id, 30);
+        $result = external_api::clean_returnvalue(mod_quiz_external::get_quiz_feedback_for_grade_returns(), $result);
+        $this->assertEquals('Feedback text 2', $result['feedbacktext']);
+        $this->assertEquals(FORMAT_HTML, $result['feedbacktextformat']);
+
+        $result = mod_quiz_external::get_quiz_feedback_for_grade($this->quiz->id, 10);
+        $result = external_api::clean_returnvalue(mod_quiz_external::get_quiz_feedback_for_grade_returns(), $result);
+        $this->assertEquals('', $result['feedbacktext']);
+        $this->assertEquals(FORMAT_MOODLE, $result['feedbacktextformat']);
+    }
+
 }