MDL-27408 Database upgrade for adaptive mode.
[moodle.git] / question / engine / questionusage.php
CommitLineData
dcd03928
TH
1<?php
2
3// This file is part of Moodle - http://moodle.org/
4//
5// Moodle is free software: you can redistribute it and/or modify
6// it under the terms of the GNU General Public License as published by
7// the Free Software Foundation, either version 3 of the License, or
8// (at your option) any later version.
9//
10// Moodle is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU General Public License for more details.
14//
15// You should have received a copy of the GNU General Public License
16// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
17
18/**
19 * This file defines the question usage class, and a few related classes.
20 *
21 * @package moodlecore
22 * @subpackage questionengine
23 * @copyright 2009 The Open University
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
26
27
28defined('MOODLE_INTERNAL') || die();
29
30
31/**
32 * This class keeps track of a group of questions that are being attempted,
33 * and which state, and so on, each one is currently in.
34 *
35 * A quiz attempt or a lesson attempt could use an instance of this class to
36 * keep track of all the questions in the attempt and process student submissions.
37 * It is basically a collection of {@question_attempt} objects.
38 *
39 * The questions being attempted as part of this usage are identified by an integer
40 * that is passed into many of the methods as $slot. ($question->id is not
41 * used so that the same question can be used more than once in an attempt.)
42 *
43 * Normally, calling code should be able to do everything it needs to be calling
44 * methods of this class. You should not normally need to get individual
45 * {@question_attempt} objects and play around with their inner workind, in code
46 * that it outside the quetsion engine.
47 *
48 * Instances of this class correspond to rows in the question_usages table.
49 *
50 * @copyright 2009 The Open University
51 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
52 */
53class question_usage_by_activity {
54 /**
55 * @var integer|string the id for this usage. If this usage was loaded from
56 * the database, then this is the database id. Otherwise a unique random
57 * string is used.
58 */
59 protected $id = null;
60
61 /**
62 * @var string name of an archetypal behaviour, that should be used
63 * by questions in this usage if possible.
64 */
65 protected $preferredbehaviour = null;
66
67 /** @var object the context this usage belongs to. */
68 protected $context;
69
70 /** @var string plugin name of the plugin this usage belongs to. */
71 protected $owningcomponent;
72
73 /** @var array {@link question_attempt}s that make up this usage. */
74 protected $questionattempts = array();
75
76 /** @var question_usage_observer that tracks changes to this usage. */
77 protected $observer;
78
79 /**
80 * Create a new instance. Normally, calling code should use
81 * {@link question_engine::make_questions_usage_by_activity()} or
82 * {@link question_engine::load_questions_usage_by_activity()} rather than
83 * calling this constructor directly.
84 *
85 * @param string $component the plugin creating this attempt. For example mod_quiz.
86 * @param object $context the context this usage belongs to.
87 */
88 public function __construct($component, $context) {
89 $this->owningcomponent = $component;
90 $this->context = $context;
91 $this->observer = new question_usage_null_observer();
92 }
93
94 /**
95 * @param string $behaviour the name of an archetypal behaviour, that should
96 * be used by questions in this usage if possible.
97 */
98 public function set_preferred_behaviour($behaviour) {
99 $this->preferredbehaviour = $behaviour;
100 $this->observer->notify_modified();
101 }
102
103 /** @return string the name of the preferred behaviour. */
104 public function get_preferred_behaviour() {
105 return $this->preferredbehaviour;
106 }
107
108 /** @return object the context this usage belongs to. */
109 public function get_owning_context() {
110 return $this->context;
111 }
112
113 /** @return string the name of the plugin that owns this attempt. */
114 public function get_owning_component() {
115 return $this->owningcomponent;
116 }
117
118 /** @return int|string If this usage came from the database, then the id
119 * from the question_usages table is returned. Otherwise a random string is
120 * returned. */
121 public function get_id() {
122 if (is_null($this->id)) {
123 $this->id = random_string(10);
124 }
125 return $this->id;
126 }
127
128 /** @return question_usage_observer that is tracking changes made to this usage. */
129 public function get_observer() {
130 return $this->observer;
131 }
132
133 /**
134 * For internal use only. Used by {@link question_engine_data_mapper} to set
135 * the id when a usage is saved to the database.
136 * @param int $id the newly determined id for this usage.
137 */
138 public function set_id_from_database($id) {
139 $this->id = $id;
140 foreach ($this->questionattempts as $qa) {
141 $qa->set_usage_id($id);
142 }
143 }
144
145 /**
146 * Add another question to this usage.
147 *
148 * The added question is not started until you call {@link start_question()}
149 * on it.
150 *
151 * @param question_definition $question the question to add.
152 * @param number $maxmark the maximum this question will be marked out of in
153 * this attempt (optional). If not given, $question->defaultmark is used.
154 * @return int the number used to identify this question within this usage.
155 */
156 public function add_question(question_definition $question, $maxmark = null) {
157 $qa = new question_attempt($question, $this->get_id(), $this->observer, $maxmark);
158 if (count($this->questionattempts) == 0) {
159 $this->questionattempts[1] = $qa;
160 } else {
161 $this->questionattempts[] = $qa;
162 }
163 $qa->set_number_in_usage(end(array_keys($this->questionattempts)));
164 $this->observer->notify_attempt_added($qa);
165 return $qa->get_slot();
166 }
167
168 /**
169 * Get the question_definition for a question in this attempt.
170 * @param int $slot the number used to identify this question within this usage.
171 * @return question_definition the requested question object.
172 */
173 public function get_question($slot) {
174 return $this->get_question_attempt($slot)->get_question();
175 }
176
177 /** @return array all the identifying numbers of all the questions in this usage. */
178 public function get_slots() {
179 return array_keys($this->questionattempts);
180 }
181
182 /** @return int the identifying number of the first question that was added to this usage. */
183 public function get_first_question_number() {
184 reset($this->questionattempts);
185 return key($this->questionattempts);
186 }
187
188 /** @return int the number of questions that are currently in this usage. */
189 public function question_count() {
190 return count($this->questionattempts);
191 }
192
193 /**
194 * Note the part of the {@link question_usage_by_activity} comment that explains
195 * that {@link question_attempt} objects should be considered part of the inner
196 * workings of the question engine, and should not, if possible, be accessed directly.
197 *
198 * @return question_attempt_iterator for iterating over all the questions being
199 * attempted. as part of this usage.
200 */
201 public function get_attempt_iterator() {
202 return new question_attempt_iterator($this);
203 }
204
205 /**
206 * Check whether $number actually corresponds to a question attempt that is
207 * part of this usage. Throws an exception if not.
208 *
209 * @param int $slot a number allegedly identifying a question within this usage.
210 */
211 protected function check_slot($slot) {
212 if (!array_key_exists($slot, $this->questionattempts)) {
213 throw new coding_exception("There is no question_attempt number $slot in this attempt.");
214 }
215 }
216
217 /**
218 * Note the part of the {@link question_usage_by_activity} comment that explains
219 * that {@link question_attempt} objects should be considered part of the inner
220 * workings of the question engine, and should not, if possible, be accessed directly.
221 *
222 * @param int $slot the number used to identify this question within this usage.
223 * @return question_attempt the corresponding {@link question_attempt} object.
224 */
225 public function get_question_attempt($slot) {
226 $this->check_slot($slot);
227 return $this->questionattempts[$slot];
228 }
229
230 /**
231 * Get the current state of the attempt at a question.
232 * @param int $slot the number used to identify this question within this usage.
233 * @return question_state.
234 */
235 public function get_question_state($slot) {
236 return $this->get_question_attempt($slot)->get_state();
237 }
238
239 /**
240 * @param int $slot the number used to identify this question within this usage.
241 * @param bool $showcorrectness Whether right/partial/wrong states should
242 * be distinguised.
243 * @return string A brief textual description of the current state.
244 */
245 public function get_question_state_string($slot, $showcorrectness) {
246 return $this->get_question_attempt($slot)->get_state_string($showcorrectness);
247 }
248
249 /**
250 * Get the time of the most recent action performed on a question.
251 * @param int $slot the number used to identify this question within this usage.
252 * @return int timestamp.
253 */
254 public function get_question_action_time($slot) {
255 return $this->get_question_attempt($slot)->get_last_action_time();
256 }
257
258 /**
259 * Get the current fraction awarded for the attempt at a question.
260 * @param int $slot the number used to identify this question within this usage.
261 * @return number|null The current fraction for this question, or null if one has
262 * not been assigned yet.
263 */
264 public function get_question_fraction($slot) {
265 return $this->get_question_attempt($slot)->get_fraction();
266 }
267
268 /**
269 * Get the current mark awarded for the attempt at a question.
270 * @param int $slot the number used to identify this question within this usage.
271 * @return number|null The current mark for this question, or null if one has
272 * not been assigned yet.
273 */
274 public function get_question_mark($slot) {
275 return $this->get_question_attempt($slot)->get_mark();
276 }
277
278 /**
279 * Get the maximum mark possible for the attempt at a question.
280 * @param int $slot the number used to identify this question within this usage.
281 * @return number the available marks for this question.
282 */
283 public function get_question_max_mark($slot) {
284 return $this->get_question_attempt($slot)->get_max_mark();
285 }
286
287 /**
288 * Get the current mark awarded for the attempt at a question.
289 * @param int $slot the number used to identify this question within this usage.
290 * @return number|null The current mark for this question, or null if one has
291 * not been assigned yet.
292 */
293 public function get_total_mark() {
294 $mark = 0;
295 foreach ($this->questionattempts as $qa) {
296 if ($qa->get_max_mark() > 0 && $qa->get_state() == question_state::$needsgrading) {
297 return null;
298 }
299 $mark += $qa->get_mark();
300 }
301 return $mark;
302 }
303
304 /**
305 * @return string a simple textual summary of the question that was asked.
306 */
307 public function get_question_summary($slot) {
308 return $this->get_question_attempt($slot)->get_question_summary();
309 }
310
311 /**
312 * @return string a simple textual summary of response given.
313 */
314 public function get_response_summary($slot) {
315 return $this->get_question_attempt($slot)->get_response_summary();
316 }
317
318 /**
319 * @return string a simple textual summary of the correct resonse.
320 */
321 public function get_right_answer_summary($slot) {
322 return $this->get_question_attempt($slot)->get_right_answer_summary();
323 }
324
325 /**
326 * Get the {@link core_question_renderer}, in collaboration with appropriate
327 * {@link qbehaviour_renderer} and {@link qtype_renderer} subclasses, to generate the
328 * HTML to display this question.
329 * @param int $slot the number used to identify this question within this usage.
330 * @param question_display_options $options controls how the question is rendered.
331 * @param string|null $number The question number to display. 'i' is a special
332 * value that gets displayed as Information. Null means no number is displayed.
333 * @return string HTML fragment representing the question.
334 */
335 public function render_question($slot, $options, $number = null) {
336 $options->context = $this->context;
337 return $this->get_question_attempt($slot)->render($options, $number);
338 }
339
340 /**
341 * Generate any bits of HTML that needs to go in the <head> tag when this question
342 * is displayed in the body.
343 * @param int $slot the number used to identify this question within this usage.
344 * @return string HTML fragment.
345 */
346 public function render_question_head_html($slot) {
347 $options->context = $this->context;
348 return $this->get_question_attempt($slot)->render_head_html();
349 }
350
351 /**
352 * Like {@link render_question()} but displays the question at the past step
353 * indicated by $seq, rather than showing the latest step.
354 *
355 * @param int $slot the number used to identify this question within this usage.
356 * @param int $seq the seq number of the past state to display.
357 * @param question_display_options $options controls how the question is rendered.
358 * @param string|null $number The question number to display. 'i' is a special
359 * value that gets displayed as Information. Null means no number is displayed.
360 * @return string HTML fragment representing the question.
361 */
362 public function render_question_at_step($slot, $seq, $options, $number = null) {
363 $options->context = $this->context;
364 return $this->get_question_attempt($slot)->render_at_step($seq, $options, $number, $this->preferredbehaviour);
365 }
366
367 /**
368 * Checks whether the users is allow to be served a particular file.
369 * @param int $slot the number used to identify this question within this usage.
370 * @param question_display_options $options the options that control display of the question.
371 * @param string $component the name of the component we are serving files for.
372 * @param string $filearea the name of the file area.
373 * @param array $args the remaining bits of the file path.
374 * @param bool $forcedownload whether the user must be forced to download the file.
375 * @return bool true if the user can access this file.
376 */
377 public function check_file_access($slot, $options, $component, $filearea, $args, $forcedownload) {
378 return $this->get_question_attempt($slot)->check_file_access($options, $component, $filearea, $args, $forcedownload);
379 }
380
381 /**
382 * Replace a particular question_attempt with a different one.
383 *
384 * For internal use only. Used when reloading the state of a question from the
385 * database.
386 *
387 * @param array $records Raw records loaded from the database.
388 * @param int $questionattemptid The id of the question_attempt to extract.
389 * @return question_attempt The newly constructed question_attempt_step.
390 */
391 public function replace_loaded_question_attempt_info($slot, $qa) {
392 $this->check_slot($slot);
393 $this->questionattempts[$slot] = $qa;
394 }
395
396 /**
397 * You should probably not use this method in code outside the question engine.
398 * The main reason for exposing it was for the benefit of unit tests.
399 * @param int $slot the number used to identify this question within this usage.
400 * @return string return the prefix that is pre-pended to field names in the HTML
401 * that is output.
402 */
403 public function get_field_prefix($slot) {
404 return $this->get_question_attempt($slot)->get_field_prefix();
405 }
406
407 /**
408 * Start the attempt at a question that has been added to this usage.
409 * @param int $slot the number used to identify this question within this usage.
410 */
411 public function start_question($slot) {
412 $qa = $this->get_question_attempt($slot);
413 $qa->start($this->preferredbehaviour);
414 $this->observer->notify_attempt_modified($qa);
415 }
416
417 /**
418 * Start the attempt at all questions that has been added to this usage.
419 */
420 public function start_all_questions() {
421 foreach ($this->questionattempts as $qa) {
422 $qa->start($this->preferredbehaviour);
423 $this->observer->notify_attempt_modified($qa);
424 }
425 }
426
427 /**
428 * Start the attempt at a question, starting from the point where the previous
429 * question_attempt $oldqa had reached. This is used by the quiz 'Each attempt
430 * builds on last' mode.
431 * @param int $slot the number used to identify this question within this usage.
432 * @param question_attempt $oldqa a previous attempt at this quetsion that
433 * defines the starting point.
434 */
435 public function start_question_based_on($slot, question_attempt $oldqa) {
436 $qa = $this->get_question_attempt($slot);
437 $qa->start_based_on($oldqa);
438 $this->observer->notify_attempt_modified($qa);
439 }
440
441 /**
442 * Process all the question actions in the current request.
443 *
444 * If there is a parameter slots included in the post data, then only
445 * those question numbers will be processed, otherwise all questions in this
446 * useage will be.
447 *
448 * This function also does {@link update_question_flags()}.
449 *
450 * @param int $timestamp optional, use this timestamp as 'now'.
451 * @param array $postdata optional, only intended for testing. Use this data
452 * instead of the data from $_POST.
453 */
454 public function process_all_actions($timestamp = null, $postdata = null) {
455 $slots = question_attempt::get_submitted_var('slots', PARAM_SEQUENCE, $postdata);
456 if (is_null($slots)) {
457 $slots = $this->get_slots();
458 } else if (!$slots) {
459 $slots = array();
460 } else {
461 $slots = explode(',', $slots);
462 }
463 foreach ($slots as $slot) {
464 if (!$this->validate_sequence_number($slot, $postdata)) {
465 continue;
466 }
467 $submitteddata = $this->extract_responses($slot, $postdata);
468 $this->process_action($slot, $submitteddata, $timestamp);
469 }
470 $this->update_question_flags($postdata);
471 }
472
473 /**
474 * Get the submitted data from the current request that belongs to this
475 * particular question.
476 *
477 * @param int $slot the number used to identify this question within this usage.
478 * @param $postdata optional, only intended for testing. Use this data
479 * instead of the data from $_POST.
480 * @return array submitted data specific to this question.
481 */
482 public function extract_responses($slot, $postdata = null) {
483 return $this->get_question_attempt($slot)->get_submitted_data($postdata);
484 }
485
486 /**
487 * Process a specific action on a specific question.
488 * @param int $slot the number used to identify this question within this usage.
489 * @param $submitteddata the submitted data that constitutes the action.
490 */
491 public function process_action($slot, $submitteddata, $timestamp = null) {
492 $qa = $this->get_question_attempt($slot);
493 $qa->process_action($submitteddata, $timestamp);
494 $this->observer->notify_attempt_modified($qa);
495 }
496
497 /**
498 * Check that the sequence number, that detects weird things like the student
499 * clicking back, is OK. If the sequence check variable is not present, returns
500 * false. If the check variable is present and correct, returns true. If the
501 * variable is present and wrong, throws an exception.
502 * @param int $slot the number used to identify this question within this usage.
503 * @param array $submitteddata the submitted data that constitutes the action.
504 * @return bool true if the check variable is present and correct. False if it
505 * is missing. (Throws an exception if the check fails.)
506 */
507 public function validate_sequence_number($slot, $postdata = null) {
508 $qa = $this->get_question_attempt($slot);
509 $sequencecheck = $qa->get_submitted_var(
510 $qa->get_control_field_name('sequencecheck'), PARAM_INT, $postdata);
511 if (is_null($sequencecheck)) {
512 return false;
513 } else if ($sequencecheck != $qa->get_num_steps()) {
514 throw new question_out_of_sequence_exception($this->id, $slot, $postdata);
515 } else {
516 return true;
517 }
518 }
519 /**
520 * Update the flagged state for all question_attempts in this usage, if their
521 * flagged state was changed in the request.
522 *
523 * @param $postdata optional, only intended for testing. Use this data
524 * instead of the data from $_POST.
525 */
526 public function update_question_flags($postdata = null) {
527 foreach ($this->questionattempts as $qa) {
528 $flagged = $qa->get_submitted_var(
529 $qa->get_flag_field_name(), PARAM_BOOL, $postdata);
530 if (!is_null($flagged) && $flagged != $qa->is_flagged()) {
531 $qa->set_flagged($flagged);
532 }
533 }
534 }
535
536 /**
537 * Get the correct response to a particular question. Passing the results of
538 * this method to {@link process_action()} will probably result in full marks.
539 * @param int $slot the number used to identify this question within this usage.
540 * @return array that constitutes a correct response to this question.
541 */
542 public function get_correct_response($slot) {
543 return $this->get_question_attempt($slot)->get_correct_response();
544 }
545
546 /**
547 * Finish the active phase of an attempt at a question.
548 *
549 * This is an external act of finishing the attempt. Think, for example, of
550 * the 'Submit all and finish' button in the quiz. Some behaviours,
551 * (for example, immediatefeedback) give a way of finishing the active phase
552 * of a question attempt as part of a {@link process_action()} call.
553 *
554 * After the active phase is over, the only changes possible are things like
555 * manual grading, or changing the flag state.
556 *
557 * @param int $slot the number used to identify this question within this usage.
558 */
559 public function finish_question($slot, $timestamp = null) {
560 $qa = $this->get_question_attempt($slot);
561 $qa->finish($timestamp);
562 $this->observer->notify_attempt_modified($qa);
563 }
564
565 /**
566 * Finish the active phase of an attempt at a question. See {@link finish_question()}
567 * for a fuller description of what 'finish' means.
568 */
569 public function finish_all_questions($timestamp = null) {
570 foreach ($this->questionattempts as $qa) {
571 $qa->finish($timestamp);
572 $this->observer->notify_attempt_modified($qa);
573 }
574 }
575
576 /**
577 * Perform a manual grading action on a question attempt.
578 * @param int $slot the number used to identify this question within this usage.
579 * @param string $comment the comment being added to the question attempt.
580 * @param number $mark the mark that is being assigned. Can be null to just
581 * add a comment.
582 */
583 public function manual_grade($slot, $comment, $mark) {
584 $qa = $this->get_question_attempt($slot);
585 $qa->manual_grade($comment, $mark);
586 $this->observer->notify_attempt_modified($qa);
587 }
588
589 /**
590 * Regrade a question in this usage. This replays the sequence of submitted
591 * actions to recompute the outcomes.
592 * @param int $slot the number used to identify this question within this usage.
593 * @param bool $finished whether the question attempt should be forced to be finished
594 * after the regrade, or whether it may still be in progress (default false).
595 * @param number $newmaxmark (optional) if given, will change the max mark while regrading.
596 */
597 public function regrade_question($slot, $finished = false, $newmaxmark = null) {
598 $oldqa = $this->get_question_attempt($slot);
599 if (is_null($newmaxmark)) {
600 $newmaxmark = $oldqa->get_max_mark();
601 }
602
603 $this->observer->notify_delete_attempt_steps($oldqa);
604
605 $newqa = new question_attempt($oldqa->get_question(), $oldqa->get_usage_id(),
606 $this->observer, $newmaxmark);
607 $newqa->set_database_id($oldqa->get_database_id());
608 $newqa->regrade($oldqa, $finished);
609
610 $this->questionattempts[$slot] = $newqa;
611 $this->observer->notify_attempt_modified($newqa);
612 }
613
614 /**
615 * Regrade all the questions in this usage (without changing their max mark).
616 * @param bool $finished whether each question should be forced to be finished
617 * after the regrade, or whether it may still be in progress (default false).
618 */
619 public function regrade_all_questions($finished = false) {
620 foreach ($this->questionattempts as $slot => $notused) {
621 $this->regrade_question($slot, $finished);
622 }
623 }
624
625 /**
626 * Create a question_usage_by_activity from records loaded from the database.
627 *
628 * For internal use only.
629 *
630 * @param array $records Raw records loaded from the database.
631 * @param int $questionattemptid The id of the question_attempt to extract.
632 * @return question_attempt The newly constructed question_attempt_step.
633 */
634 public static function load_from_records(&$records, $qubaid) {
635 $record = current($records);
636 while ($record->qubaid != $qubaid) {
637 $record = next($records);
638 if (!$record) {
639 throw new coding_exception("Question usage $qubaid not found in the database.");
640 }
641 }
642
643 $quba = new question_usage_by_activity($record->component,
644 get_context_instance_by_id($record->contextid));
645 $quba->set_id_from_database($record->qubaid);
646 $quba->set_preferred_behaviour($record->preferredbehaviour);
647
648 $quba->observer = new question_engine_unit_of_work($quba);
649
650 while ($record && $record->qubaid == $qubaid && !is_null($record->slot)) {
651 $quba->questionattempts[$record->slot] =
652 question_attempt::load_from_records($records,
653 $record->questionattemptid, $quba->observer,
654 $quba->get_preferred_behaviour());
655 $record = current($records);
656 }
657
658 return $quba;
659 }
660}
661
662
663/**
664 * A class abstracting access to the
665 * {@link question_usage_by_activity::$questionattempts} array.
666 *
667 * This class snapshots the list of {@link question_attempts} to iterate over
668 * when it is created. If a question is added to the usage mid-iteration, it
669 * will now show up.
670 *
671 * To create an instance of this class, use
672 * {@link question_usage_by_activity::get_attempt_iterator()}
673 *
674 * @copyright 2009 The Open University
675 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
676 */
677class question_attempt_iterator implements Iterator, ArrayAccess {
678 /** @var question_usage_by_activity that we are iterating over. */
679 protected $quba;
680 /** @var array of question numbers. */
681 protected $slots;
682
683 /**
684 * To create an instance of this class, use {@link question_usage_by_activity::get_attempt_iterator()}.
685 * @param $quba the usage to iterate over.
686 */
687 public function __construct(question_usage_by_activity $quba) {
688 $this->quba = $quba;
689 $this->slots = $quba->get_slots();
690 $this->rewind();
691 }
692
693 /** @return question_attempt_step */
694 public function current() {
695 return $this->offsetGet(current($this->slots));
696 }
697 /** @return int */
698 public function key() {
699 return current($this->slots);
700 }
701 public function next() {
702 next($this->slots);
703 }
704 public function rewind() {
705 reset($this->slots);
706 }
707 /** @return bool */
708 public function valid() {
709 return current($this->slots) !== false;
710 }
711
712 /** @return bool */
713 public function offsetExists($slot) {
714 return in_array($slot, $this->slots);
715 }
716 /** @return question_attempt_step */
717 public function offsetGet($slot) {
718 return $this->quba->get_question_attempt($slot);
719 }
720 public function offsetSet($slot, $value) {
721 throw new coding_exception('You are only allowed read-only access to question_attempt::states through a question_attempt_step_iterator. Cannot set.');
722 }
723 public function offsetUnset($slot) {
724 throw new coding_exception('You are only allowed read-only access to question_attempt::states through a question_attempt_step_iterator. Cannot unset.');
725 }
726}
727
728
729/**
730 * Interface for things that want to be notified of signficant changes to a
731 * {@link question_usage_by_activity}.
732 *
733 * A question behaviour controls the flow of actions a student can
734 * take as they work through a question, and later, as a teacher manually grades it.
735 *
736 * @copyright 2009 The Open University
737 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
738 */
739interface question_usage_observer {
740 /** Called when a field of the question_usage_by_activity is changed. */
741 public function notify_modified();
742
743 /**
744 * Called when the fields of a question attempt in this usage are modified.
745 * @param question_attempt $qa the newly added question attempt.
746 */
747 public function notify_attempt_modified(question_attempt $qa);
748
749 /**
750 * Called when a new question attempt is added to this usage.
751 * @param question_attempt $qa the newly added question attempt.
752 */
753 public function notify_attempt_added(question_attempt $qa);
754
755 /**
756 * Called we want to delete the old step records for an attempt, prior to
757 * inserting newones. This is used by regrading.
758 * @param question_attempt $qa the question attempt to delete the steps for.
759 */
760 public function notify_delete_attempt_steps(question_attempt $qa);
761
762 /**
763 * Called when a new step is added to a question attempt in this usage.
764 * @param $step the new step.
765 * @param $qa the usage it is being added to.
766 * @param $seq the sequence number of the new step.
767 */
768 public function notify_step_added(question_attempt_step $step, question_attempt $qa, $seq);
769}
770
771
772/**
773 * Null implmentation of the {@link question_usage_watcher} interface.
774 * Does nothing.
775 *
776 * @copyright 2009 The Open University
777 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
778 */
779class question_usage_null_observer implements question_usage_observer {
780 public function notify_modified() {
781 }
782 public function notify_attempt_modified(question_attempt $qa) {
783 }
784 public function notify_attempt_added(question_attempt $qa) {
785 }
786 public function notify_delete_attempt_steps(question_attempt $qa) {
787 }
788 public function notify_step_added(question_attempt_step $step, question_attempt $qa, $seq) {
789 }
790}