on-demand release 2.6beta+
[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(),
25d9a6a6
TH
65 'class' => implode(' ', array(
66 'que',
67 $qa->get_question()->qtype->name(),
68 $qa->get_behaviour_name(),
69 $qa->get_state_class($options->correctness && $qa->has_marks()),
70 ))
d1b7e03d
TH
71 ));
72
73 $output .= html_writer::tag('div',
74 $this->info($qa, $behaviouroutput, $qtoutput, $options, $number),
75 array('class' => 'info'));
76
77 $output .= html_writer::start_tag('div', array('class' => 'content'));
78
79 $output .= html_writer::tag('div',
7042a252
TH
80 $this->add_part_heading($qtoutput->formulation_heading(),
81 $this->formulation($qa, $behaviouroutput, $qtoutput, $options)),
d1b7e03d
TH
82 array('class' => 'formulation'));
83 $output .= html_writer::nonempty_tag('div',
84 $this->add_part_heading(get_string('feedback', 'question'),
7042a252 85 $this->outcome($qa, $behaviouroutput, $qtoutput, $options)),
d1b7e03d
TH
86 array('class' => 'outcome'));
87 $output .= html_writer::nonempty_tag('div',
88 $this->add_part_heading(get_string('comments', 'question'),
7042a252 89 $this->manual_comment($qa, $behaviouroutput, $qtoutput, $options)),
783af252 90 array('class' => 'comment'));
d1b7e03d
TH
91 $output .= html_writer::nonempty_tag('div',
92 $this->response_history($qa, $behaviouroutput, $qtoutput, $options),
93 array('class' => 'history'));
94
95 $output .= html_writer::end_tag('div');
96 $output .= html_writer::end_tag('div');
97 return $output;
98 }
99
100 /**
101 * Generate the information bit of the question display that contains the
102 * metadata like the question number, current state, and mark.
103 * @param question_attempt $qa the question attempt to display.
104 * @param qbehaviour_renderer $behaviouroutput the renderer to output the behaviour
105 * specific parts.
106 * @param qtype_renderer $qtoutput the renderer to output the question type
107 * specific parts.
108 * @param question_display_options $options controls what should and should not be displayed.
109 * @param string|null $number The question number to display. 'i' is a special
110 * value that gets displayed as Information. Null means no number is displayed.
111 * @return HTML fragment.
112 */
113 protected function info(question_attempt $qa, qbehaviour_renderer $behaviouroutput,
114 qtype_renderer $qtoutput, question_display_options $options, $number) {
115 $output = '';
116 $output .= $this->number($number);
117 $output .= $this->status($qa, $behaviouroutput, $options);
02d3e4d5 118 $output .= $this->mark_summary($qa, $behaviouroutput, $options);
d1b7e03d 119 $output .= $this->question_flag($qa, $options->flags);
da729916 120 $output .= $this->edit_question_link($qa, $options);
d1b7e03d
TH
121 return $output;
122 }
123
124 /**
125 * Generate the display of the question number.
126 * @param string|null $number The question number to display. 'i' is a special
127 * value that gets displayed as Information. Null means no number is displayed.
128 * @return HTML fragment.
129 */
130 protected function number($number) {
131 $numbertext = '';
132 if (is_numeric($number)) {
133 $numbertext = get_string('questionx', 'question',
134 html_writer::tag('span', $number, array('class' => 'qno')));
135 } else if ($number == 'i') {
136 $numbertext = get_string('information', 'question');
137 }
138 if (!$numbertext) {
139 return '';
140 }
141 return html_writer::tag('h2', $numbertext, array('class' => 'no'));
142 }
143
144 /**
145 * Add an invisible heading like 'question text', 'feebdack' at the top of
146 * a section's contents, but only if the section has some content.
147 * @param string $heading the heading to add.
148 * @param string $content the content of the section.
149 * @return string HTML fragment with the heading added.
150 */
151 protected function add_part_heading($heading, $content) {
152 if ($content) {
153 $content = html_writer::tag('h3', $heading, array('class' => 'accesshide')) . $content;
154 }
155 return $content;
156 }
157
158 /**
159 * Generate the display of the status line that gives the current state of
160 * the question.
161 * @param question_attempt $qa the question attempt to display.
162 * @param qbehaviour_renderer $behaviouroutput the renderer to output the behaviour
163 * specific parts.
164 * @param question_display_options $options controls what should and should not be displayed.
165 * @return HTML fragment.
166 */
9c197f44
TH
167 protected function status(question_attempt $qa, qbehaviour_renderer $behaviouroutput,
168 question_display_options $options) {
d1b7e03d
TH
169 return html_writer::tag('div', $qa->get_state_string($options->correctness),
170 array('class' => 'state'));
171 }
172
173 /**
174 * Generate the display of the marks for this question.
175 * @param question_attempt $qa the question attempt to display.
02d3e4d5 176 * @param qbehaviour_renderer $behaviouroutput the behaviour renderer, which can generate a custom display.
d1b7e03d
TH
177 * @param question_display_options $options controls what should and should not be displayed.
178 * @return HTML fragment.
179 */
02d3e4d5
TH
180 protected function mark_summary(question_attempt $qa, qbehaviour_renderer $behaviouroutput, question_display_options $options) {
181 return html_writer::nonempty_tag('div',
182 $behaviouroutput->mark_summary($qa, $this, $options),
183 array('class' => 'grade'));
184 }
185
186 /**
187 * Generate the display of the marks for this question.
188 * @param question_attempt $qa the question attempt to display.
189 * @param question_display_options $options controls what should and should not be displayed.
190 * @return HTML fragment.
191 */
192 public function standard_mark_summary(question_attempt $qa, qbehaviour_renderer $behaviouroutput, question_display_options $options) {
d1b7e03d
TH
193 if (!$options->marks) {
194 return '';
d1b7e03d 195
02d3e4d5
TH
196 } else if ($qa->get_max_mark() == 0) {
197 return get_string('notgraded', 'question');
d1b7e03d
TH
198
199 } else if ($options->marks == question_display_options::MAX_ONLY ||
200 is_null($qa->get_fraction())) {
02d3e4d5 201 return $behaviouroutput->marked_out_of_max($qa, $this, $options);
d1b7e03d
TH
202
203 } else {
02d3e4d5 204 return $behaviouroutput->mark_out_of_max($qa, $this, $options);
d1b7e03d 205 }
02d3e4d5
TH
206 }
207
208 /**
209 * Generate the display of the available marks for this question.
210 * @param question_attempt $qa the question attempt to display.
211 * @param question_display_options $options controls what should and should not be displayed.
212 * @return HTML fragment.
213 */
214 public function standard_marked_out_of_max(question_attempt $qa, question_display_options $options) {
215 return get_string('markedoutofmax', 'question', $qa->format_max_mark($options->markdp));
216 }
d1b7e03d 217
02d3e4d5
TH
218 /**
219 * Generate the display of the marks for this question out of the available marks.
220 * @param question_attempt $qa the question attempt to display.
221 * @param question_display_options $options controls what should and should not be displayed.
222 * @return HTML fragment.
223 */
224 public function standard_mark_out_of_max(question_attempt $qa, question_display_options $options) {
225 $a = new stdClass();
226 $a->mark = $qa->format_mark($options->markdp);
227 $a->max = $qa->format_max_mark($options->markdp);
228 return get_string('markoutofmax', 'question', $a);
d1b7e03d
TH
229 }
230
231 /**
232 * Render the question flag, assuming $flagsoption allows it.
233 *
234 * @param question_attempt $qa the question attempt to display.
f7970e3c 235 * @param int $flagsoption the option that says whether flags should be displayed.
d1b7e03d
TH
236 */
237 protected function question_flag(question_attempt $qa, $flagsoption) {
238 global $CFG;
f1b3d3e0
TH
239
240 $divattributes = array('class' => 'questionflag');
241
d1b7e03d
TH
242 switch ($flagsoption) {
243 case question_display_options::VISIBLE:
244 $flagcontent = $this->get_flag_html($qa->is_flagged());
245 break;
f1b3d3e0 246
d1b7e03d
TH
247 case question_display_options::EDITABLE:
248 $id = $qa->get_flag_field_name();
9c197f44
TH
249 // The checkbox id must be different from any element name, because
250 // of a stupid IE bug:
251 // http://www.456bereastreet.com/archive/200802/beware_of_id_and_name_attribute_mixups_when_using_getelementbyid_in_internet_explorer/
f1b3d3e0
TH
252 $checkboxattributes = array(
253 'type' => 'checkbox',
254 'id' => $id . 'checkbox',
255 'name' => $id,
256 'value' => 1,
257 );
258 if ($qa->is_flagged()) {
259 $checkboxattributes['checked'] = 'checked';
260 }
261 $postdata = question_flags::get_postdata($qa);
262
263 $flagcontent = html_writer::empty_tag('input',
264 array('type' => 'hidden', 'name' => $id, 'value' => 0)) .
265 html_writer::empty_tag('input', $checkboxattributes) .
266 html_writer::empty_tag('input',
267 array('type' => 'hidden', 'value' => $postdata, 'class' => 'questionflagpostdata')) .
268 html_writer::tag('label', $this->get_flag_html($qa->is_flagged(), $id . 'img'),
269 array('id' => $id . 'label', 'for' => $id . 'checkbox')) . "\n";
270
271 $divattributes = array(
272 'class' => 'questionflag editable',
273 'aria-atomic' => 'true',
274 'aria-relevant' => 'text',
275 'aria-live' => 'assertive',
276 );
277
d1b7e03d 278 break;
f1b3d3e0 279
d1b7e03d
TH
280 default:
281 $flagcontent = '';
282 }
f1b3d3e0
TH
283
284 return html_writer::nonempty_tag('div', $flagcontent, $divattributes);
d1b7e03d
TH
285 }
286
287 /**
288 * Work out the actual img tag needed for the flag
289 *
f7970e3c 290 * @param bool $flagged whether the question is currently flagged.
d1b7e03d
TH
291 * @param string $id an id to be added as an attribute to the img (optional).
292 * @return string the img tag.
293 */
294 protected function get_flag_html($flagged, $id = '') {
22c97c64
TH
295 if ($flagged) {
296 $icon = 'i/flagged';
297 $alt = get_string('flagged', 'question');
298 } else {
299 $icon = 'i/unflagged';
300 $alt = get_string('notflagged', 'question');
301 }
302 $attributes = array(
303 'src' => $this->pix_url($icon),
304 'alt' => $alt,
305 );
d1b7e03d 306 if ($id) {
22c97c64 307 $attributes['id'] = $id;
d1b7e03d 308 }
22c97c64 309 $img = html_writer::empty_tag('img', $attributes);
d1b7e03d 310 if ($flagged) {
22c97c64 311 $img .= ' ' . get_string('flagged', 'question');
d1b7e03d 312 }
22c97c64 313 return $img;
d1b7e03d
TH
314 }
315
da729916
TH
316 protected function edit_question_link(question_attempt $qa,
317 question_display_options $options) {
318 global $CFG;
319
320 if (empty($options->editquestionparams)) {
321 return '';
322 }
323
324 $params = $options->editquestionparams;
325 if ($params['returnurl'] instanceof moodle_url) {
a530d4a9 326 $params['returnurl'] = $params['returnurl']->out_as_local_url(false);
da729916
TH
327 }
328 $params['id'] = $qa->get_question()->id;
329 $editurl = new moodle_url('/question/question.php', $params);
330
331 return html_writer::tag('div', html_writer::link(
c3847443 332 $editurl, $this->pix_icon('t/edit', get_string('edit'), '', array('class' => 'iconsmall')) .
da729916
TH
333 get_string('editquestion', 'question')),
334 array('class' => 'editquestion'));
335 }
336
d1b7e03d
TH
337 /**
338 * Generate the display of the formulation part of the question. This is the
339 * area that contains the quetsion text, and the controls for students to
340 * input their answers. Some question types also embed feedback, for
341 * example ticks and crosses, in this area.
342 *
343 * @param question_attempt $qa the question attempt to display.
344 * @param qbehaviour_renderer $behaviouroutput the renderer to output the behaviour
345 * specific parts.
346 * @param qtype_renderer $qtoutput the renderer to output the question type
347 * specific parts.
348 * @param question_display_options $options controls what should and should not be displayed.
349 * @return HTML fragment.
350 */
351 protected function formulation(question_attempt $qa, qbehaviour_renderer $behaviouroutput,
352 qtype_renderer $qtoutput, question_display_options $options) {
353 $output = '';
354 $output .= html_writer::empty_tag('input', array(
355 'type' => 'hidden',
356 'name' => $qa->get_control_field_name('sequencecheck'),
c7fbfe46 357 'value' => $qa->get_sequence_check_count()));
d1b7e03d
TH
358 $output .= $qtoutput->formulation_and_controls($qa, $options);
359 if ($options->clearwrong) {
360 $output .= $qtoutput->clear_wrong($qa);
361 }
362 $output .= html_writer::nonempty_tag('div',
363 $behaviouroutput->controls($qa, $options), array('class' => 'im-controls'));
364 return $output;
365 }
366
367 /**
368 * Generate the display of the outcome part of the question. This is the
369 * area that contains the various forms of feedback.
370 *
371 * @param question_attempt $qa the question attempt to display.
372 * @param qbehaviour_renderer $behaviouroutput the renderer to output the behaviour
373 * specific parts.
374 * @param qtype_renderer $qtoutput the renderer to output the question type
375 * specific parts.
376 * @param question_display_options $options controls what should and should not be displayed.
377 * @return HTML fragment.
378 */
379 protected function outcome(question_attempt $qa, qbehaviour_renderer $behaviouroutput,
380 qtype_renderer $qtoutput, question_display_options $options) {
381 $output = '';
382 $output .= html_writer::nonempty_tag('div',
383 $qtoutput->feedback($qa, $options), array('class' => 'feedback'));
384 $output .= html_writer::nonempty_tag('div',
385 $behaviouroutput->feedback($qa, $options), array('class' => 'im-feedback'));
386 return $output;
387 }
388
783af252
TH
389 protected function manual_comment(question_attempt $qa, qbehaviour_renderer $behaviouroutput,
390 qtype_renderer $qtoutput, question_display_options $options) {
391 return $qtoutput->manual_comment($qa, $options) .
392 $behaviouroutput->manual_comment($qa, $options);
393 }
394
d1b7e03d
TH
395 /**
396 * Generate the display of the response history part of the question. This
397 * is the table showing all the steps the question has been through.
398 *
399 * @param question_attempt $qa the question attempt to display.
400 * @param qbehaviour_renderer $behaviouroutput the renderer to output the behaviour
401 * specific parts.
402 * @param qtype_renderer $qtoutput the renderer to output the question type
403 * specific parts.
404 * @param question_display_options $options controls what should and should not be displayed.
405 * @return HTML fragment.
406 */
407 protected function response_history(question_attempt $qa, qbehaviour_renderer $behaviouroutput,
408 qtype_renderer $qtoutput, question_display_options $options) {
409
410 if (!$options->history) {
411 return '';
412 }
413
068b4594 414 $table = new html_table();
d1b7e03d
TH
415 $table->head = array (
416 get_string('step', 'question'),
417 get_string('time'),
418 get_string('action', 'question'),
419 get_string('state', 'question'),
420 );
421 if ($options->marks >= question_display_options::MARK_AND_MAX) {
422 $table->head[] = get_string('marks', 'question');
423 }
424
425 foreach ($qa->get_full_step_iterator() as $i => $step) {
426 $stepno = $i + 1;
d47d12d0 427
d1b7e03d
TH
428 $rowclass = '';
429 if ($stepno == $qa->get_num_steps()) {
430 $rowclass = 'current';
431 } else if (!empty($options->questionreviewlink)) {
9c197f44
TH
432 $url = new moodle_url($options->questionreviewlink,
433 array('slot' => $qa->get_slot(), 'step' => $i));
729c372b 434 $stepno = $this->output->action_link($url, $stepno,
9c197f44
TH
435 new popup_action('click', $url, 'reviewquestion',
436 array('width' => 450, 'height' => 650)),
5e8a85aa 437 array('title' => get_string('reviewresponse', 'question')));
d1b7e03d 438 }
d47d12d0
TH
439
440 $restrictedqa = new question_attempt_with_restricted_history($qa, $i, null);
441
0ff4bd08 442 $user = new stdClass();
d1b7e03d
TH
443 $user->id = $step->get_user_id();
444 $row = array(
445 $stepno,
446 userdate($step->get_timecreated(), get_string('strftimedatetimeshort')),
447 s($qa->summarise_action($step)),
d47d12d0 448 $restrictedqa->get_state_string($options->correctness),
d1b7e03d
TH
449 );
450
451 if ($options->marks >= question_display_options::MARK_AND_MAX) {
452 $row[] = $qa->format_fraction_as_mark($step->get_fraction(), $options->markdp);
453 }
454
068b4594 455 $table->rowclasses[] = $rowclass;
d1b7e03d
TH
456 $table->data[] = $row;
457 }
458
459 return html_writer::tag('h3', get_string('responsehistory', 'question'),
460 array('class' => 'responsehistoryheader')) . html_writer::tag('div',
068b4594 461 html_writer::table($table, true), array('class' => 'responsehistoryheader'));
d1b7e03d
TH
462 }
463
464}