question/type/rendererbase.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 /**
  18  * Defines the renderer base classes for question types.
  19  *
  20  * @package    moodlecore
  21  * @subpackage questiontypes
  22  * @copyright  2009 The Open University
  23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24  */
  25
  26
  27 defined('MOODLE_INTERNAL') || die();
  28
  29
  30 /**
  31  * Renderer base classes for question types.
  32  *
  33  * @copyright  2009 The Open University
  34  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  35  */
  36 abstract class qtype_renderer extends plugin_renderer_base {
  37     /**
  38      * Generate the display of the formulation part of the question. This is the
  39      * area that contains the quetsion text, and the controls for students to
  40      * input their answers. Some question types also embed bits of feedback, for
  41      * example ticks and crosses, in this area.
  42      *
  43      * @param question_attempt $qa the question attempt to display.
  44      * @param question_display_options $options controls what should and should not be displayed.
  45      * @return string HTML fragment.
  46      */
  47     public function formulation_and_controls(question_attempt $qa,
  48             question_display_options $options) {
  49         return $qa->get_question()->format_questiontext($qa);
  50     }
  51
  52     /**
  53      * In the question output there are some class="accesshide" headers to help
  54      * screen-readers. This method returns the text to use for the heading above
  55      * the formulation_and_controls section.
  56      * @return string to use as the heading.
  57      */
  58     public function formulation_heading() {
  59         return get_string('questiontext', 'question');
  60     }
  61
  62     /**
  63      * Output hidden form fields to clear any wrong parts of the student's response.
  64      *
  65      * This method will only be called if the question is in read-only mode.
  66      * @param question_attempt $qa the question attempt to display.
  67      * @return string HTML fragment.
  68      */
  69     public function clear_wrong(question_attempt $qa) {
  70         $response = $qa->get_last_qt_data();
  71         if (!$response) {
  72             return '';
  73         }
  74         $cleanresponse = $qa->get_question()->clear_wrong_from_response($response);
  75         $output = '';
  76         foreach ($cleanresponse as $name => $value) {
  77             $attr = array(
  78                 'type' => 'hidden',
  79                 'name' => $qa->get_qt_field_name($name),
  80                 'value' => s($value),
  81             );
  82             $output .= html_writer::empty_tag('input', $attr);
  83         }
  84         return $output;
  85     }
  86
  87     /**
  88      * Generate the display of the outcome part of the question. This is the
  89      * area that contains the various forms of feedback. This function generates
  90      * the content of this area belonging to the question type.
  91      *
  92      * Subclasses will normally want to override the more specific methods
  93      * {specific_feedback()}, {general_feedback()} and {correct_response()}
  94      * that this method calls.
  95      *
  96      * @param question_attempt $qa the question attempt to display.
  97      * @param question_display_options $options controls what should and should not be displayed.
  98      * @return string HTML fragment.
  99      */
 100     public function feedback(question_attempt $qa, question_display_options $options) {
 101         $output = '';
 102         $hint = null;
 103
 104         if ($options->feedback) {
 105             $output .= html_writer::nonempty_tag('div', $this->specific_feedback($qa),
 106                     array('class' => 'specificfeedback'));
 107             $hint = $qa->get_applicable_hint();
 108         }
 109
 110         if ($options->numpartscorrect) {
 111             $output .= html_writer::nonempty_tag('div', $this->num_parts_correct($qa),
 112                     array('class' => 'numpartscorrect'));
 113         }
 114
 115         if ($hint) {
 116             $output .= $this->hint($qa, $hint);
 117         }
 118
 119         if ($options->generalfeedback) {
 120             $output .= html_writer::nonempty_tag('div', $this->general_feedback($qa),
 121                     array('class' => 'generalfeedback'));
 122         }
 123
 124         if ($options->rightanswer) {
 125             $output .= html_writer::nonempty_tag('div', $this->correct_response($qa),
 126                     array('class' => 'rightanswer'));
 127         }
 128
 129         return $output;
 130     }
 131
 132     /**
 133      * Generate the specific feedback. This is feedback that varies according to
 134      * the response the student gave.
 135      * @param question_attempt $qa the question attempt to display.
 136      * @return string HTML fragment.
 137      */
 138     protected function specific_feedback(question_attempt $qa) {
 139         return '';
 140     }
 141
 142     /**
 143      * Gereate a brief statement of how many sub-parts of this question the
 144      * student got right.
 145      * @param question_attempt $qa the question attempt to display.
 146      * @return string HTML fragment.
 147      */
 148     protected function num_parts_correct(question_attempt $qa) {
 149         $a = new stdClass();
 150         list($a->num, $a->outof) = $qa->get_question()->get_num_parts_right(
 151                 $qa->get_last_qt_data());
 152         if (is_null($a->outof)) {
 153             return '';
 154         } else {
 155             return get_string('yougotnright', 'question', $a);
 156         }
 157     }
 158
 159     /**
 160      * Gereate the specific feedback. This is feedback that varies according to
 161      * the response the student gave.
 162      * @param question_attempt $qa the question attempt to display.
 163      * @return string HTML fragment.
 164      */
 165     protected function hint(question_attempt $qa, question_hint $hint) {
 166         return html_writer::nonempty_tag('div',
 167                 $qa->get_question()->format_hint($hint, $qa), array('class' => 'hint'));
 168     }
 169
 170     /**
 171      * Gereate the general feedback. This is feedback is shown ot all students.
 172      *
 173      * @param question_attempt $qa the question attempt to display.
 174      * @return string HTML fragment.
 175      */
 176     protected function general_feedback(question_attempt $qa) {
 177         return $qa->get_question()->format_generalfeedback($qa);
 178     }
 179
 180     /**
 181      * Gereate an automatic description of the correct response to this question.
 182      * Not all question types can do this. If it is not possible, this method
 183      * should just return an empty string.
 184      *
 185      * @param question_attempt $qa the question attempt to display.
 186      * @return string HTML fragment.
 187      */
 188     protected function correct_response(question_attempt $qa) {
 189         return '';
 190     }
 191
 192     /**
 193      * Display any extra question-type specific content that should be visible
 194      * when grading, if appropriate.
 195      *
 196      * @param question_attempt $qa a question attempt.
 197      * @param question_display_options $options controls what should and should not be displayed.
 198      * @return string HTML fragment.
 199      */
 200     public function manual_comment(question_attempt $qa, question_display_options $options) {
 201         return '';
 202     }
 203
 204     /**
 205      * Return any HTML that needs to be included in the page's <head> when this
 206      * question is used.
 207      * @param $qa the question attempt that will be displayed on the page.
 208      * @return string HTML fragment.
 209      */
 210     public function head_code(question_attempt $qa) {
 211         // This method is used by the Opaque question type. The remote question
 212         // engine can send back arbitrary CSS that we have to link to in the
 213         // page header. If it was not for that, we might be able to eliminate
 214         // this method and load the required CSS and JS some other way.
 215         $qa->get_question()->qtype->find_standard_scripts();
 216     }
 217
 218     protected function feedback_class($fraction) {
 219         return question_state::graded_state_for_fraction($fraction)->get_feedback_class();
 220     }
 221
 222     /**
 223      * Return an appropriate icon (green tick, red cross, etc.) for a grade.
 224      * @param float $fraction grade on a scale 0..1.
 225      * @param bool $selected whether to show a big or small icon. (Deprecated)
 226      * @return string html fragment.
 227      */
 228     protected function feedback_image($fraction, $selected = true) {
 229         $feedbackclass = question_state::graded_state_for_fraction($fraction)->get_feedback_class();
 230
 231         return $this->output->pix_icon('i/grade_' . $feedbackclass, get_string($feedbackclass, 'question'));
 232     }
 233 }
 234
 235 /**
 236  * Renderer base classes for question types.
 237  *
 238  * @copyright  2010 The Open University
 239  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 240  */
 241 abstract class qtype_with_combined_feedback_renderer extends qtype_renderer {
 242     protected function combined_feedback(question_attempt $qa) {
 243         $question = $qa->get_question();
 244
 245         $state = $qa->get_state();
 246
 247         if (!$state->is_finished()) {
 248             $response = $qa->get_last_qt_data();
 249             if (!$qa->get_question()->is_gradable_response($response)) {
 250                 return '';
 251             }
 252             list($notused, $state) = $qa->get_question()->grade_response($response);
 253         }
 254
 255         $feedback = '';
 256         $field = $state->get_feedback_class() . 'feedback';
 257         $format = $state->get_feedback_class() . 'feedbackformat';
 258         if ($question->$field) {
 259             $feedback .= $question->format_text($question->$field, $question->$format,
 260                     $qa, 'question', $field, $question->id);
 261         }
 262
 263         return $feedback;
 264     }
 265 }