Merge branch 'MDL-70065_310' of https://github.com/timhunt/moodle into MOODLE_310_STABLE
[moodle.git] / 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/>.
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  */
27 defined('MOODLE_INTERNAL') || die();
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     }
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     }
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     }
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;
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         }
110         if ($options->numpartscorrect) {
111             $output .= html_writer::nonempty_tag('div', $this->num_parts_correct($qa),
112                     array('class' => 'numpartscorrect'));
113         }
115         if ($hint) {
116             $output .= $this->hint($qa, $hint);
117         }
119         if ($options->generalfeedback) {
120             $output .= html_writer::nonempty_tag('div', $this->general_feedback($qa),
121                     array('class' => 'generalfeedback'));
122         }
124         if ($options->rightanswer) {
125             $output .= html_writer::nonempty_tag('div', $this->correct_response($qa),
126                     array('class' => 'rightanswer'));
127         }
129         return $output;
130     }
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     }
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     }
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     }
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     }
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     }
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     }
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     }
218     protected function feedback_class($fraction) {
219         return question_state::graded_state_for_fraction($fraction)->get_feedback_class();
220     }
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();
231         return $this->output->pix_icon('i/grade_' . $feedbackclass, get_string($feedbackclass, 'question'));
232     }
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();
245         $state = $qa->get_state();
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         }
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         }
263         return $feedback;
264     }