weekly release 2.2dev
[moodle.git] / question / engine / renderer.php
CommitLineData
d1b7e03d 1<?php
d1b7e03d
TH
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
d1b7e03d
TH
17/**
18 * Renderers for outputting parts of the question engine.
19 *
017bc1d9 20 * @package moodlecore
d1b7e03d 21 * @subpackage questionengine
017bc1d9
TH
22 * @copyright 2009 The Open University
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
d1b7e03d
TH
24 */
25
26
a17b297d
TH
27defined('MOODLE_INTERNAL') || die();
28
29
d1b7e03d
TH
30/**
31 * This renderer controls the overall output of questions. It works with a
32 * {@link qbehaviour_renderer} and a {@link qtype_renderer} to output the
33 * type-specific bits. The main entry point is the {@link question()} method.
34 *
017bc1d9
TH
35 * @copyright 2009 The Open University
36 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
d1b7e03d 37 */
729c372b 38class core_question_renderer extends plugin_renderer_base {
2daffca5
TH
39 public function get_page() {
40 return $this->page;
41 }
d1b7e03d
TH
42
43 /**
44 * Generate the display of a question in a particular state, and with certain
45 * display options. Normally you do not call this method directly. Intsead
46 * you call {@link question_usage_by_activity::render_question()} which will
47 * call this method with appropriate arguments.
48 *
49 * @param question_attempt $qa the question attempt to display.
50 * @param qbehaviour_renderer $behaviouroutput the renderer to output the behaviour
51 * specific parts.
52 * @param qtype_renderer $qtoutput the renderer to output the question type
53 * specific parts.
54 * @param question_display_options $options controls what should and should not be displayed.
55 * @param string|null $number The question number to display. 'i' is a special
56 * value that gets displayed as Information. Null means no number is displayed.
57 * @return string HTML representation of the question.
58 */
59 public function question(question_attempt $qa, qbehaviour_renderer $behaviouroutput,
60 qtype_renderer $qtoutput, question_display_options $options, $number) {
61
62 $output = '';
63 $output .= html_writer::start_tag('div', array(
64 'id' => 'q' . $qa->get_slot(),
65 'class' => 'que ' . $qa->get_question()->qtype->name() . ' ' .
66 $qa->get_behaviour_name(),
67 ));
68
69 $output .= html_writer::tag('div',
70 $this->info($qa, $behaviouroutput, $qtoutput, $options, $number),
71 array('class' => 'info'));
72
73 $output .= html_writer::start_tag('div', array('class' => 'content'));
74
75 $output .= html_writer::tag('div',
76 $this->add_part_heading(get_string('questiontext', 'question'),
77 $this->formulation($qa, $behaviouroutput, $qtoutput, $options)),
78 array('class' => 'formulation'));
79 $output .= html_writer::nonempty_tag('div',
80 $this->add_part_heading(get_string('feedback', 'question'),
81 $this->outcome($qa, $behaviouroutput, $qtoutput, $options)),
82 array('class' => 'outcome'));
83 $output .= html_writer::nonempty_tag('div',
84 $this->add_part_heading(get_string('comments', 'question'),
783af252
TH
85 $this->manual_comment($qa, $behaviouroutput, $qtoutput, $options)),
86 array('class' => 'comment'));
d1b7e03d
TH
87 $output .= html_writer::nonempty_tag('div',
88 $this->response_history($qa, $behaviouroutput, $qtoutput, $options),
89 array('class' => 'history'));
90
91 $output .= html_writer::end_tag('div');
92 $output .= html_writer::end_tag('div');
93 return $output;
94 }
95
96 /**
97 * Generate the information bit of the question display that contains the
98 * metadata like the question number, current state, and mark.
99 * @param question_attempt $qa the question attempt to display.
100 * @param qbehaviour_renderer $behaviouroutput the renderer to output the behaviour
101 * specific parts.
102 * @param qtype_renderer $qtoutput the renderer to output the question type
103 * specific parts.
104 * @param question_display_options $options controls what should and should not be displayed.
105 * @param string|null $number The question number to display. 'i' is a special
106 * value that gets displayed as Information. Null means no number is displayed.
107 * @return HTML fragment.
108 */
109 protected function info(question_attempt $qa, qbehaviour_renderer $behaviouroutput,
110 qtype_renderer $qtoutput, question_display_options $options, $number) {
111 $output = '';
112 $output .= $this->number($number);
113 $output .= $this->status($qa, $behaviouroutput, $options);
114 $output .= $this->mark_summary($qa, $options);
115 $output .= $this->question_flag($qa, $options->flags);
da729916 116 $output .= $this->edit_question_link($qa, $options);
d1b7e03d
TH
117 return $output;
118 }
119
120 /**
121 * Generate the display of the question number.
122 * @param string|null $number The question number to display. 'i' is a special
123 * value that gets displayed as Information. Null means no number is displayed.
124 * @return HTML fragment.
125 */
126 protected function number($number) {
127 $numbertext = '';
128 if (is_numeric($number)) {
129 $numbertext = get_string('questionx', 'question',
130 html_writer::tag('span', $number, array('class' => 'qno')));
131 } else if ($number == 'i') {
132 $numbertext = get_string('information', 'question');
133 }
134 if (!$numbertext) {
135 return '';
136 }
137 return html_writer::tag('h2', $numbertext, array('class' => 'no'));
138 }
139
140 /**
141 * Add an invisible heading like 'question text', 'feebdack' at the top of
142 * a section's contents, but only if the section has some content.
143 * @param string $heading the heading to add.
144 * @param string $content the content of the section.
145 * @return string HTML fragment with the heading added.
146 */
147 protected function add_part_heading($heading, $content) {
148 if ($content) {
149 $content = html_writer::tag('h3', $heading, array('class' => 'accesshide')) . $content;
150 }
151 return $content;
152 }
153
154 /**
155 * Generate the display of the status line that gives the current state of
156 * the question.
157 * @param question_attempt $qa the question attempt to display.
158 * @param qbehaviour_renderer $behaviouroutput the renderer to output the behaviour
159 * specific parts.
160 * @param question_display_options $options controls what should and should not be displayed.
161 * @return HTML fragment.
162 */
9c197f44
TH
163 protected function status(question_attempt $qa, qbehaviour_renderer $behaviouroutput,
164 question_display_options $options) {
d1b7e03d
TH
165 return html_writer::tag('div', $qa->get_state_string($options->correctness),
166 array('class' => 'state'));
167 }
168
169 /**
170 * Generate the display of the marks for this question.
171 * @param question_attempt $qa the question attempt to display.
172 * @param question_display_options $options controls what should and should not be displayed.
173 * @return HTML fragment.
174 */
175 protected function mark_summary(question_attempt $qa, question_display_options $options) {
176 if (!$options->marks) {
177 return '';
178 }
179
180 if ($qa->get_max_mark() == 0) {
181 $summary = get_string('notgraded', 'question');
182
183 } else if ($options->marks == question_display_options::MAX_ONLY ||
184 is_null($qa->get_fraction())) {
9c197f44
TH
185 $summary = get_string('markedoutofmax', 'question',
186 $qa->format_max_mark($options->markdp));
d1b7e03d
TH
187
188 } else {
0ff4bd08 189 $a = new stdClass();
d1b7e03d
TH
190 $a->mark = $qa->format_mark($options->markdp);
191 $a->max = $qa->format_max_mark($options->markdp);
192 $summary = get_string('markoutofmax', 'question', $a);
193 }
194
195 return html_writer::tag('div', $summary, array('class' => 'grade'));
196 }
197
198 /**
199 * Render the question flag, assuming $flagsoption allows it.
200 *
201 * @param question_attempt $qa the question attempt to display.
f7970e3c 202 * @param int $flagsoption the option that says whether flags should be displayed.
d1b7e03d
TH
203 */
204 protected function question_flag(question_attempt $qa, $flagsoption) {
205 global $CFG;
206 switch ($flagsoption) {
207 case question_display_options::VISIBLE:
208 $flagcontent = $this->get_flag_html($qa->is_flagged());
209 break;
210 case question_display_options::EDITABLE:
211 $id = $qa->get_flag_field_name();
212 if ($qa->is_flagged()) {
213 $checked = 'checked="checked" ';
214 } else {
215 $checked = '';
216 }
217 $postdata = question_flags::get_postdata($qa);
9c197f44
TH
218 // The checkbox id must be different from any element name, because
219 // of a stupid IE bug:
220 // http://www.456bereastreet.com/archive/200802/beware_of_id_and_name_attribute_mixups_when_using_getelementbyid_in_internet_explorer/
d1b7e03d 221 $flagcontent = '<input type="hidden" name="' . $id . '" value="0" />' .
9c197f44
TH
222 '<input type="checkbox" id="' . $id . 'checkbox" name="' . $id .
223 '" value="1" ' . $checked . ' />' .
224 '<input type="hidden" value="' . s($postdata) .
225 '" class="questionflagpostdata" />' .
226 '<label id="' . $id . 'label" for="' . $id . 'checkbox">' .
227 $this->get_flag_html($qa->is_flagged(), $id . 'img') .
228 '</label>' . "\n";
d1b7e03d
TH
229 break;
230 default:
231 $flagcontent = '';
232 }
233 if ($flagcontent) {
234 return '<div class="questionflag">' . $flagcontent . "</div>\n";
235 }
236 }
237
238 /**
239 * Work out the actual img tag needed for the flag
240 *
f7970e3c 241 * @param bool $flagged whether the question is currently flagged.
d1b7e03d
TH
242 * @param string $id an id to be added as an attribute to the img (optional).
243 * @return string the img tag.
244 */
245 protected function get_flag_html($flagged, $id = '') {
22c97c64
TH
246 if ($flagged) {
247 $icon = 'i/flagged';
248 $alt = get_string('flagged', 'question');
249 } else {
250 $icon = 'i/unflagged';
251 $alt = get_string('notflagged', 'question');
252 }
253 $attributes = array(
254 'src' => $this->pix_url($icon),
255 'alt' => $alt,
256 );
d1b7e03d 257 if ($id) {
22c97c64 258 $attributes['id'] = $id;
d1b7e03d 259 }
22c97c64 260 $img = html_writer::empty_tag('img', $attributes);
d1b7e03d 261 if ($flagged) {
22c97c64 262 $img .= ' ' . get_string('flagged', 'question');
d1b7e03d 263 }
22c97c64 264 return $img;
d1b7e03d
TH
265 }
266
da729916
TH
267 protected function edit_question_link(question_attempt $qa,
268 question_display_options $options) {
269 global $CFG;
270
271 if (empty($options->editquestionparams)) {
272 return '';
273 }
274
275 $params = $options->editquestionparams;
276 if ($params['returnurl'] instanceof moodle_url) {
277 $params['returnurl'] = str_replace($CFG->wwwroot, '',
278 $params['returnurl']->out(false));
279 }
280 $params['id'] = $qa->get_question()->id;
281 $editurl = new moodle_url('/question/question.php', $params);
282
283 return html_writer::tag('div', html_writer::link(
284 $editurl, $this->pix_icon('i/edit', get_string('edit')) .
285 get_string('editquestion', 'question')),
286 array('class' => 'editquestion'));
287 }
288
d1b7e03d
TH
289 /**
290 * Generate the display of the formulation part of the question. This is the
291 * area that contains the quetsion text, and the controls for students to
292 * input their answers. Some question types also embed feedback, for
293 * example ticks and crosses, in this area.
294 *
295 * @param question_attempt $qa the question attempt to display.
296 * @param qbehaviour_renderer $behaviouroutput the renderer to output the behaviour
297 * specific parts.
298 * @param qtype_renderer $qtoutput the renderer to output the question type
299 * specific parts.
300 * @param question_display_options $options controls what should and should not be displayed.
301 * @return HTML fragment.
302 */
303 protected function formulation(question_attempt $qa, qbehaviour_renderer $behaviouroutput,
304 qtype_renderer $qtoutput, question_display_options $options) {
305 $output = '';
306 $output .= html_writer::empty_tag('input', array(
307 'type' => 'hidden',
308 'name' => $qa->get_control_field_name('sequencecheck'),
309 'value' => $qa->get_num_steps()));
310 $output .= $qtoutput->formulation_and_controls($qa, $options);
311 if ($options->clearwrong) {
312 $output .= $qtoutput->clear_wrong($qa);
313 }
314 $output .= html_writer::nonempty_tag('div',
315 $behaviouroutput->controls($qa, $options), array('class' => 'im-controls'));
316 return $output;
317 }
318
319 /**
320 * Generate the display of the outcome part of the question. This is the
321 * area that contains the various forms of feedback.
322 *
323 * @param question_attempt $qa the question attempt to display.
324 * @param qbehaviour_renderer $behaviouroutput the renderer to output the behaviour
325 * specific parts.
326 * @param qtype_renderer $qtoutput the renderer to output the question type
327 * specific parts.
328 * @param question_display_options $options controls what should and should not be displayed.
329 * @return HTML fragment.
330 */
331 protected function outcome(question_attempt $qa, qbehaviour_renderer $behaviouroutput,
332 qtype_renderer $qtoutput, question_display_options $options) {
333 $output = '';
334 $output .= html_writer::nonempty_tag('div',
335 $qtoutput->feedback($qa, $options), array('class' => 'feedback'));
336 $output .= html_writer::nonempty_tag('div',
337 $behaviouroutput->feedback($qa, $options), array('class' => 'im-feedback'));
338 return $output;
339 }
340
783af252
TH
341 protected function manual_comment(question_attempt $qa, qbehaviour_renderer $behaviouroutput,
342 qtype_renderer $qtoutput, question_display_options $options) {
343 return $qtoutput->manual_comment($qa, $options) .
344 $behaviouroutput->manual_comment($qa, $options);
345 }
346
d1b7e03d
TH
347 /**
348 * Generate the display of the response history part of the question. This
349 * is the table showing all the steps the question has been through.
350 *
351 * @param question_attempt $qa the question attempt to display.
352 * @param qbehaviour_renderer $behaviouroutput the renderer to output the behaviour
353 * specific parts.
354 * @param qtype_renderer $qtoutput the renderer to output the question type
355 * specific parts.
356 * @param question_display_options $options controls what should and should not be displayed.
357 * @return HTML fragment.
358 */
359 protected function response_history(question_attempt $qa, qbehaviour_renderer $behaviouroutput,
360 qtype_renderer $qtoutput, question_display_options $options) {
361
362 if (!$options->history) {
363 return '';
364 }
365
068b4594 366 $table = new html_table();
d1b7e03d
TH
367 $table->head = array (
368 get_string('step', 'question'),
369 get_string('time'),
370 get_string('action', 'question'),
371 get_string('state', 'question'),
372 );
373 if ($options->marks >= question_display_options::MARK_AND_MAX) {
374 $table->head[] = get_string('marks', 'question');
375 }
376
377 foreach ($qa->get_full_step_iterator() as $i => $step) {
378 $stepno = $i + 1;
379 $rowclass = '';
380 if ($stepno == $qa->get_num_steps()) {
381 $rowclass = 'current';
382 } else if (!empty($options->questionreviewlink)) {
9c197f44
TH
383 $url = new moodle_url($options->questionreviewlink,
384 array('slot' => $qa->get_slot(), 'step' => $i));
729c372b 385 $stepno = $this->output->action_link($url, $stepno,
9c197f44
TH
386 new popup_action('click', $url, 'reviewquestion',
387 array('width' => 450, 'height' => 650)),
5e8a85aa 388 array('title' => get_string('reviewresponse', 'question')));
d1b7e03d 389 }
0ff4bd08 390 $user = new stdClass();
d1b7e03d
TH
391 $user->id = $step->get_user_id();
392 $row = array(
393 $stepno,
394 userdate($step->get_timecreated(), get_string('strftimedatetimeshort')),
395 s($qa->summarise_action($step)),
396 $step->get_state()->default_string(true),
397 );
398
399 if ($options->marks >= question_display_options::MARK_AND_MAX) {
400 $row[] = $qa->format_fraction_as_mark($step->get_fraction(), $options->markdp);
401 }
402
068b4594 403 $table->rowclasses[] = $rowclass;
d1b7e03d
TH
404 $table->data[] = $row;
405 }
406
407 return html_writer::tag('h3', get_string('responsehistory', 'question'),
408 array('class' => 'responsehistoryheader')) . html_writer::tag('div',
068b4594 409 html_writer::table($table, true), array('class' => 'responsehistoryheader'));
d1b7e03d
TH
410 }
411
412}