weekly release 3.9dev+
[moodle.git] / question / engine / questionattempt.php
CommitLineData
dcd03928 1<?php
dcd03928
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
17/**
18 * This file defines the question attempt class, and a few related classes.
19 *
20 * @package moodlecore
21 * @subpackage questionengine
22 * @copyright 2009 The Open University
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24 */
25
26
27defined('MOODLE_INTERNAL') || die();
28
29
30/**
31 * Tracks an attempt at one particular question in a {@link question_usage_by_activity}.
32 *
33 * Most calling code should need to access objects of this class. They should be
34 * able to do everything through the usage interface. This class is an internal
35 * implementation detail of the question engine.
36 *
37 * Instances of this class correspond to rows in the question_attempts table, and
38 * a collection of {@link question_attempt_steps}. Question inteaction models and
39 * question types do work with question_attempt objects.
40 *
41 * @copyright 2009 The Open University
42 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
43 */
44class question_attempt {
45 /**
46 * @var string this is a magic value that question types can return from
47 * {@link question_definition::get_expected_data()}.
48 */
49 const USE_RAW_DATA = 'use raw data';
50
51 /**
b2694c02
TH
52 * @var string Should not longer be used.
53 * @deprecated since Moodle 3.0
dcd03928 54 */
b2694c02 55 const PARAM_MARK = PARAM_RAW_TRIMMED;
dcd03928
TH
56
57 /**
58 * @var string special value to indicate a response variable that is uploaded
59 * files.
60 */
61 const PARAM_FILES = 'paramfiles';
62
63 /**
64 * @var string special value to indicate a response variable that is uploaded
65 * files.
66 */
2d2018ab 67 const PARAM_RAW_FILES = 'paramrawfiles';
dcd03928 68
99caa248
JP
69 /**
70 * @var string means first try at a question during an attempt by a user.
71 */
72 const FIRST_TRY = 'firsttry';
73
74 /**
75 * @var string means last try at a question during an attempt by a user.
76 */
77 const LAST_TRY = 'lasttry';
78
79 /**
80 * @var string means all tries at a question during an attempt by a user.
81 */
82 const ALL_TRIES = 'alltries';
83
dcd03928
TH
84 /** @var integer if this attempts is stored in the question_attempts table, the id of that row. */
85 protected $id = null;
86
87 /** @var integer|string the id of the question_usage_by_activity we belong to. */
88 protected $usageid;
89
90 /** @var integer the number used to identify this question_attempt within the usage. */
91 protected $slot = null;
92
93 /**
94 * @var question_behaviour the behaviour controlling this attempt.
95 * null until {@link start()} is called.
96 */
97 protected $behaviour = null;
98
99 /** @var question_definition the question this is an attempt at. */
100 protected $question;
101
1da821bb
TH
102 /** @var int which variant of the question to use. */
103 protected $variant;
104
4e3d8293
TH
105 /**
106 * @var float the maximum mark that can be scored at this question.
107 * Actually, this is only really a nominal maximum. It might be better thought
108 * of as the question weight.
109 */
dcd03928
TH
110 protected $maxmark;
111
112 /**
4e3d8293 113 * @var float the minimum fraction that can be scored at this question, so
dcd03928
TH
114 * the minimum mark is $this->minfraction * $this->maxmark.
115 */
116 protected $minfraction = null;
117
4e3d8293
TH
118 /**
119 * @var float the maximum fraction that can be scored at this question, so
120 * the maximum mark is $this->maxfraction * $this->maxmark.
121 */
122 protected $maxfraction = null;
123
dcd03928
TH
124 /**
125 * @var string plain text summary of the variant of the question the
126 * student saw. Intended for reporting purposes.
127 */
128 protected $questionsummary = null;
129
130 /**
131 * @var string plain text summary of the response the student gave.
132 * Intended for reporting purposes.
133 */
134 protected $responsesummary = null;
135
6c91e515
TH
136 /**
137 * @var int last modified time.
138 */
139 public $timemodified = null;
140
dcd03928
TH
141 /**
142 * @var string plain text summary of the correct response to this question
143 * variant the student saw. The format should be similar to responsesummary.
144 * Intended for reporting purposes.
145 */
146 protected $rightanswer = null;
147
148 /** @var array of {@link question_attempt_step}s. The steps in this attempt. */
149 protected $steps = array();
150
0a606a2b
TH
151 /**
152 * @var question_attempt_step if, when we loaded the step from the DB, there was
153 * an autosaved step, we save a pointer to it here. (It is also added to the $steps array.)
154 */
155 protected $autosavedstep = null;
156
dcd03928
TH
157 /** @var boolean whether the user has flagged this attempt within the usage. */
158 protected $flagged = false;
159
160 /** @var question_usage_observer tracks changes to the useage this attempt is part of.*/
161 protected $observer;
162
163 /**#@+
164 * Constants used by the intereaction models to indicate whether the current
165 * pending step should be kept or discarded.
166 */
167 const KEEP = true;
168 const DISCARD = false;
169 /**#@-*/
170
171 /**
172 * Create a new {@link question_attempt}. Normally you should create question_attempts
173 * indirectly, by calling {@link question_usage_by_activity::add_question()}.
174 *
175 * @param question_definition $question the question this is an attempt at.
176 * @param int|string $usageid The id of the
177 * {@link question_usage_by_activity} we belong to. Used by {@link get_field_prefix()}.
178 * @param question_usage_observer $observer tracks changes to the useage this
179 * attempt is part of. (Optional, a {@link question_usage_null_observer} is
180 * used if one is not passed.
181 * @param number $maxmark the maximum grade for this question_attempt. If not
182 * passed, $question->defaultmark is used.
183 */
184 public function __construct(question_definition $question, $usageid,
185 question_usage_observer $observer = null, $maxmark = null) {
186 $this->question = $question;
187 $this->usageid = $usageid;
188 if (is_null($observer)) {
189 $observer = new question_usage_null_observer();
190 }
191 $this->observer = $observer;
192 if (!is_null($maxmark)) {
193 $this->maxmark = $maxmark;
194 } else {
195 $this->maxmark = $question->defaultmark;
196 }
197 }
198
f123d67f
TH
199 /**
200 * This method exists so that {@link question_attempt_with_restricted_history}
201 * can override it. You should not normally need to call it.
202 * @return question_attempt return ourself.
203 */
204 public function get_full_qa() {
205 return $this;
206 }
207
dcd03928
TH
208 /** @return question_definition the question this is an attempt at. */
209 public function get_question() {
210 return $this->question;
211 }
212
1da821bb
TH
213 /**
214 * Get the variant of the question being used in a given slot.
215 * @return int the variant number.
216 */
217 public function get_variant() {
218 return $this->variant;
219 }
220
dcd03928
TH
221 /**
222 * Set the number used to identify this question_attempt within the usage.
223 * For internal use only.
224 * @param int $slot
225 */
94815ccf 226 public function set_slot($slot) {
dcd03928
TH
227 $this->slot = $slot;
228 }
229
230 /** @return int the number used to identify this question_attempt within the usage. */
231 public function get_slot() {
232 return $this->slot;
233 }
234
235 /**
236 * @return int the id of row for this question_attempt, if it is stored in the
237 * database. null if not.
238 */
239 public function get_database_id() {
240 return $this->id;
241 }
242
243 /**
244 * For internal use only. Set the id of the corresponding database row.
245 * @param int $id the id of row for this question_attempt, if it is
246 * stored in the database.
247 */
248 public function set_database_id($id) {
249 $this->id = $id;
250 }
251
94815ccf
TH
252 /**
253 * You should almost certainly not call this method from your code. It is for
254 * internal use only.
255 * @param question_usage_observer that should be used to tracking changes made to this qa.
256 */
257 public function set_observer($observer) {
258 $this->observer = $observer;
259 }
260
dcd03928
TH
261 /** @return int|string the id of the {@link question_usage_by_activity} we belong to. */
262 public function get_usage_id() {
263 return $this->usageid;
264 }
265
266 /**
267 * Set the id of the {@link question_usage_by_activity} we belong to.
268 * For internal use only.
269 * @param int|string the new id.
270 */
271 public function set_usage_id($usageid) {
272 $this->usageid = $usageid;
273 }
274
275 /** @return string the name of the behaviour that is controlling this attempt. */
276 public function get_behaviour_name() {
277 return $this->behaviour->get_name();
278 }
279
280 /**
281 * For internal use only.
282 * @return question_behaviour the behaviour that is controlling this attempt.
283 */
284 public function get_behaviour() {
285 return $this->behaviour;
286 }
287
288 /**
289 * Set the flagged state of this question.
290 * @param bool $flagged the new state.
291 */
292 public function set_flagged($flagged) {
293 $this->flagged = $flagged;
294 $this->observer->notify_attempt_modified($this);
295 }
296
297 /** @return bool whether this question is currently flagged. */
298 public function is_flagged() {
299 return $this->flagged;
300 }
301
302 /**
303 * Get the name (in the sense a HTML name="" attribute, or a $_POST variable
304 * name) to use for the field that indicates whether this question is flagged.
305 *
6c91e515 306 * @return string The field name to use.
dcd03928
TH
307 */
308 public function get_flag_field_name() {
309 return $this->get_control_field_name('flagged');
310 }
311
312 /**
313 * Get the name (in the sense a HTML name="" attribute, or a $_POST variable
314 * name) to use for a question_type variable belonging to this question_attempt.
315 *
316 * See the comment on {@link question_attempt_step} for an explanation of
317 * question type and behaviour variables.
318 *
6c91e515
TH
319 * @param string $varname The short form of the variable name.
320 * @return string The field name to use.
dcd03928
TH
321 */
322 public function get_qt_field_name($varname) {
323 return $this->get_field_prefix() . $varname;
324 }
325
326 /**
327 * Get the name (in the sense a HTML name="" attribute, or a $_POST variable
328 * name) to use for a question_type variable belonging to this question_attempt.
329 *
330 * See the comment on {@link question_attempt_step} for an explanation of
331 * question type and behaviour variables.
332 *
6c91e515
TH
333 * @param string $varname The short form of the variable name.
334 * @return string The field name to use.
dcd03928
TH
335 */
336 public function get_behaviour_field_name($varname) {
337 return $this->get_field_prefix() . '-' . $varname;
338 }
339
340 /**
341 * Get the name (in the sense a HTML name="" attribute, or a $_POST variable
342 * name) to use for a control variables belonging to this question_attempt.
343 *
344 * Examples are :sequencecheck and :flagged
345 *
6c91e515
TH
346 * @param string $varname The short form of the variable name.
347 * @return string The field name to use.
dcd03928
TH
348 */
349 public function get_control_field_name($varname) {
350 return $this->get_field_prefix() . ':' . $varname;
351 }
352
353 /**
354 * Get the prefix added to variable names to give field names for this
355 * question attempt.
356 *
357 * You should not use this method directly. This is an implementation detail
358 * anyway, but if you must access it, use {@link question_usage_by_activity::get_field_prefix()}.
359 *
6c91e515 360 * @return string The field name to use.
dcd03928
TH
361 */
362 public function get_field_prefix() {
363 return 'q' . $this->usageid . ':' . $this->slot . '_';
364 }
365
f1ffd134
TH
366 /**
367 * When the question is rendered, this unique id is added to the
368 * outer div of the question. It can be used to uniquely reference
369 * the question from JavaScript.
370 *
371 * @return string id added to the outer <div class="que ..."> when the question is rendered.
372 */
373 public function get_outer_question_div_unique_id() {
374 return 'question-' . $this->usageid . '-' . $this->slot;
375 }
376
dcd03928
TH
377 /**
378 * Get one of the steps in this attempt.
99caa248 379 *
f6579bea 380 * @param int $i the step number, which counts from 0.
dcd03928
TH
381 * @return question_attempt_step
382 */
383 public function get_step($i) {
384 if ($i < 0 || $i >= count($this->steps)) {
385 throw new coding_exception('Index out of bounds in question_attempt::get_step.');
386 }
387 return $this->steps[$i];
388 }
389
c7fbfe46
TH
390 /**
391 * Get the number of real steps in this attempt.
392 * This is put as a hidden field in the HTML, so that when we receive some
393 * data to process, then we can check that it came from the question
394 * in the state we are now it.
395 * @return int a number that summarises the current state of this question attempt.
396 */
397 public function get_sequence_check_count() {
398 $numrealsteps = $this->get_num_steps();
399 if ($this->has_autosaved_step()) {
400 $numrealsteps -= 1;
401 }
402 return $numrealsteps;
403 }
404
dcd03928
TH
405 /**
406 * Get the number of steps in this attempt.
407 * For internal/test code use only.
408 * @return int the number of steps we currently have.
409 */
410 public function get_num_steps() {
411 return count($this->steps);
412 }
413
414 /**
415 * Return the latest step in this question_attempt.
416 * For internal/test code use only.
417 * @return question_attempt_step
418 */
419 public function get_last_step() {
420 if (count($this->steps) == 0) {
421 return new question_null_step();
422 }
423 return end($this->steps);
424 }
425
0a606a2b
TH
426 /**
427 * @return boolean whether this question_attempt has autosaved data from
428 * some time in the past.
429 */
430 public function has_autosaved_step() {
431 return !is_null($this->autosavedstep);
432 }
433
dcd03928
TH
434 /**
435 * @return question_attempt_step_iterator for iterating over the steps in
436 * this attempt, in order.
437 */
438 public function get_step_iterator() {
439 return new question_attempt_step_iterator($this);
440 }
441
442 /**
443 * The same as {@link get_step_iterator()}. However, for a
444 * {@link question_attempt_with_restricted_history} this returns the full
445 * list of steps, while {@link get_step_iterator()} returns only the
446 * limited history.
447 * @return question_attempt_step_iterator for iterating over the steps in
448 * this attempt, in order.
449 */
450 public function get_full_step_iterator() {
451 return $this->get_step_iterator();
452 }
453
454 /**
455 * @return question_attempt_reverse_step_iterator for iterating over the steps in
456 * this attempt, in reverse order.
457 */
458 public function get_reverse_step_iterator() {
459 return new question_attempt_reverse_step_iterator($this);
460 }
461
462 /**
463 * Get the qt data from the latest step that has any qt data. Return $default
464 * array if it is no step has qt data.
465 *
dcd03928
TH
466 * @param mixed default the value to return no step has qt data.
467 * (Optional, defaults to an empty array.)
468 * @return array|mixed the data, or $default if there is not any.
469 */
470 public function get_last_qt_data($default = array()) {
471 foreach ($this->get_reverse_step_iterator() as $step) {
472 $response = $step->get_qt_data();
473 if (!empty($response)) {
474 return $response;
475 }
476 }
477 return $default;
478 }
479
480 /**
481 * Get the last step with a particular question type varialbe set.
482 * @param string $name the name of the variable to get.
483 * @return question_attempt_step the last step, or a step with no variables
484 * if there was not a real step.
485 */
486 public function get_last_step_with_qt_var($name) {
487 foreach ($this->get_reverse_step_iterator() as $step) {
488 if ($step->has_qt_var($name)) {
489 return $step;
490 }
cc9fc649
HB
491 }
492 return new question_attempt_step_read_only();
493 }
494
495 /**
496 * Get the last step with a particular behaviour variable set.
497 * @param string $name the name of the variable to get.
498 * @return question_attempt_step the last step, or a step with no variables
499 * if there was not a real step.
500 */
501 public function get_last_step_with_behaviour_var($name) {
502 foreach ($this->get_reverse_step_iterator() as $step) {
503 if ($step->has_behaviour_var($name)) {
504 return $step;
505 }
dcd03928
TH
506 }
507 return new question_attempt_step_read_only();
508 }
509
510 /**
511 * Get the latest value of a particular question type variable. That is, get
512 * the value from the latest step that has it set. Return null if it is not
513 * set in any step.
514 *
515 * @param string $name the name of the variable to get.
516 * @param mixed default the value to return in the variable has never been set.
517 * (Optional, defaults to null.)
518 * @return mixed string value, or $default if it has never been set.
519 */
520 public function get_last_qt_var($name, $default = null) {
521 $step = $this->get_last_step_with_qt_var($name);
522 if ($step->has_qt_var($name)) {
523 return $step->get_qt_var($name);
524 } else {
525 return $default;
526 }
527 }
528
529 /**
530 * Get the latest set of files for a particular question type variable of
531 * type question_attempt::PARAM_FILES.
532 *
533 * @param string $name the name of the associated variable.
6c91e515 534 * @param int $contextid the context to which the files are linked.
dcd03928
TH
535 * @return array of {@link stored_files}.
536 */
537 public function get_last_qt_files($name, $contextid) {
538 foreach ($this->get_reverse_step_iterator() as $step) {
539 if ($step->has_qt_var($name)) {
540 return $step->get_qt_files($name, $contextid);
541 }
542 }
543 return array();
544 }
545
546 /**
547 * Get the URL of a file that belongs to a response variable of this
548 * question_attempt.
549 * @param stored_file $file the file to link to.
550 * @return string the URL of that file.
551 */
552 public function get_response_file_url(stored_file $file) {
553 return file_encode_url(new moodle_url('/pluginfile.php'), '/' . implode('/', array(
554 $file->get_contextid(),
555 $file->get_component(),
556 $file->get_filearea(),
557 $this->usageid,
558 $this->slot,
559 $file->get_itemid())) .
560 $file->get_filepath() . $file->get_filename(), true);
561 }
562
563 /**
564 * Prepare a draft file are for the files belonging the a response variable
565 * of this question attempt. The draft area is populated with the files from
566 * the most recent step having files.
567 *
568 * @param string $name the variable name the files belong to.
569 * @param int $contextid the id of the context the quba belongs to.
570 * @return int the draft itemid.
571 */
572 public function prepare_response_files_draft_itemid($name, $contextid) {
573 foreach ($this->get_reverse_step_iterator() as $step) {
574 if ($step->has_qt_var($name)) {
575 return $step->prepare_response_files_draft_itemid($name, $contextid);
576 }
577 }
578
579 // No files yet.
580 $draftid = 0; // Will be filled in by file_prepare_draft_area.
581 file_prepare_draft_area($draftid, $contextid, 'question', 'response_' . $name, null);
582 return $draftid;
583 }
584
585 /**
586 * Get the latest value of a particular behaviour variable. That is,
587 * get the value from the latest step that has it set. Return null if it is
588 * not set in any step.
589 *
590 * @param string $name the name of the variable to get.
591 * @param mixed default the value to return in the variable has never been set.
592 * (Optional, defaults to null.)
593 * @return mixed string value, or $default if it has never been set.
594 */
595 public function get_last_behaviour_var($name, $default = null) {
596 foreach ($this->get_reverse_step_iterator() as $step) {
597 if ($step->has_behaviour_var($name)) {
598 return $step->get_behaviour_var($name);
599 }
600 }
601 return $default;
602 }
603
604 /**
605 * Get the current state of this question attempt. That is, the state of the
606 * latest step.
607 * @return question_state
608 */
609 public function get_state() {
610 return $this->get_last_step()->get_state();
611 }
612
613 /**
614 * @param bool $showcorrectness Whether right/partial/wrong states should
615 * be distinguised.
616 * @return string A brief textual description of the current state.
617 */
618 public function get_state_string($showcorrectness) {
f8e28244
RK
619 // Special case when attempt is based on previous one, see MDL-31226.
620 if ($this->get_num_steps() == 1 && $this->get_state() == question_state::$complete) {
621 return get_string('notchanged', 'question');
622 }
dcd03928
TH
623 return $this->behaviour->get_state_string($showcorrectness);
624 }
625
97cdc1de
TH
626 /**
627 * @param bool $showcorrectness Whether right/partial/wrong states should
628 * be distinguised.
629 * @return string a CSS class name for the current state.
630 */
631 public function get_state_class($showcorrectness) {
632 return $this->get_state()->get_state_class($showcorrectness);
633 }
634
dcd03928
TH
635 /**
636 * @return int the timestamp of the most recent step in this question attempt.
637 */
638 public function get_last_action_time() {
639 return $this->get_last_step()->get_timecreated();
640 }
641
642 /**
643 * Get the current fraction of this question attempt. That is, the fraction
644 * of the latest step, or null if this question has not yet been graded.
645 * @return number the current fraction.
646 */
647 public function get_fraction() {
648 return $this->get_last_step()->get_fraction();
649 }
650
651 /** @return bool whether this question attempt has a non-zero maximum mark. */
652 public function has_marks() {
653 // Since grades are stored in the database as NUMBER(12,7).
654 return $this->maxmark >= 0.00000005;
655 }
656
657 /**
658 * @return number the current mark for this question.
659 * {@link get_fraction()} * {@link get_max_mark()}.
660 */
661 public function get_mark() {
662 return $this->fraction_to_mark($this->get_fraction());
663 }
664
665 /**
666 * This is used by the manual grading code, particularly in association with
808b6883
TH
667 * validation. It gets the current manual mark for a question, in exactly the string
668 * form that the teacher entered it, if possible. This may come from the current
669 * POST request, if there is one, otherwise from the database.
670 *
671 * @return string the current manual mark for this question, in the format the teacher typed,
672 * if possible.
dcd03928
TH
673 */
674 public function get_current_manual_mark() {
808b6883 675 // Is there a current value in the current POST data? If so, use that.
b2694c02 676 $mark = $this->get_submitted_var($this->get_behaviour_field_name('mark'), PARAM_RAW_TRIMMED);
808b6883 677 if ($mark !== null) {
dcd03928
TH
678 return $mark;
679 }
808b6883
TH
680
681 // Otherwise, use the stored value.
682 // If the question max mark has not changed, use the stored value that was input.
683 $storedmaxmark = $this->get_last_behaviour_var('maxmark');
684 if ($storedmaxmark !== null && ($storedmaxmark - $this->get_max_mark()) < 0.0000005) {
685 return $this->get_last_behaviour_var('mark');
686 }
687
688 // The max mark for this question has changed so we must re-scale the current mark.
689 return format_float($this->get_mark(), 7, true, true);
dcd03928
TH
690 }
691
692 /**
693 * @param number|null $fraction a fraction.
694 * @return number|null the corresponding mark.
695 */
696 public function fraction_to_mark($fraction) {
697 if (is_null($fraction)) {
698 return null;
699 }
700 return $fraction * $this->maxmark;
701 }
702
4e3d8293
TH
703 /**
704 * @return float the maximum mark possible for this question attempt.
705 * In fact, this is not strictly the maximum, becuase get_max_fraction may
706 * return a number greater than 1. It might be better to think of this as a
707 * question weight.
708 */
dcd03928
TH
709 public function get_max_mark() {
710 return $this->maxmark;
711 }
712
4e3d8293 713 /** @return float the maximum mark possible for this question attempt. */
dcd03928
TH
714 public function get_min_fraction() {
715 if (is_null($this->minfraction)) {
4e3d8293 716 throw new coding_exception('This question_attempt has not been started yet, the min fraction is not yet known.');
dcd03928
TH
717 }
718 return $this->minfraction;
719 }
720
4e3d8293
TH
721 /** @return float the maximum mark possible for this question attempt. */
722 public function get_max_fraction() {
723 if (is_null($this->maxfraction)) {
724 throw new coding_exception('This question_attempt has not been started yet, the max fraction is not yet known.');
725 }
726 return $this->maxfraction;
727 }
728
dcd03928
TH
729 /**
730 * The current mark, formatted to the stated number of decimal places. Uses
731 * {@link format_float()} to format floats according to the current locale.
732 * @param int $dp number of decimal places.
733 * @return string formatted mark.
734 */
735 public function format_mark($dp) {
736 return $this->format_fraction_as_mark($this->get_fraction(), $dp);
737 }
738
739 /**
6c91e515 740 * The a mark, formatted to the stated number of decimal places. Uses
dcd03928 741 * {@link format_float()} to format floats according to the current locale.
6c91e515
TH
742 *
743 * @param number $fraction a fraction.
dcd03928
TH
744 * @param int $dp number of decimal places.
745 * @return string formatted mark.
746 */
747 public function format_fraction_as_mark($fraction, $dp) {
748 return format_float($this->fraction_to_mark($fraction), $dp);
749 }
750
751 /**
752 * The maximum mark for this question attempt, formatted to the stated number
753 * of decimal places. Uses {@link format_float()} to format floats according
754 * to the current locale.
755 * @param int $dp number of decimal places.
756 * @return string formatted maximum mark.
757 */
758 public function format_max_mark($dp) {
759 return format_float($this->maxmark, $dp);
760 }
761
762 /**
763 * Return the hint that applies to the question in its current state, or null.
764 * @return question_hint|null
765 */
766 public function get_applicable_hint() {
767 return $this->behaviour->get_applicable_hint();
768 }
769
770 /**
771 * Produce a plain-text summary of what the user did during a step.
772 * @param question_attempt_step $step the step in quetsion.
773 * @return string a summary of what was done during that step.
774 */
775 public function summarise_action(question_attempt_step $step) {
776 return $this->behaviour->summarise_action($step);
777 }
778
f6579bea
TH
779 /**
780 * Return one of the bits of metadata for a this question attempt.
781 * @param string $name the name of the metadata variable to return.
782 * @return string the value of that metadata variable.
783 */
784 public function get_metadata($name) {
785 return $this->get_step(0)->get_metadata_var($name);
786 }
787
788 /**
789 * Set some metadata for this question attempt.
790 * @param string $name the name of the metadata variable to return.
791 * @param string $value the value to set that metadata variable to.
792 */
793 public function set_metadata($name, $value) {
794 $firststep = $this->get_step(0);
795 if (!$firststep->has_metadata_var($name)) {
796 $this->observer->notify_metadata_added($this, $name);
797 } else if ($value !== $firststep->get_metadata_var($name)) {
798 $this->observer->notify_metadata_modified($this, $name);
799 }
800 $firststep->set_metadata_var($name, $value);
801 }
802
dcd03928
TH
803 /**
804 * Helper function used by {@link rewrite_pluginfile_urls()} and
805 * {@link rewrite_response_pluginfile_urls()}.
806 * @return array ids that need to go into the file paths.
807 */
808 protected function extra_file_path_components() {
809 return array($this->get_usage_id(), $this->get_slot());
810 }
811
812 /**
813 * Calls {@link question_rewrite_question_urls()} with appropriate parameters
814 * for content belonging to this question.
815 * @param string $text the content to output.
816 * @param string $component the component name (normally 'question' or 'qtype_...')
817 * @param string $filearea the name of the file area.
818 * @param int $itemid the item id.
6c91e515 819 * @return string the content with the URLs rewritten.
dcd03928
TH
820 */
821 public function rewrite_pluginfile_urls($text, $component, $filearea, $itemid) {
822 return question_rewrite_question_urls($text, 'pluginfile.php',
823 $this->question->contextid, $component, $filearea,
824 $this->extra_file_path_components(), $itemid);
825 }
826
827 /**
828 * Calls {@link question_rewrite_question_urls()} with appropriate parameters
829 * for content belonging to responses to this question.
830 *
831 * @param string $text the text to update the URLs in.
832 * @param int $contextid the id of the context the quba belongs to.
833 * @param string $name the variable name the files belong to.
834 * @param question_attempt_step $step the step the response is coming from.
6c91e515 835 * @return string the content with the URLs rewritten.
dcd03928
TH
836 */
837 public function rewrite_response_pluginfile_urls($text, $contextid, $name,
838 question_attempt_step $step) {
839 return $step->rewrite_response_pluginfile_urls($text, $contextid, $name,
840 $this->extra_file_path_components());
841 }
842
843 /**
844 * Get the {@link core_question_renderer}, in collaboration with appropriate
845 * {@link qbehaviour_renderer} and {@link qtype_renderer} subclasses, to generate the
846 * HTML to display this question attempt in its current state.
6c91e515 847 *
dcd03928
TH
848 * @param question_display_options $options controls how the question is rendered.
849 * @param string|null $number The question number to display.
6c91e515
TH
850 * @param moodle_page|null $page the page the question is being redered to.
851 * (Optional. Defaults to $PAGE.)
dcd03928
TH
852 * @return string HTML fragment representing the question.
853 */
854 public function render($options, $number, $page = null) {
855 if (is_null($page)) {
856 global $PAGE;
857 $page = $PAGE;
858 }
859 $qoutput = $page->get_renderer('core', 'question');
860 $qtoutput = $this->question->get_renderer($page);
861 return $this->behaviour->render($options, $number, $qoutput, $qtoutput);
862 }
863
864 /**
865 * Generate any bits of HTML that needs to go in the <head> tag when this question
866 * attempt is displayed in the body.
867 * @return string HTML fragment.
868 */
869 public function render_head_html($page = null) {
870 if (is_null($page)) {
871 global $PAGE;
872 $page = $PAGE;
873 }
874 // TODO go via behaviour.
875 return $this->question->get_renderer($page)->head_code($this) .
876 $this->behaviour->get_renderer($page)->head_code($this);
877 }
878
879 /**
880 * Like {@link render_question()} but displays the question at the past step
881 * indicated by $seq, rather than showing the latest step.
882 *
883 * @param int $seq the seq number of the past state to display.
884 * @param question_display_options $options controls how the question is rendered.
885 * @param string|null $number The question number to display. 'i' is a special
886 * value that gets displayed as Information. Null means no number is displayed.
6c91e515
TH
887 * @param string $preferredbehaviour the preferred behaviour. It is slightly
888 * annoying that this needs to be passed, but unavoidable for now.
dcd03928
TH
889 * @return string HTML fragment representing the question.
890 */
891 public function render_at_step($seq, $options, $number, $preferredbehaviour) {
892 $restrictedqa = new question_attempt_with_restricted_history($this, $seq, $preferredbehaviour);
893 return $restrictedqa->render($options, $number);
894 }
895
896 /**
897 * Checks whether the users is allow to be served a particular file.
898 * @param question_display_options $options the options that control display of the question.
899 * @param string $component the name of the component we are serving files for.
900 * @param string $filearea the name of the file area.
901 * @param array $args the remaining bits of the file path.
902 * @param bool $forcedownload whether the user must be forced to download the file.
903 * @return bool true if the user can access this file.
904 */
905 public function check_file_access($options, $component, $filearea, $args, $forcedownload) {
906 return $this->behaviour->check_file_access($options, $component, $filearea, $args, $forcedownload);
907 }
908
909 /**
910 * Add a step to this question attempt.
911 * @param question_attempt_step $step the new step.
912 */
913 protected function add_step(question_attempt_step $step) {
914 $this->steps[] = $step;
915 end($this->steps);
916 $this->observer->notify_step_added($step, $this, key($this->steps));
917 }
918
0a606a2b
TH
919 /**
920 * Add an auto-saved step to this question attempt. We mark auto-saved steps by
921 * changing saving the step number with a - sign.
922 * @param question_attempt_step $step the new step.
923 */
924 protected function add_autosaved_step(question_attempt_step $step) {
925 $this->steps[] = $step;
926 $this->autosavedstep = $step;
927 end($this->steps);
928 $this->observer->notify_step_added($step, $this, -key($this->steps));
929 }
930
931 /**
932 * Discard any auto-saved data belonging to this question attempt.
933 */
934 public function discard_autosaved_step() {
935 if (!$this->has_autosaved_step()) {
936 return;
937 }
938
939 $autosaved = array_pop($this->steps);
940 $this->autosavedstep = null;
941 $this->observer->notify_step_deleted($autosaved, $this);
942 }
943
3d96b494
TH
944 /**
945 * If there is an autosaved step, convert it into a real save, so that it
946 * is preserved.
947 */
948 protected function convert_autosaved_step_to_real_step() {
949 if ($this->autosavedstep === null) {
950 return;
951 }
952
953 $laststep = end($this->steps);
954 if ($laststep !== $this->autosavedstep) {
955 throw new coding_exception('Cannot convert autosaved step to real step, since other steps have been added.');
956 }
957
958 $this->observer->notify_step_modified($this->autosavedstep, $this, key($this->steps));
959 $this->autosavedstep = null;
960 }
961
1da821bb
TH
962 /**
963 * Use a strategy to pick a variant.
964 * @param question_variant_selection_strategy $variantstrategy a strategy.
965 * @return int the selected variant.
966 */
967 public function select_variant(question_variant_selection_strategy $variantstrategy) {
968 return $variantstrategy->choose_variant($this->get_question()->get_num_variants(),
969 $this->get_question()->get_variants_selection_seed());
970 }
971
dcd03928
TH
972 /**
973 * Start this question attempt.
974 *
975 * You should not call this method directly. Call
976 * {@link question_usage_by_activity::start_question()} instead.
977 *
978 * @param string|question_behaviour $preferredbehaviour the name of the
979 * desired archetypal behaviour, or an actual model instance.
1da821bb
TH
980 * @param int $variant the variant of the question to start. Between 1 and
981 * $this->get_question()->get_num_variants() inclusive.
dcd03928
TH
982 * @param array $submitteddata optional, used when re-starting to keep the same initial state.
983 * @param int $timestamp optional, the timstamp to record for this action. Defaults to now.
984 * @param int $userid optional, the user to attribute this action to. Defaults to the current user.
94815ccf
TH
985 * @param int $existingstepid optional, if this step is going to replace an existing step
986 * (for example, during a regrade) this is the id of the previous step we are replacing.
dcd03928 987 */
1da821bb 988 public function start($preferredbehaviour, $variant, $submitteddata = array(),
94815ccf 989 $timestamp = null, $userid = null, $existingstepid = null) {
1da821bb 990
f6579bea
TH
991 if ($this->get_num_steps() > 0) {
992 throw new coding_exception('Cannot start a question that is already started.');
993 }
994
dcd03928 995 // Initialise the behaviour.
1da821bb 996 $this->variant = $variant;
dcd03928
TH
997 if (is_string($preferredbehaviour)) {
998 $this->behaviour =
999 $this->question->make_behaviour($this, $preferredbehaviour);
1000 } else {
1001 $class = get_class($preferredbehaviour);
1002 $this->behaviour = new $class($this, $preferredbehaviour);
1003 }
1004
4e3d8293 1005 // Record the minimum and maximum fractions.
dcd03928 1006 $this->minfraction = $this->behaviour->get_min_fraction();
4e3d8293 1007 $this->maxfraction = $this->behaviour->get_max_fraction();
dcd03928
TH
1008
1009 // Initialise the first step.
94815ccf 1010 $firststep = new question_attempt_step($submitteddata, $timestamp, $userid, $existingstepid);
dcd03928 1011 if ($submitteddata) {
f8e28244
RK
1012 $firststep->set_state(question_state::$complete);
1013 $this->behaviour->apply_attempt_state($firststep);
dcd03928 1014 } else {
1da821bb 1015 $this->behaviour->init_first_step($firststep, $variant);
dcd03928
TH
1016 }
1017 $this->add_step($firststep);
1018
1019 // Record questionline and correct answer.
1020 $this->questionsummary = $this->behaviour->get_question_summary();
1021 $this->rightanswer = $this->behaviour->get_right_answer_summary();
1022 }
1023
1024 /**
1025 * Start this question attempt, starting from the point that the previous
1026 * attempt $oldqa had reached.
1027 *
1028 * You should not call this method directly. Call
1029 * {@link question_usage_by_activity::start_question_based_on()} instead.
1030 *
1031 * @param question_attempt $oldqa a previous attempt at this quetsion that
1032 * defines the starting point.
1033 */
1034 public function start_based_on(question_attempt $oldqa) {
1da821bb 1035 $this->start($oldqa->behaviour, $oldqa->get_variant(), $oldqa->get_resume_data());
dcd03928
TH
1036 }
1037
1038 /**
1039 * Used by {@link start_based_on()} to get the data needed to start a new
1040 * attempt from the point this attempt has go to.
1041 * @return array name => value pairs.
1042 */
1043 protected function get_resume_data() {
afb1b3d0
TH
1044 $resumedata = $this->behaviour->get_resume_data();
1045 foreach ($resumedata as $name => $value) {
1046 if ($value instanceof question_file_loader) {
1047 $resumedata[$name] = $value->get_question_file_saver();
1048 }
1049 }
1050 return $resumedata;
dcd03928
TH
1051 }
1052
1053 /**
1054 * Get a particular parameter from the current request. A wrapper round
1055 * {@link optional_param()}, except that the results is returned without
1056 * slashes.
1057 * @param string $name the paramter name.
1058 * @param int $type one of the standard PARAM_... constants, or one of the
1059 * special extra constands defined by this class.
1060 * @param array $postdata (optional, only inteded for testing use) take the
1061 * data from this array, instead of from $_POST.
1062 * @return mixed the requested value.
1063 */
1064 public function get_submitted_var($name, $type, $postdata = null) {
1065 switch ($type) {
dcd03928
TH
1066
1067 case self::PARAM_FILES:
1068 return $this->process_response_files($name, $name, $postdata);
1069
2d2018ab
TH
1070 case self::PARAM_RAW_FILES:
1071 $var = $this->get_submitted_var($name, PARAM_RAW, $postdata);
dcd03928
TH
1072 return $this->process_response_files($name, $name . ':itemid', $postdata, $var);
1073
1074 default:
1075 if (is_null($postdata)) {
1076 $var = optional_param($name, null, $type);
1077 } else if (array_key_exists($name, $postdata)) {
1078 $var = clean_param($postdata[$name], $type);
1079 } else {
1080 $var = null;
1081 }
1082
be492e2a
TH
1083 if ($var !== null) {
1084 // Ensure that, if set, $var is a string. This is because later, after
1085 // it has been saved to the database and loaded back it will be a string,
1086 // so better if the type is predictably always a string.
1087 $var = (string) $var;
1088 }
1089
dcd03928
TH
1090 return $var;
1091 }
1092 }
1093
b2694c02
TH
1094 /**
1095 * Validate the manual mark for a question.
6c91e515 1096 * @param string $currentmark the user input (e.g. '1,0', '1,0' or 'invalid'.
b2694c02
TH
1097 * @return string any errors with the value, or '' if it is OK.
1098 */
1099 public function validate_manual_mark($currentmark) {
1100 if ($currentmark === null || $currentmark === '') {
1101 return '';
1102 }
52b08f5f 1103
b2694c02
TH
1104 $mark = question_utils::clean_param_mark($currentmark);
1105 if ($mark === null) {
1106 return get_string('manualgradeinvalidformat', 'question');
52b08f5f 1107 }
b2694c02 1108
52b08f5f 1109 $maxmark = $this->get_max_mark();
b2694c02
TH
1110 if ($mark > $maxmark * $this->get_max_fraction() || $mark < $maxmark * $this->get_min_fraction()) {
1111 return get_string('manualgradeoutofrange', 'question');
52b08f5f
NM
1112 }
1113
1114 return '';
52b08f5f
NM
1115 }
1116
dcd03928
TH
1117 /**
1118 * Handle a submitted variable representing uploaded files.
1119 * @param string $name the field name.
1120 * @param string $draftidname the field name holding the draft file area id.
1121 * @param array $postdata (optional, only inteded for testing use) take the
1122 * data from this array, instead of from $_POST. At the moment, this
1123 * behaves as if there were no files.
1124 * @param string $text optional reponse text.
1125 * @return question_file_saver that can be used to save the files later.
1126 */
1127 protected function process_response_files($name, $draftidname, $postdata = null, $text = null) {
1128 if ($postdata) {
afb1b3d0
TH
1129 // For simulated posts, get the draft itemid from there.
1130 $draftitemid = $this->get_submitted_var($draftidname, PARAM_INT, $postdata);
1131 } else {
1132 $draftitemid = file_get_submitted_draft_itemid($draftidname);
dcd03928
TH
1133 }
1134
dcd03928
TH
1135 if (!$draftitemid) {
1136 return null;
1137 }
1138
18e1450b
AH
1139 $filearea = str_replace($this->get_field_prefix(), '', $name);
1140 $filearea = str_replace('-', 'bf_', $filearea);
1141 $filearea = 'response_' . $filearea;
1142 return new question_file_saver($draftitemid, 'question', $filearea, $text);
dcd03928
TH
1143 }
1144
1145 /**
1146 * Get any data from the request that matches the list of expected params.
6c91e515 1147 *
dcd03928 1148 * @param array $expected variable name => PARAM_... constant.
6c91e515 1149 * @param null|array $postdata null to use real post data, otherwise an array of data to use.
dcd03928
TH
1150 * @param string $extraprefix '-' or ''.
1151 * @return array name => value.
1152 */
1153 protected function get_expected_data($expected, $postdata, $extraprefix) {
1154 $submitteddata = array();
1155 foreach ($expected as $name => $type) {
1156 $value = $this->get_submitted_var(
1157 $this->get_field_prefix() . $extraprefix . $name, $type, $postdata);
1158 if (!is_null($value)) {
1159 $submitteddata[$extraprefix . $name] = $value;
1160 }
1161 }
1162 return $submitteddata;
1163 }
1164
1165 /**
1166 * Get all the submitted question type data for this question, whithout checking
1167 * that it is valid or cleaning it in any way.
6c91e515
TH
1168 *
1169 * @param null|array $postdata null to use real post data, otherwise an array of data to use.
dcd03928
TH
1170 * @return array name => value.
1171 */
df7d175d 1172 public function get_all_submitted_qt_vars($postdata) {
dcd03928
TH
1173 if (is_null($postdata)) {
1174 $postdata = $_POST;
1175 }
1176
03cefcc9 1177 $pattern = '/^' . preg_quote($this->get_field_prefix(), '/') . '[^-:]/';
dcd03928
TH
1178 $prefixlen = strlen($this->get_field_prefix());
1179
1180 $submitteddata = array();
df7d175d 1181 foreach ($postdata as $name => $value) {
dcd03928
TH
1182 if (preg_match($pattern, $name)) {
1183 $submitteddata[substr($name, $prefixlen)] = $value;
1184 }
1185 }
1186
1187 return $submitteddata;
1188 }
1189
1190 /**
1191 * Get all the sumbitted data belonging to this question attempt from the
1192 * current request.
1193 * @param array $postdata (optional, only inteded for testing use) take the
1194 * data from this array, instead of from $_POST.
1195 * @return array name => value pairs that could be passed to {@link process_action()}.
1196 */
1197 public function get_submitted_data($postdata = null) {
1198 $submitteddata = $this->get_expected_data(
1199 $this->behaviour->get_expected_data(), $postdata, '-');
1200
1201 $expected = $this->behaviour->get_expected_qt_data();
18e1450b
AH
1202 $this->check_qt_var_name_restrictions($expected);
1203
dcd03928
TH
1204 if ($expected === self::USE_RAW_DATA) {
1205 $submitteddata += $this->get_all_submitted_qt_vars($postdata);
1206 } else {
1207 $submitteddata += $this->get_expected_data($expected, $postdata, '');
1208 }
1209 return $submitteddata;
1210 }
1211
18e1450b
AH
1212 /**
1213 * Ensure that no reserved prefixes are being used by installed
1214 * question types.
1215 * @param array $expected An array of question type variables
1216 */
1217 protected function check_qt_var_name_restrictions($expected) {
1218 global $CFG;
1219
802ff4c9 1220 if ($CFG->debugdeveloper && $expected !== self::USE_RAW_DATA) {
18e1450b
AH
1221 foreach ($expected as $key => $value) {
1222 if (strpos($key, 'bf_') !== false) {
1223 debugging('The bf_ prefix is reserved and cannot be used by question types', DEBUG_DEVELOPER);
1224 }
1225 }
1226 }
1227 }
1228
dcd03928
TH
1229 /**
1230 * Get a set of response data for this question attempt that would get the
da22c012
K
1231 * best possible mark. If it is not possible to compute a correct
1232 * response, this method should return null.
1233 * @return array|null name => value pairs that could be passed to {@link process_action()}.
dcd03928
TH
1234 */
1235 public function get_correct_response() {
1236 $response = $this->question->get_correct_response();
da22c012
K
1237 if (is_null($response)) {
1238 return null;
1239 }
dcd03928
TH
1240 $imvars = $this->behaviour->get_correct_response();
1241 foreach ($imvars as $name => $value) {
1242 $response['-' . $name] = $value;
1243 }
1244 return $response;
1245 }
1246
1247 /**
1248 * Change the quetsion summary. Note, that this is almost never necessary.
1249 * This method was only added to work around a limitation of the Opaque
1250 * protocol, which only sends questionLine at the end of an attempt.
6c91e515 1251 * @param string $questionsummary the new summary to set.
dcd03928
TH
1252 */
1253 public function set_question_summary($questionsummary) {
1254 $this->questionsummary = $questionsummary;
1255 $this->observer->notify_attempt_modified($this);
1256 }
1257
1258 /**
1259 * @return string a simple textual summary of the question that was asked.
1260 */
1261 public function get_question_summary() {
1262 return $this->questionsummary;
1263 }
1264
1265 /**
1266 * @return string a simple textual summary of response given.
1267 */
1268 public function get_response_summary() {
1269 return $this->responsesummary;
1270 }
1271
1272 /**
1273 * @return string a simple textual summary of the correct resonse.
1274 */
1275 public function get_right_answer_summary() {
1276 return $this->rightanswer;
1277 }
1278
fd7a8af5
TH
1279 /**
1280 * Whether this attempt at this question could be completed just by the
1281 * student interacting with the question, before {@link finish()} is called.
1282 *
1283 * @return boolean whether this attempt can finish naturally.
1284 */
1285 public function can_finish_during_attempt() {
1286 return $this->behaviour->can_finish_during_attempt();
1287 }
1288
dcd03928
TH
1289 /**
1290 * Perform the action described by $submitteddata.
1291 * @param array $submitteddata the submitted data the determines the action.
1292 * @param int $timestamp the time to record for the action. (If not given, use now.)
0a606a2b
TH
1293 * @param int $userid the user to attribute the action to. (If not given, use the current user.)
1294 * @param int $existingstepid used by the regrade code.
dcd03928 1295 */
94815ccf
TH
1296 public function process_action($submitteddata, $timestamp = null, $userid = null, $existingstepid = null) {
1297 $pendingstep = new question_attempt_pending_step($submitteddata, $timestamp, $userid, $existingstepid);
0a606a2b 1298 $this->discard_autosaved_step();
dcd03928
TH
1299 if ($this->behaviour->process_action($pendingstep) == self::KEEP) {
1300 $this->add_step($pendingstep);
1301 if ($pendingstep->response_summary_changed()) {
1302 $this->responsesummary = $pendingstep->get_new_response_summary();
1303 }
a8de8667
TH
1304 if ($pendingstep->variant_number_changed()) {
1305 $this->variant = $pendingstep->get_new_variant_number();
1306 }
dcd03928
TH
1307 }
1308 }
1309
0a606a2b
TH
1310 /**
1311 * Process an autosave.
1312 * @param array $submitteddata the submitted data the determines the action.
1313 * @param int $timestamp the time to record for the action. (If not given, use now.)
1314 * @param int $userid the user to attribute the action to. (If not given, use the current user.)
1315 * @return bool whether anything was saved.
1316 */
1317 public function process_autosave($submitteddata, $timestamp = null, $userid = null) {
1318 $pendingstep = new question_attempt_pending_step($submitteddata, $timestamp, $userid);
1319 if ($this->behaviour->process_autosave($pendingstep) == self::KEEP) {
1320 $this->add_autosaved_step($pendingstep);
1321 return true;
1322 }
1323 return false;
1324 }
1325
dcd03928
TH
1326 /**
1327 * Perform a finish action on this question attempt. This corresponds to an
1328 * external finish action, for example the user pressing Submit all and finish
1329 * in the quiz, rather than using one of the controls that is part of the
1330 * question.
1331 *
1332 * @param int $timestamp the time to record for the action. (If not given, use now.)
1333 * @param int $userid the user to attribute the aciton to. (If not given, use the current user.)
1334 */
1335 public function finish($timestamp = null, $userid = null) {
3d96b494 1336 $this->convert_autosaved_step_to_real_step();
dcd03928
TH
1337 $this->process_action(array('-finish' => 1), $timestamp, $userid);
1338 }
1339
1340 /**
1341 * Perform a regrade. This replays all the actions from $oldqa into this
1342 * attempt.
1343 * @param question_attempt $oldqa the attempt to regrade.
1344 * @param bool $finished whether the question attempt should be forced to be finished
1345 * after the regrade, or whether it may still be in progress (default false).
1346 */
1347 public function regrade(question_attempt $oldqa, $finished) {
1348 $first = true;
1349 foreach ($oldqa->get_step_iterator() as $step) {
94815ccf 1350 $this->observer->notify_step_deleted($step, $this);
9212fe7a 1351
dcd03928 1352 if ($first) {
9212fe7a 1353 // First step of the attempt.
dcd03928 1354 $first = false;
1da821bb 1355 $this->start($oldqa->behaviour, $oldqa->get_variant(), $step->get_all_data(),
94815ccf 1356 $step->get_timecreated(), $step->get_user_id(), $step->get_id());
9212fe7a
TH
1357
1358 } else if ($step->has_behaviour_var('finish') && count($step->get_submitted_data()) > 1) {
1359 // This case relates to MDL-32062. The upgrade code from 2.0
1360 // generates attempts where the final submit of the question
1361 // data, and the finish action, are in the same step. The system
1362 // cannot cope with that, so convert the single old step into
1363 // two new steps.
1364 $submitteddata = $step->get_submitted_data();
1365 unset($submitteddata['-finish']);
1366 $this->process_action($submitteddata,
1367 $step->get_timecreated(), $step->get_user_id(), $step->get_id());
1368 $this->finish($step->get_timecreated(), $step->get_user_id());
1369
dcd03928 1370 } else {
9212fe7a 1371 // This is the normal case. Replay the next step of the attempt.
09fd8aec
MG
1372 if ($step === $oldqa->autosavedstep) {
1373 $this->process_autosave($step->get_submitted_data(),
1374 $step->get_timecreated(), $step->get_user_id());
1375 } else {
1376 $this->process_action($step->get_submitted_data(),
1377 $step->get_timecreated(), $step->get_user_id(), $step->get_id());
1378 }
dcd03928
TH
1379 }
1380 }
9212fe7a 1381
dcd03928
TH
1382 if ($finished) {
1383 $this->finish();
1384 }
2d708a73
TH
1385
1386 $this->set_flagged($oldqa->is_flagged());
dcd03928
TH
1387 }
1388
f6579bea
TH
1389 /**
1390 * Change the max mark for this question_attempt.
1391 * @param float $maxmark the new max mark.
1392 */
1393 public function set_max_mark($maxmark) {
1394 $this->maxmark = $maxmark;
1395 $this->observer->notify_attempt_modified($this);
1396 }
1397
dcd03928
TH
1398 /**
1399 * Perform a manual grading action on this attempt.
53b8e256
TH
1400 * @param string $comment the comment being added.
1401 * @param float $mark the new mark. If null, then only a comment is added.
1402 * @param int $commentformat the FORMAT_... for $comment. Must be given.
dcd03928
TH
1403 * @param int $timestamp the time to record for the action. (If not given, use now.)
1404 * @param int $userid the user to attribute the aciton to. (If not given, use the current user.)
dcd03928 1405 */
53b8e256 1406 public function manual_grade($comment, $mark, $commentformat = null, $timestamp = null, $userid = null) {
dcd03928 1407 $submitteddata = array('-comment' => $comment);
53b8e256
TH
1408 if (is_null($commentformat)) {
1409 debugging('You should pass $commentformat to manual_grade.', DEBUG_DEVELOPER);
1410 $commentformat = FORMAT_HTML;
1411 }
1412 $submitteddata['-commentformat'] = $commentformat;
dcd03928
TH
1413 if (!is_null($mark)) {
1414 $submitteddata['-mark'] = $mark;
1415 $submitteddata['-maxmark'] = $this->maxmark;
1416 }
1417 $this->process_action($submitteddata, $timestamp, $userid);
1418 }
1419
1420 /** @return bool Whether this question attempt has had a manual comment added. */
1421 public function has_manual_comment() {
1422 foreach ($this->steps as $step) {
1423 if ($step->has_behaviour_var('comment')) {
1424 return true;
1425 }
1426 }
1427 return false;
1428 }
1429
1430 /**
1431 * @return array(string, int) the most recent manual comment that was added
f3d9872a 1432 * to this question, the FORMAT_... it is and the step itself.
dcd03928
TH
1433 */
1434 public function get_manual_comment() {
1435 foreach ($this->get_reverse_step_iterator() as $step) {
1436 if ($step->has_behaviour_var('comment')) {
1437 return array($step->get_behaviour_var('comment'),
f3d9872a
AH
1438 $step->get_behaviour_var('commentformat'),
1439 $step);
dcd03928
TH
1440 }
1441 }
f3d9872a 1442 return array(null, null, null);
dcd03928
TH
1443 }
1444
1eb470fc
TH
1445 /**
1446 * This is used by the manual grading code, particularly in association with
1447 * validation. If there is a comment submitted in the request, then use that,
1448 * otherwise use the latest comment for this question.
6c91e515
TH
1449 *
1450 * @return array with three elements, comment, commentformat and mark.
1eb470fc
TH
1451 */
1452 public function get_current_manual_comment() {
1453 $comment = $this->get_submitted_var($this->get_behaviour_field_name('comment'), PARAM_RAW);
1454 if (is_null($comment)) {
1455 return $this->get_manual_comment();
1456 } else {
1457 $commentformat = $this->get_submitted_var(
1458 $this->get_behaviour_field_name('commentformat'), PARAM_INT);
1459 if ($commentformat === null) {
1460 $commentformat = FORMAT_HTML;
1461 }
f3d9872a 1462 return array($comment, $commentformat, null);
1eb470fc
TH
1463 }
1464 }
1465
dcd03928 1466 /**
038014c4 1467 * Break down a student response by sub part and classification. See also {@link question::classify_response}.
d50b05e6
JP
1468 * Used for response analysis.
1469 *
6c91e515
TH
1470 * @param string $whichtries which tries to analyse for response analysis. Will be one of
1471 * question_attempt::FIRST_TRY, LAST_TRY or ALL_TRIES. Defaults to question_attempt::LAST_TRY.
1472 * @return question_classified_response[]|question_classified_response[][] If $whichtries is
1473 * question_attempt::FIRST_TRY or LAST_TRY index is subpartid and values are
1474 * question_classified_response instances.
1475 * If $whichtries is question_attempt::ALL_TRIES then first key is submitted response no
1476 * and the second key is subpartid.
dcd03928 1477 */
038014c4
JP
1478 public function classify_response($whichtries = self::LAST_TRY) {
1479 return $this->behaviour->classify_response($whichtries);
dcd03928
TH
1480 }
1481
1482 /**
1483 * Create a question_attempt_step from records loaded from the database.
1484 *
1485 * For internal use only.
1486 *
35d5f1c2 1487 * @param Iterator $records Raw records loaded from the database.
dcd03928 1488 * @param int $questionattemptid The id of the question_attempt to extract.
6c91e515
TH
1489 * @param question_usage_observer $observer the observer that will be monitoring changes in us.
1490 * @param string $preferredbehaviour the preferred behaviour under which we are operating.
94815ccf 1491 * @return question_attempt The newly constructed question_attempt.
dcd03928 1492 */
35d5f1c2 1493 public static function load_from_records($records, $questionattemptid,
dcd03928 1494 question_usage_observer $observer, $preferredbehaviour) {
35d5f1c2 1495 $record = $records->current();
dcd03928 1496 while ($record->questionattemptid != $questionattemptid) {
6c91e515 1497 $records->next();
35d5f1c2 1498 if (!$records->valid()) {
f4fe3968 1499 throw new coding_exception("Question attempt {$questionattemptid} not found in the database.");
dcd03928 1500 }
35d5f1c2 1501 $record = $records->current();
dcd03928
TH
1502 }
1503
1504 try {
1505 $question = question_bank::load_question($record->questionid);
1506 } catch (Exception $e) {
1507 // The question must have been deleted somehow. Create a missing
1508 // question to use in its place.
1509 $question = question_bank::get_qtype('missingtype')->make_deleted_instance(
1510 $record->questionid, $record->maxmark + 0);
1511 }
1512
1513 $qa = new question_attempt($question, $record->questionusageid,
1514 null, $record->maxmark + 0);
1515 $qa->set_database_id($record->questionattemptid);
94815ccf 1516 $qa->set_slot($record->slot);
1da821bb 1517 $qa->variant = $record->variant + 0;
dcd03928 1518 $qa->minfraction = $record->minfraction + 0;
4e3d8293 1519 $qa->maxfraction = $record->maxfraction + 0;
dcd03928
TH
1520 $qa->set_flagged($record->flagged);
1521 $qa->questionsummary = $record->questionsummary;
1522 $qa->rightanswer = $record->rightanswer;
1523 $qa->responsesummary = $record->responsesummary;
1524 $qa->timemodified = $record->timemodified;
1525
1526 $qa->behaviour = question_engine::make_behaviour(
1527 $record->behaviour, $qa, $preferredbehaviour);
0a606a2b 1528 $qa->observer = $observer;
dcd03928 1529
dd7aa583
TH
1530 // If attemptstepid is null (which should not happen, but has happened
1531 // due to corrupt data, see MDL-34251) then the current pointer in $records
1532 // will not be advanced in the while loop below, and we get stuck in an
1533 // infinite loop, since this method is supposed to always consume at
1534 // least one record. Therefore, in this case, advance the record here.
1535 if (is_null($record->attemptstepid)) {
1536 $records->next();
1537 }
1538
dcd03928 1539 $i = 0;
0a606a2b
TH
1540 $autosavedstep = null;
1541 $autosavedsequencenumber = null;
dcd03928 1542 while ($record && $record->questionattemptid == $questionattemptid && !is_null($record->attemptstepid)) {
0a606a2b 1543 $sequencenumber = $record->sequencenumber;
dc1ee5cb 1544 $nextstep = question_attempt_step::load_from_records($records, $record->attemptstepid, $qa->get_question()->get_type_name());
0a606a2b
TH
1545
1546 if ($sequencenumber < 0) {
1547 if (!$autosavedstep) {
1548 $autosavedstep = $nextstep;
1549 $autosavedsequencenumber = -$sequencenumber;
1550 } else {
1551 // Old redundant data. Mark it for deletion.
1552 $qa->observer->notify_step_deleted($nextstep, $qa);
1553 }
1554 } else {
1555 $qa->steps[$i] = $nextstep;
1556 if ($i == 0) {
1557 $question->apply_attempt_state($qa->steps[0]);
1558 }
1559 $i++;
dcd03928 1560 }
0a606a2b 1561
35d5f1c2
TH
1562 if ($records->valid()) {
1563 $record = $records->current();
1564 } else {
1565 $record = false;
1566 }
dcd03928
TH
1567 }
1568
0a606a2b
TH
1569 if ($autosavedstep) {
1570 if ($autosavedsequencenumber >= $i) {
1571 $qa->autosavedstep = $autosavedstep;
1572 $qa->steps[$i] = $qa->autosavedstep;
1573 } else {
1574 $qa->observer->notify_step_deleted($autosavedstep, $qa);
1575 }
1576 }
dcd03928
TH
1577
1578 return $qa;
1579 }
99caa248
JP
1580
1581 /**
1582 * Allow access to steps with responses submitted by students for grading in a question attempt.
1583 *
1584 * @return question_attempt_steps_with_submitted_response_iterator to access all steps with submitted data for questions that
1585 * allow multiple submissions that count towards grade, per attempt.
1586 */
1587 public function get_steps_with_submitted_response_iterator() {
1588 return new question_attempt_steps_with_submitted_response_iterator($this);
1589 }
dcd03928
TH
1590}
1591
1592
1593/**
1594 * This subclass of question_attempt pretends that only part of the step history
1595 * exists. It is used for rendering the question in past states.
1596 *
1597 * All methods that try to modify the question_attempt throw exceptions.
1598 *
1599 * @copyright 2010 The Open University
1600 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1601 */
1602class question_attempt_with_restricted_history extends question_attempt {
1603 /**
1604 * @var question_attempt the underlying question_attempt.
1605 */
1606 protected $baseqa;
1607
1608 /**
1609 * Create a question_attempt_with_restricted_history
1610 * @param question_attempt $baseqa The question_attempt to make a restricted version of.
1611 * @param int $lastseq the index of the last step to include.
1612 * @param string $preferredbehaviour the preferred behaviour. It is slightly
6c91e515 1613 * annoying that this needs to be passed, but unavoidable for now.
dcd03928
TH
1614 */
1615 public function __construct(question_attempt $baseqa, $lastseq, $preferredbehaviour) {
f123d67f
TH
1616 $this->baseqa = $baseqa->get_full_qa();
1617
1618 if ($lastseq < 0 || $lastseq >= $this->baseqa->get_num_steps()) {
1619 throw new coding_exception('$lastseq out of range', $lastseq);
dcd03928
TH
1620 }
1621
f123d67f 1622 $this->steps = array_slice($this->baseqa->steps, 0, $lastseq + 1);
dcd03928
TH
1623 $this->observer = new question_usage_null_observer();
1624
1625 // This should be a straight copy of all the remaining fields.
f123d67f
TH
1626 $this->id = $this->baseqa->id;
1627 $this->usageid = $this->baseqa->usageid;
1628 $this->slot = $this->baseqa->slot;
1629 $this->question = $this->baseqa->question;
1630 $this->maxmark = $this->baseqa->maxmark;
1631 $this->minfraction = $this->baseqa->minfraction;
4e3d8293 1632 $this->maxfraction = $this->baseqa->maxfraction;
f123d67f
TH
1633 $this->questionsummary = $this->baseqa->questionsummary;
1634 $this->responsesummary = $this->baseqa->responsesummary;
1635 $this->rightanswer = $this->baseqa->rightanswer;
1636 $this->flagged = $this->baseqa->flagged;
dcd03928
TH
1637
1638 // Except behaviour, where we need to create a new one.
1639 $this->behaviour = question_engine::make_behaviour(
f123d67f
TH
1640 $this->baseqa->get_behaviour_name(), $this, $preferredbehaviour);
1641 }
1642
1643 public function get_full_qa() {
1644 return $this->baseqa;
dcd03928
TH
1645 }
1646
1647 public function get_full_step_iterator() {
1648 return $this->baseqa->get_step_iterator();
1649 }
1650
1651 protected function add_step(question_attempt_step $step) {
6c91e515 1652 throw new coding_exception('Cannot modify a question_attempt_with_restricted_history.');
dcd03928 1653 }
072db71c 1654 public function process_action($submitteddata, $timestamp = null, $userid = null, $existingstepid = null) {
6c91e515 1655 throw new coding_exception('Cannot modify a question_attempt_with_restricted_history.');
dcd03928 1656 }
072db71c 1657 public function start($preferredbehaviour, $variant, $submitteddata = array(), $timestamp = null, $userid = null, $existingstepid = null) {
6c91e515 1658 throw new coding_exception('Cannot modify a question_attempt_with_restricted_history.');
dcd03928
TH
1659 }
1660
1661 public function set_database_id($id) {
6c91e515 1662 throw new coding_exception('Cannot modify a question_attempt_with_restricted_history.');
dcd03928
TH
1663 }
1664 public function set_flagged($flagged) {
6c91e515 1665 throw new coding_exception('Cannot modify a question_attempt_with_restricted_history.');
dcd03928 1666 }
94815ccf 1667 public function set_slot($slot) {
6c91e515 1668 throw new coding_exception('Cannot modify a question_attempt_with_restricted_history.');
dcd03928
TH
1669 }
1670 public function set_question_summary($questionsummary) {
6c91e515 1671 throw new coding_exception('Cannot modify a question_attempt_with_restricted_history.');
dcd03928
TH
1672 }
1673 public function set_usage_id($usageid) {
6c91e515 1674 throw new coding_exception('Cannot modify a question_attempt_with_restricted_history.');
dcd03928
TH
1675 }
1676}
1677
1678
1679/**
1680 * A class abstracting access to the {@link question_attempt::$states} array.
1681 *
1682 * This is actively linked to question_attempt. If you add an new step
1683 * mid-iteration, then it will be included.
1684 *
1685 * @copyright 2009 The Open University
1686 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1687 */
1688class question_attempt_step_iterator implements Iterator, ArrayAccess {
1689 /** @var question_attempt the question_attempt being iterated over. */
1690 protected $qa;
1691 /** @var integer records the current position in the iteration. */
1692 protected $i;
1693
1694 /**
1695 * Do not call this constructor directly.
1696 * Use {@link question_attempt::get_step_iterator()}.
1697 * @param question_attempt $qa the attempt to iterate over.
1698 */
1699 public function __construct(question_attempt $qa) {
1700 $this->qa = $qa;
1701 $this->rewind();
1702 }
1703
1704 /** @return question_attempt_step */
1705 public function current() {
1706 return $this->offsetGet($this->i);
1707 }
1708 /** @return int */
1709 public function key() {
1710 return $this->i;
1711 }
1712 public function next() {
1713 ++$this->i;
1714 }
1715 public function rewind() {
1716 $this->i = 0;
1717 }
1718 /** @return bool */
1719 public function valid() {
1720 return $this->offsetExists($this->i);
1721 }
1722
1723 /** @return bool */
1724 public function offsetExists($i) {
1725 return $i >= 0 && $i < $this->qa->get_num_steps();
1726 }
1727 /** @return question_attempt_step */
1728 public function offsetGet($i) {
1729 return $this->qa->get_step($i);
1730 }
1731 public function offsetSet($offset, $value) {
1732 throw new coding_exception('You are only allowed read-only access to question_attempt::states through a question_attempt_step_iterator. Cannot set.');
1733 }
1734 public function offsetUnset($offset) {
1735 throw new coding_exception('You are only allowed read-only access to question_attempt::states through a question_attempt_step_iterator. Cannot unset.');
1736 }
1737}
1738
1739
1740/**
1741 * A variant of {@link question_attempt_step_iterator} that iterates through the
1742 * steps in reverse order.
1743 *
1744 * @copyright 2009 The Open University
1745 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1746 */
1747class question_attempt_reverse_step_iterator extends question_attempt_step_iterator {
1748 public function next() {
1749 --$this->i;
1750 }
1751
1752 public function rewind() {
1753 $this->i = $this->qa->get_num_steps() - 1;
1754 }
1755}
99caa248
JP
1756
1757/**
1758 * A variant of {@link question_attempt_step_iterator} that iterates through the
1759 * steps with submitted tries.
1760 *
1761 * @copyright 2014 The Open University
1762 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1763 */
1764class question_attempt_steps_with_submitted_response_iterator extends question_attempt_step_iterator implements Countable {
1765
1766 /** @var question_attempt the question_attempt being iterated over. */
1767 protected $qa;
1768
1769 /** @var integer records the current position in the iteration. */
1770 protected $submittedresponseno;
1771
1772 /**
1773 * Index is the submitted response number and value is the step no.
1774 *
1775 * @var int[]
1776 */
1777 protected $stepswithsubmittedresponses;
1778
1779 /**
1780 * Do not call this constructor directly.
1781 * Use {@link question_attempt::get_submission_step_iterator()}.
1782 * @param question_attempt $qa the attempt to iterate over.
1783 */
1784 public function __construct(question_attempt $qa) {
1785 $this->qa = $qa;
1786 $this->find_steps_with_submitted_response();
1787 $this->rewind();
1788 }
1789
1790 /**
1791 * Find the step nos in which a student has submitted a response. Including any step with a response that is saved before
1792 * the question attempt finishes.
1793 *
1794 * Called from constructor, should not be called from elsewhere.
1795 *
1796 */
1797 protected function find_steps_with_submitted_response() {
1798 $stepnos = array();
1799 $lastsavedstep = null;
1800 foreach ($this->qa->get_step_iterator() as $stepno => $step) {
1801 if ($this->qa->get_behaviour()->step_has_a_submitted_response($step)) {
1802 $stepnos[] = $stepno;
1803 $lastsavedstep = null;
1804 } else {
1805 $qtdata = $step->get_qt_data();
1806 if (count($qtdata)) {
1807 $lastsavedstep = $stepno;
1808 }
1809 }
1810 }
1811
1812 if (!is_null($lastsavedstep)) {
1813 $stepnos[] = $lastsavedstep;
1814 }
1815 if (empty($stepnos)) {
1816 $this->stepswithsubmittedresponses = array();
1817 } else {
1818 // Re-index array so index starts with 1.
1819 $this->stepswithsubmittedresponses = array_combine(range(1, count($stepnos)), $stepnos);
1820 }
1821 }
1822
1823 /** @return question_attempt_step */
1824 public function current() {
1825 return $this->offsetGet($this->submittedresponseno);
1826 }
1827 /** @return int */
1828 public function key() {
1829 return $this->submittedresponseno;
1830 }
1831 public function next() {
1832 ++$this->submittedresponseno;
1833 }
1834 public function rewind() {
1835 $this->submittedresponseno = 1;
1836 }
1837 /** @return bool */
1838 public function valid() {
038014c4 1839 return $this->submittedresponseno >= 1 && $this->submittedresponseno <= count($this->stepswithsubmittedresponses);
99caa248
JP
1840 }
1841
1842 /**
1843 * @param int $submittedresponseno
1844 * @return bool
1845 */
1846 public function offsetExists($submittedresponseno) {
1847 return $submittedresponseno >= 1;
1848 }
1849
1850 /**
1851 * @param int $submittedresponseno
1852 * @return question_attempt_step
1853 */
1854 public function offsetGet($submittedresponseno) {
1855 if ($submittedresponseno > count($this->stepswithsubmittedresponses)) {
1856 return null;
1857 } else {
1858 return $this->qa->get_step($this->step_no_for_try($submittedresponseno));
1859 }
1860 }
1861
1862 /**
1863 * @return int the count of steps with tries.
1864 */
1865 public function count() {
1866 return count($this->stepswithsubmittedresponses);
1867 }
1868
1869 /**
1870 * @param int $submittedresponseno
1871 * @throws coding_exception
1872 * @return int|null the step number or null if there is no such submitted response.
1873 */
1874 public function step_no_for_try($submittedresponseno) {
1875 if (isset($this->stepswithsubmittedresponses[$submittedresponseno])) {
1876 return $this->stepswithsubmittedresponses[$submittedresponseno];
1877 } else if ($submittedresponseno > count($this->stepswithsubmittedresponses)) {
1878 return null;
1879 } else {
1880 throw new coding_exception('Try number not found. It should be 1 or more.');
1881 }
1882 }
1883
1884 public function offsetSet($offset, $value) {
1885 throw new coding_exception('You are only allowed read-only access to question_attempt::states '.
1886 'through a question_attempt_step_iterator. Cannot set.');
1887 }
1888 public function offsetUnset($offset) {
1889 throw new coding_exception('You are only allowed read-only access to question_attempt::states '.
1890 'through a question_attempt_step_iterator. Cannot unset.');
1891 }
1892
1893}