weekly release 2.9dev
[moodle.git] / question / engine / questionusage.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 usage 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 * This class keeps track of a group of questions that are being attempted,
32 * and which state, and so on, each one is currently in.
33 *
34 * A quiz attempt or a lesson attempt could use an instance of this class to
35 * keep track of all the questions in the attempt and process student submissions.
36 * It is basically a collection of {@question_attempt} objects.
37 *
38 * The questions being attempted as part of this usage are identified by an integer
39 * that is passed into many of the methods as $slot. ($question->id is not
40 * used so that the same question can be used more than once in an attempt.)
41 *
42 * Normally, calling code should be able to do everything it needs to be calling
43 * methods of this class. You should not normally need to get individual
44 * {@question_attempt} objects and play around with their inner workind, in code
45 * that it outside the quetsion engine.
46 *
47 * Instances of this class correspond to rows in the question_usages table.
48 *
49 * @copyright 2009 The Open University
50 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
51 */
52class question_usage_by_activity {
53 /**
54 * @var integer|string the id for this usage. If this usage was loaded from
55 * the database, then this is the database id. Otherwise a unique random
56 * string is used.
57 */
58 protected $id = null;
59
60 /**
61 * @var string name of an archetypal behaviour, that should be used
62 * by questions in this usage if possible.
63 */
64 protected $preferredbehaviour = null;
65
4c16e191 66 /** @var context the context this usage belongs to. */
dcd03928
TH
67 protected $context;
68
69 /** @var string plugin name of the plugin this usage belongs to. */
70 protected $owningcomponent;
71
72 /** @var array {@link question_attempt}s that make up this usage. */
73 protected $questionattempts = array();
74
75 /** @var question_usage_observer that tracks changes to this usage. */
76 protected $observer;
77
78 /**
79 * Create a new instance. Normally, calling code should use
80 * {@link question_engine::make_questions_usage_by_activity()} or
81 * {@link question_engine::load_questions_usage_by_activity()} rather than
82 * calling this constructor directly.
83 *
84 * @param string $component the plugin creating this attempt. For example mod_quiz.
85 * @param object $context the context this usage belongs to.
86 */
87 public function __construct($component, $context) {
88 $this->owningcomponent = $component;
89 $this->context = $context;
90 $this->observer = new question_usage_null_observer();
91 }
92
93 /**
94 * @param string $behaviour the name of an archetypal behaviour, that should
95 * be used by questions in this usage if possible.
96 */
97 public function set_preferred_behaviour($behaviour) {
98 $this->preferredbehaviour = $behaviour;
99 $this->observer->notify_modified();
100 }
101
102 /** @return string the name of the preferred behaviour. */
103 public function get_preferred_behaviour() {
104 return $this->preferredbehaviour;
105 }
106
4c16e191 107 /** @return context the context this usage belongs to. */
dcd03928
TH
108 public function get_owning_context() {
109 return $this->context;
110 }
111
112 /** @return string the name of the plugin that owns this attempt. */
113 public function get_owning_component() {
114 return $this->owningcomponent;
115 }
116
117 /** @return int|string If this usage came from the database, then the id
118 * from the question_usages table is returned. Otherwise a random string is
119 * returned. */
120 public function get_id() {
121 if (is_null($this->id)) {
122 $this->id = random_string(10);
123 }
124 return $this->id;
125 }
126
dcd03928
TH
127 /**
128 * For internal use only. Used by {@link question_engine_data_mapper} to set
129 * the id when a usage is saved to the database.
130 * @param int $id the newly determined id for this usage.
131 */
132 public function set_id_from_database($id) {
133 $this->id = $id;
134 foreach ($this->questionattempts as $qa) {
135 $qa->set_usage_id($id);
136 }
137 }
138
94815ccf
TH
139 /** @return question_usage_observer that is tracking changes made to this usage. */
140 public function get_observer() {
141 return $this->observer;
142 }
143
144 /**
145 * You should almost certainly not call this method from your code. It is for
146 * internal use only.
147 * @param question_usage_observer that should be used to tracking changes made to this usage.
148 */
149 public function set_observer($observer) {
150 $this->observer = $observer;
151 foreach ($this->questionattempts as $qa) {
152 $qa->set_observer($observer);
153 }
154 }
155
dcd03928
TH
156 /**
157 * Add another question to this usage.
158 *
159 * The added question is not started until you call {@link start_question()}
160 * on it.
161 *
162 * @param question_definition $question the question to add.
163 * @param number $maxmark the maximum this question will be marked out of in
164 * this attempt (optional). If not given, $question->defaultmark is used.
165 * @return int the number used to identify this question within this usage.
166 */
167 public function add_question(question_definition $question, $maxmark = null) {
168 $qa = new question_attempt($question, $this->get_id(), $this->observer, $maxmark);
c2f2e7f0
JP
169 $qa->set_slot($this->next_slot_number());
170 $this->questionattempts[$this->next_slot_number()] = $qa;
dcd03928
TH
171 $this->observer->notify_attempt_added($qa);
172 return $qa->get_slot();
173 }
174
c2f2e7f0
JP
175 /**
176 * The slot number that will be allotted to the next question added.
177 */
178 public function next_slot_number() {
179 return count($this->questionattempts) + 1;
180 }
181
dcd03928
TH
182 /**
183 * Get the question_definition for a question in this attempt.
184 * @param int $slot the number used to identify this question within this usage.
185 * @return question_definition the requested question object.
186 */
187 public function get_question($slot) {
188 return $this->get_question_attempt($slot)->get_question();
189 }
190
191 /** @return array all the identifying numbers of all the questions in this usage. */
192 public function get_slots() {
193 return array_keys($this->questionattempts);
194 }
195
196 /** @return int the identifying number of the first question that was added to this usage. */
197 public function get_first_question_number() {
198 reset($this->questionattempts);
199 return key($this->questionattempts);
200 }
201
202 /** @return int the number of questions that are currently in this usage. */
203 public function question_count() {
204 return count($this->questionattempts);
205 }
206
207 /**
208 * Note the part of the {@link question_usage_by_activity} comment that explains
209 * that {@link question_attempt} objects should be considered part of the inner
210 * workings of the question engine, and should not, if possible, be accessed directly.
211 *
212 * @return question_attempt_iterator for iterating over all the questions being
213 * attempted. as part of this usage.
214 */
215 public function get_attempt_iterator() {
216 return new question_attempt_iterator($this);
217 }
218
219 /**
220 * Check whether $number actually corresponds to a question attempt that is
221 * part of this usage. Throws an exception if not.
222 *
223 * @param int $slot a number allegedly identifying a question within this usage.
224 */
225 protected function check_slot($slot) {
226 if (!array_key_exists($slot, $this->questionattempts)) {
9c197f44
TH
227 throw new coding_exception('There is no question_attempt number ' . $slot .
228 ' in this attempt.');
dcd03928
TH
229 }
230 }
231
232 /**
233 * Note the part of the {@link question_usage_by_activity} comment that explains
234 * that {@link question_attempt} objects should be considered part of the inner
235 * workings of the question engine, and should not, if possible, be accessed directly.
236 *
237 * @param int $slot the number used to identify this question within this usage.
238 * @return question_attempt the corresponding {@link question_attempt} object.
239 */
240 public function get_question_attempt($slot) {
241 $this->check_slot($slot);
242 return $this->questionattempts[$slot];
243 }
244
245 /**
246 * Get the current state of the attempt at a question.
247 * @param int $slot the number used to identify this question within this usage.
248 * @return question_state.
249 */
250 public function get_question_state($slot) {
251 return $this->get_question_attempt($slot)->get_state();
252 }
253
254 /**
255 * @param int $slot the number used to identify this question within this usage.
256 * @param bool $showcorrectness Whether right/partial/wrong states should
257 * be distinguised.
258 * @return string A brief textual description of the current state.
259 */
260 public function get_question_state_string($slot, $showcorrectness) {
261 return $this->get_question_attempt($slot)->get_state_string($showcorrectness);
262 }
263
97cdc1de
TH
264 /**
265 * @param int $slot the number used to identify this question within this usage.
266 * @param bool $showcorrectness Whether right/partial/wrong states should
267 * be distinguised.
268 * @return string a CSS class name for the current state.
269 */
270 public function get_question_state_class($slot, $showcorrectness) {
271 return $this->get_question_attempt($slot)->get_state_class($showcorrectness);
272 }
273
dcd03928
TH
274 /**
275 * Get the time of the most recent action performed on a question.
276 * @param int $slot the number used to identify this question within this usage.
277 * @return int timestamp.
278 */
279 public function get_question_action_time($slot) {
280 return $this->get_question_attempt($slot)->get_last_action_time();
281 }
282
283 /**
284 * Get the current fraction awarded for the attempt at a question.
285 * @param int $slot the number used to identify this question within this usage.
286 * @return number|null The current fraction for this question, or null if one has
287 * not been assigned yet.
288 */
289 public function get_question_fraction($slot) {
290 return $this->get_question_attempt($slot)->get_fraction();
291 }
292
293 /**
294 * Get the current mark awarded for the attempt at a question.
295 * @param int $slot the number used to identify this question within this usage.
296 * @return number|null The current mark for this question, or null if one has
297 * not been assigned yet.
298 */
299 public function get_question_mark($slot) {
300 return $this->get_question_attempt($slot)->get_mark();
301 }
302
303 /**
304 * Get the maximum mark possible for the attempt at a question.
305 * @param int $slot the number used to identify this question within this usage.
306 * @return number the available marks for this question.
307 */
308 public function get_question_max_mark($slot) {
309 return $this->get_question_attempt($slot)->get_max_mark();
310 }
311
312 /**
a7b4c964
TH
313 * Get the total mark for all questions in this usage.
314 * @return number The sum of marks of all the question_attempts in this usage.
dcd03928
TH
315 */
316 public function get_total_mark() {
317 $mark = 0;
318 foreach ($this->questionattempts as $qa) {
319 if ($qa->get_max_mark() > 0 && $qa->get_state() == question_state::$needsgrading) {
320 return null;
321 }
322 $mark += $qa->get_mark();
323 }
324 return $mark;
325 }
326
474aa125
TH
327 /**
328 * Get summary information about this usage.
329 *
330 * Some behaviours may be able to provide interesting summary information
331 * about the attempt as a whole, and this method provides access to that data.
332 * To see how this works, try setting a quiz to one of the CBM behaviours,
333 * and then look at the extra information displayed at the top of the quiz
334 * review page once you have sumitted an attempt.
335 *
336 * In the return value, the array keys are identifiers of the form
337 * qbehaviour_behaviourname_meaningfullkey. For qbehaviour_deferredcbm_highsummary.
338 * The values are arrays with two items, title and content. Each of these
339 * will be either a string, or a renderable.
340 *
474aa125
TH
341 * @return array as described above.
342 */
343 public function get_summary_information(question_display_options $options) {
344 return question_engine::get_behaviour_type($this->preferredbehaviour)
345 ->summarise_usage($this, $options);
346 }
347
dcd03928
TH
348 /**
349 * @return string a simple textual summary of the question that was asked.
350 */
351 public function get_question_summary($slot) {
352 return $this->get_question_attempt($slot)->get_question_summary();
353 }
354
355 /**
356 * @return string a simple textual summary of response given.
357 */
358 public function get_response_summary($slot) {
359 return $this->get_question_attempt($slot)->get_response_summary();
360 }
361
362 /**
363 * @return string a simple textual summary of the correct resonse.
364 */
365 public function get_right_answer_summary($slot) {
366 return $this->get_question_attempt($slot)->get_right_answer_summary();
367 }
368
369 /**
370 * Get the {@link core_question_renderer}, in collaboration with appropriate
371 * {@link qbehaviour_renderer} and {@link qtype_renderer} subclasses, to generate the
372 * HTML to display this question.
373 * @param int $slot the number used to identify this question within this usage.
374 * @param question_display_options $options controls how the question is rendered.
375 * @param string|null $number The question number to display. 'i' is a special
376 * value that gets displayed as Information. Null means no number is displayed.
377 * @return string HTML fragment representing the question.
378 */
379 public function render_question($slot, $options, $number = null) {
380 $options->context = $this->context;
381 return $this->get_question_attempt($slot)->render($options, $number);
382 }
383
384 /**
385 * Generate any bits of HTML that needs to go in the <head> tag when this question
386 * is displayed in the body.
387 * @param int $slot the number used to identify this question within this usage.
388 * @return string HTML fragment.
389 */
390 public function render_question_head_html($slot) {
92701024 391 //$options->context = $this->context;
dcd03928
TH
392 return $this->get_question_attempt($slot)->render_head_html();
393 }
394
395 /**
396 * Like {@link render_question()} but displays the question at the past step
397 * indicated by $seq, rather than showing the latest step.
398 *
399 * @param int $slot the number used to identify this question within this usage.
400 * @param int $seq the seq number of the past state to display.
401 * @param question_display_options $options controls how the question is rendered.
402 * @param string|null $number The question number to display. 'i' is a special
403 * value that gets displayed as Information. Null means no number is displayed.
404 * @return string HTML fragment representing the question.
405 */
406 public function render_question_at_step($slot, $seq, $options, $number = null) {
407 $options->context = $this->context;
9c197f44
TH
408 return $this->get_question_attempt($slot)->render_at_step(
409 $seq, $options, $number, $this->preferredbehaviour);
dcd03928
TH
410 }
411
412 /**
413 * Checks whether the users is allow to be served a particular file.
414 * @param int $slot the number used to identify this question within this usage.
415 * @param question_display_options $options the options that control display of the question.
416 * @param string $component the name of the component we are serving files for.
417 * @param string $filearea the name of the file area.
418 * @param array $args the remaining bits of the file path.
419 * @param bool $forcedownload whether the user must be forced to download the file.
420 * @return bool true if the user can access this file.
421 */
9c197f44
TH
422 public function check_file_access($slot, $options, $component, $filearea,
423 $args, $forcedownload) {
424 return $this->get_question_attempt($slot)->check_file_access(
425 $options, $component, $filearea, $args, $forcedownload);
dcd03928
TH
426 }
427
428 /**
429 * Replace a particular question_attempt with a different one.
430 *
431 * For internal use only. Used when reloading the state of a question from the
432 * database.
433 *
434 * @param array $records Raw records loaded from the database.
435 * @param int $questionattemptid The id of the question_attempt to extract.
436 * @return question_attempt The newly constructed question_attempt_step.
437 */
438 public function replace_loaded_question_attempt_info($slot, $qa) {
439 $this->check_slot($slot);
440 $this->questionattempts[$slot] = $qa;
441 }
442
443 /**
444 * You should probably not use this method in code outside the question engine.
445 * The main reason for exposing it was for the benefit of unit tests.
446 * @param int $slot the number used to identify this question within this usage.
447 * @return string return the prefix that is pre-pended to field names in the HTML
448 * that is output.
449 */
450 public function get_field_prefix($slot) {
451 return $this->get_question_attempt($slot)->get_field_prefix();
452 }
453
1da821bb
TH
454 /**
455 * Get the number of variants available for the question in this slot.
456 * @param int $slot the number used to identify this question within this usage.
457 * @return int the number of variants available.
458 */
459 public function get_num_variants($slot) {
460 return $this->get_question_attempt($slot)->get_question()->get_num_variants();
461 }
462
463 /**
464 * Get the variant of the question being used in a given slot.
465 * @param int $slot the number used to identify this question within this usage.
466 * @return int the variant of this question that is being used.
467 */
468 public function get_variant($slot) {
469 return $this->get_question_attempt($slot)->get_variant();
470 }
471
dcd03928
TH
472 /**
473 * Start the attempt at a question that has been added to this usage.
474 * @param int $slot the number used to identify this question within this usage.
1da821bb
TH
475 * @param int $variant which variant of the question to use. Must be between
476 * 1 and ->get_num_variants($slot) inclusive. If not give, a variant is
477 * chosen at random.
dcd03928 478 */
1da821bb
TH
479 public function start_question($slot, $variant = null) {
480 if (is_null($variant)) {
481 $variant = rand(1, $this->get_num_variants($slot));
482 }
483
dcd03928 484 $qa = $this->get_question_attempt($slot);
1da821bb 485 $qa->start($this->preferredbehaviour, $variant);
dcd03928
TH
486 $this->observer->notify_attempt_modified($qa);
487 }
488
489 /**
490 * Start the attempt at all questions that has been added to this usage.
1da821bb 491 * @param question_variant_selection_strategy how to pick which variant of each question to use.
e35ba43c
TH
492 * @param int $timestamp optional, the timstamp to record for this action. Defaults to now.
493 * @param int $userid optional, the user to attribute this action to. Defaults to the current user.
dcd03928 494 */
1da821bb
TH
495 public function start_all_questions(question_variant_selection_strategy $variantstrategy = null,
496 $timestamp = null, $userid = null) {
497 if (is_null($variantstrategy)) {
498 $variantstrategy = new question_variant_random_strategy();
499 }
500
dcd03928 501 foreach ($this->questionattempts as $qa) {
1da821bb 502 $qa->start($this->preferredbehaviour, $qa->select_variant($variantstrategy));
dcd03928
TH
503 $this->observer->notify_attempt_modified($qa);
504 }
505 }
506
507 /**
508 * Start the attempt at a question, starting from the point where the previous
509 * question_attempt $oldqa had reached. This is used by the quiz 'Each attempt
510 * builds on last' mode.
511 * @param int $slot the number used to identify this question within this usage.
512 * @param question_attempt $oldqa a previous attempt at this quetsion that
513 * defines the starting point.
514 */
515 public function start_question_based_on($slot, question_attempt $oldqa) {
516 $qa = $this->get_question_attempt($slot);
517 $qa->start_based_on($oldqa);
518 $this->observer->notify_attempt_modified($qa);
519 }
520
521 /**
522 * Process all the question actions in the current request.
523 *
524 * If there is a parameter slots included in the post data, then only
525 * those question numbers will be processed, otherwise all questions in this
526 * useage will be.
527 *
528 * This function also does {@link update_question_flags()}.
529 *
530 * @param int $timestamp optional, use this timestamp as 'now'.
531 * @param array $postdata optional, only intended for testing. Use this data
532 * instead of the data from $_POST.
533 */
534 public function process_all_actions($timestamp = null, $postdata = null) {
0a606a2b
TH
535 foreach ($this->get_slots_in_request($postdata) as $slot) {
536 if (!$this->validate_sequence_number($slot, $postdata)) {
537 continue;
538 }
539 $submitteddata = $this->extract_responses($slot, $postdata);
540 $this->process_action($slot, $submitteddata, $timestamp);
541 }
542 $this->update_question_flags($postdata);
543 }
544
545 /**
546 * Process all the question autosave data in the current request.
547 *
548 * If there is a parameter slots included in the post data, then only
549 * those question numbers will be processed, otherwise all questions in this
550 * useage will be.
551 *
552 * This function also does {@link update_question_flags()}.
553 *
554 * @param int $timestamp optional, use this timestamp as 'now'.
555 * @param array $postdata optional, only intended for testing. Use this data
556 * instead of the data from $_POST.
557 */
558 public function process_all_autosaves($timestamp = null, $postdata = null) {
559 foreach ($this->get_slots_in_request($postdata) as $slot) {
560 if (!$this->is_autosave_required($slot, $postdata)) {
561 continue;
562 }
563 $submitteddata = $this->extract_responses($slot, $postdata);
564 $this->process_autosave($slot, $submitteddata, $timestamp);
565 }
566 $this->update_question_flags($postdata);
567 }
568
569 /**
570 * Get the list of slot numbers that should be processed as part of processing
571 * the current request.
572 * @param array $postdata optional, only intended for testing. Use this data
573 * instead of the data from $_POST.
574 * @return array of slot numbers.
575 */
576 protected function get_slots_in_request($postdata = null) {
577 // Note: we must not use "question_attempt::get_submitted_var()" because there is no attempt instance!!!
caee6e6c
PS
578 if (is_null($postdata)) {
579 $slots = optional_param('slots', null, PARAM_SEQUENCE);
580 } else if (array_key_exists('slots', $postdata)) {
581 $slots = clean_param($postdata['slots'], PARAM_SEQUENCE);
582 } else {
583 $slots = null;
584 }
dcd03928
TH
585 if (is_null($slots)) {
586 $slots = $this->get_slots();
587 } else if (!$slots) {
588 $slots = array();
589 } else {
590 $slots = explode(',', $slots);
591 }
0a606a2b 592 return $slots;
dcd03928
TH
593 }
594
595 /**
596 * Get the submitted data from the current request that belongs to this
597 * particular question.
598 *
599 * @param int $slot the number used to identify this question within this usage.
600 * @param $postdata optional, only intended for testing. Use this data
601 * instead of the data from $_POST.
602 * @return array submitted data specific to this question.
603 */
604 public function extract_responses($slot, $postdata = null) {
605 return $this->get_question_attempt($slot)->get_submitted_data($postdata);
606 }
607
388f0473
JP
608 /**
609 * Transform an array of response data for slots to an array of post data as you would get from quiz attempt form.
610 *
611 * @param $simulatedresponses array keys are slot nos => contains arrays representing student
612 * responses which will be passed to question_definition::prepare_simulated_post_data method
613 * and then have the appropriate prefix added.
614 * @return array simulated post data
615 */
616 public function prepare_simulated_post_data($simulatedresponses) {
617 $simulatedpostdata = array();
618 $simulatedpostdata['slots'] = implode(',', array_keys($simulatedresponses));
619 foreach ($simulatedresponses as $slot => $responsedata) {
764f6153
JP
620 $slotresponse = array();
621
622 // Behaviour vars should not be processed by question type, just add prefix.
623 $behaviourvars = $this->get_question_attempt($slot)->get_behaviour()->get_expected_data();
99caa248
JP
624 foreach (array_keys($responsedata) as $responsedatakey) {
625 if ($responsedatakey{0} === '-') {
626 $behaviourvarname = substr($responsedatakey, 1);
627 if (isset($behaviourvars[$behaviourvarname])) {
628 // Expected behaviour var found.
629 if ($responsedata[$responsedatakey]) {
630 // Only set the behaviour var if the column value from the cvs file is non zero.
631 // The behaviours only look at whether the var is set or not they don't look at the value.
632 $slotresponse[$responsedatakey] = $responsedata[$responsedatakey];
633 }
634 }
635 // Remove both expected and unexpected vars from data passed to question type.
636 unset($responsedata[$responsedatakey]);
764f6153
JP
637 }
638 }
639
640 $slotresponse += $this->get_question($slot)->prepare_simulated_post_data($responsedata);
99caa248 641 $slotresponse[':sequencecheck'] = $this->get_question_attempt($slot)->get_sequence_check_count();
764f6153
JP
642
643 // Add this slot's prefix to slot data.
644 $prefix = $this->get_field_prefix($slot);
388f0473
JP
645 foreach ($slotresponse as $key => $value) {
646 $simulatedpostdata[$prefix.$key] = $value;
647 }
648 }
649 return $simulatedpostdata;
650 }
651
dcd03928
TH
652 /**
653 * Process a specific action on a specific question.
654 * @param int $slot the number used to identify this question within this usage.
655 * @param $submitteddata the submitted data that constitutes the action.
656 */
657 public function process_action($slot, $submitteddata, $timestamp = null) {
658 $qa = $this->get_question_attempt($slot);
659 $qa->process_action($submitteddata, $timestamp);
660 $this->observer->notify_attempt_modified($qa);
661 }
662
0a606a2b
TH
663 /**
664 * Process an autosave action on a specific question.
665 * @param int $slot the number used to identify this question within this usage.
666 * @param $submitteddata the submitted data that constitutes the action.
667 */
668 public function process_autosave($slot, $submitteddata, $timestamp = null) {
669 $qa = $this->get_question_attempt($slot);
670 if ($qa->process_autosave($submitteddata, $timestamp)) {
671 $this->observer->notify_attempt_modified($qa);
672 }
673 }
674
dcd03928
TH
675 /**
676 * Check that the sequence number, that detects weird things like the student
677 * clicking back, is OK. If the sequence check variable is not present, returns
678 * false. If the check variable is present and correct, returns true. If the
679 * variable is present and wrong, throws an exception.
680 * @param int $slot the number used to identify this question within this usage.
681 * @param array $submitteddata the submitted data that constitutes the action.
682 * @return bool true if the check variable is present and correct. False if it
683 * is missing. (Throws an exception if the check fails.)
684 */
685 public function validate_sequence_number($slot, $postdata = null) {
686 $qa = $this->get_question_attempt($slot);
687 $sequencecheck = $qa->get_submitted_var(
688 $qa->get_control_field_name('sequencecheck'), PARAM_INT, $postdata);
689 if (is_null($sequencecheck)) {
690 return false;
c7fbfe46 691 } else if ($sequencecheck != $qa->get_sequence_check_count()) {
dcd03928
TH
692 throw new question_out_of_sequence_exception($this->id, $slot, $postdata);
693 } else {
694 return true;
695 }
696 }
d122fe32
TH
697
698 /**
699 * Check, based on the sequence number, whether this auto-save is still required.
700 * @param int $slot the number used to identify this question within this usage.
701 * @param array $submitteddata the submitted data that constitutes the action.
702 * @return bool true if the check variable is present and correct, otherwise false.
703 */
704 public function is_autosave_required($slot, $postdata = null) {
705 $qa = $this->get_question_attempt($slot);
706 $sequencecheck = $qa->get_submitted_var(
707 $qa->get_control_field_name('sequencecheck'), PARAM_INT, $postdata);
708 if (is_null($sequencecheck)) {
709 return false;
c7fbfe46 710 } else if ($sequencecheck != $qa->get_sequence_check_count()) {
d122fe32
TH
711 return false;
712 } else {
713 return true;
714 }
715 }
716
dcd03928
TH
717 /**
718 * Update the flagged state for all question_attempts in this usage, if their
719 * flagged state was changed in the request.
720 *
721 * @param $postdata optional, only intended for testing. Use this data
722 * instead of the data from $_POST.
723 */
724 public function update_question_flags($postdata = null) {
725 foreach ($this->questionattempts as $qa) {
726 $flagged = $qa->get_submitted_var(
727 $qa->get_flag_field_name(), PARAM_BOOL, $postdata);
728 if (!is_null($flagged) && $flagged != $qa->is_flagged()) {
729 $qa->set_flagged($flagged);
730 }
731 }
732 }
733
734 /**
735 * Get the correct response to a particular question. Passing the results of
736 * this method to {@link process_action()} will probably result in full marks.
da22c012 737 * If it is not possible to compute a correct response, this method should return null.
dcd03928
TH
738 * @param int $slot the number used to identify this question within this usage.
739 * @return array that constitutes a correct response to this question.
740 */
741 public function get_correct_response($slot) {
742 return $this->get_question_attempt($slot)->get_correct_response();
743 }
744
745 /**
746 * Finish the active phase of an attempt at a question.
747 *
748 * This is an external act of finishing the attempt. Think, for example, of
749 * the 'Submit all and finish' button in the quiz. Some behaviours,
750 * (for example, immediatefeedback) give a way of finishing the active phase
751 * of a question attempt as part of a {@link process_action()} call.
752 *
753 * After the active phase is over, the only changes possible are things like
754 * manual grading, or changing the flag state.
755 *
756 * @param int $slot the number used to identify this question within this usage.
757 */
758 public function finish_question($slot, $timestamp = null) {
759 $qa = $this->get_question_attempt($slot);
760 $qa->finish($timestamp);
761 $this->observer->notify_attempt_modified($qa);
762 }
763
764 /**
765 * Finish the active phase of an attempt at a question. See {@link finish_question()}
766 * for a fuller description of what 'finish' means.
767 */
768 public function finish_all_questions($timestamp = null) {
769 foreach ($this->questionattempts as $qa) {
770 $qa->finish($timestamp);
771 $this->observer->notify_attempt_modified($qa);
772 }
773 }
774
775 /**
776 * Perform a manual grading action on a question attempt.
777 * @param int $slot the number used to identify this question within this usage.
778 * @param string $comment the comment being added to the question attempt.
779 * @param number $mark the mark that is being assigned. Can be null to just
780 * add a comment.
770e4a46 781 * @param int $commentformat one of the FORMAT_... constants. The format of $comment.
dcd03928 782 */
53b8e256 783 public function manual_grade($slot, $comment, $mark, $commentformat = null) {
dcd03928 784 $qa = $this->get_question_attempt($slot);
53b8e256 785 $qa->manual_grade($comment, $mark, $commentformat);
dcd03928
TH
786 $this->observer->notify_attempt_modified($qa);
787 }
788
789 /**
790 * Regrade a question in this usage. This replays the sequence of submitted
791 * actions to recompute the outcomes.
792 * @param int $slot the number used to identify this question within this usage.
793 * @param bool $finished whether the question attempt should be forced to be finished
794 * after the regrade, or whether it may still be in progress (default false).
795 * @param number $newmaxmark (optional) if given, will change the max mark while regrading.
796 */
797 public function regrade_question($slot, $finished = false, $newmaxmark = null) {
798 $oldqa = $this->get_question_attempt($slot);
799 if (is_null($newmaxmark)) {
800 $newmaxmark = $oldqa->get_max_mark();
801 }
802
dcd03928
TH
803 $newqa = new question_attempt($oldqa->get_question(), $oldqa->get_usage_id(),
804 $this->observer, $newmaxmark);
805 $newqa->set_database_id($oldqa->get_database_id());
94815ccf 806 $newqa->set_slot($oldqa->get_slot());
dcd03928
TH
807 $newqa->regrade($oldqa, $finished);
808
809 $this->questionattempts[$slot] = $newqa;
810 $this->observer->notify_attempt_modified($newqa);
811 }
812
813 /**
814 * Regrade all the questions in this usage (without changing their max mark).
815 * @param bool $finished whether each question should be forced to be finished
816 * after the regrade, or whether it may still be in progress (default false).
817 */
818 public function regrade_all_questions($finished = false) {
819 foreach ($this->questionattempts as $slot => $notused) {
820 $this->regrade_question($slot, $finished);
821 }
822 }
823
824 /**
825 * Create a question_usage_by_activity from records loaded from the database.
826 *
827 * For internal use only.
828 *
35d5f1c2 829 * @param Iterator $records Raw records loaded from the database.
dcd03928 830 * @param int $questionattemptid The id of the question_attempt to extract.
94815ccf 831 * @return question_usage_by_activity The newly constructed usage.
dcd03928 832 */
35d5f1c2
TH
833 public static function load_from_records($records, $qubaid) {
834 $record = $records->current();
dcd03928 835 while ($record->qubaid != $qubaid) {
35d5f1c2
TH
836 $records->next();
837 if (!$records->valid()) {
f4fe3968 838 throw new coding_exception("Question usage {$qubaid} not found in the database.");
dcd03928 839 }
35d5f1c2 840 $record = $records->current();
dcd03928
TH
841 }
842
843 $quba = new question_usage_by_activity($record->component,
2cdd5d85 844 context::instance_by_id($record->contextid, IGNORE_MISSING));
dcd03928
TH
845 $quba->set_id_from_database($record->qubaid);
846 $quba->set_preferred_behaviour($record->preferredbehaviour);
847
848 $quba->observer = new question_engine_unit_of_work($quba);
849
dd7aa583
TH
850 // If slot is null then the current pointer in $records will not be
851 // advanced in the while loop below, and we get stuck in an infinite loop,
852 // since this method is supposed to always consume at least one record.
853 // Therefore, in this case, advance the record here.
854 if (is_null($record->slot)) {
855 $records->next();
856 }
857
dcd03928
TH
858 while ($record && $record->qubaid == $qubaid && !is_null($record->slot)) {
859 $quba->questionattempts[$record->slot] =
860 question_attempt::load_from_records($records,
861 $record->questionattemptid, $quba->observer,
862 $quba->get_preferred_behaviour());
35d5f1c2
TH
863 if ($records->valid()) {
864 $record = $records->current();
865 } else {
866 $record = false;
867 }
dcd03928
TH
868 }
869
870 return $quba;
871 }
872}
873
874
875/**
876 * A class abstracting access to the
877 * {@link question_usage_by_activity::$questionattempts} array.
878 *
879 * This class snapshots the list of {@link question_attempts} to iterate over
880 * when it is created. If a question is added to the usage mid-iteration, it
881 * will now show up.
882 *
883 * To create an instance of this class, use
884 * {@link question_usage_by_activity::get_attempt_iterator()}
885 *
886 * @copyright 2009 The Open University
887 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
888 */
889class question_attempt_iterator implements Iterator, ArrayAccess {
890 /** @var question_usage_by_activity that we are iterating over. */
891 protected $quba;
892 /** @var array of question numbers. */
893 protected $slots;
894
895 /**
9c197f44
TH
896 * To create an instance of this class, use
897 * {@link question_usage_by_activity::get_attempt_iterator()}.
dcd03928
TH
898 * @param $quba the usage to iterate over.
899 */
900 public function __construct(question_usage_by_activity $quba) {
901 $this->quba = $quba;
902 $this->slots = $quba->get_slots();
903 $this->rewind();
904 }
905
906 /** @return question_attempt_step */
907 public function current() {
908 return $this->offsetGet(current($this->slots));
909 }
910 /** @return int */
911 public function key() {
912 return current($this->slots);
913 }
914 public function next() {
915 next($this->slots);
916 }
917 public function rewind() {
918 reset($this->slots);
919 }
920 /** @return bool */
921 public function valid() {
922 return current($this->slots) !== false;
923 }
924
925 /** @return bool */
926 public function offsetExists($slot) {
927 return in_array($slot, $this->slots);
928 }
929 /** @return question_attempt_step */
930 public function offsetGet($slot) {
931 return $this->quba->get_question_attempt($slot);
932 }
933 public function offsetSet($slot, $value) {
9c197f44
TH
934 throw new coding_exception('You are only allowed read-only access to ' .
935 'question_attempt::states through a question_attempt_step_iterator. Cannot set.');
dcd03928
TH
936 }
937 public function offsetUnset($slot) {
9c197f44
TH
938 throw new coding_exception('You are only allowed read-only access to ' .
939 'question_attempt::states through a question_attempt_step_iterator. Cannot unset.');
dcd03928
TH
940 }
941}
942
943
944/**
945 * Interface for things that want to be notified of signficant changes to a
946 * {@link question_usage_by_activity}.
947 *
948 * A question behaviour controls the flow of actions a student can
949 * take as they work through a question, and later, as a teacher manually grades it.
950 *
951 * @copyright 2009 The Open University
952 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
953 */
954interface question_usage_observer {
955 /** Called when a field of the question_usage_by_activity is changed. */
956 public function notify_modified();
957
958 /**
959 * Called when the fields of a question attempt in this usage are modified.
960 * @param question_attempt $qa the newly added question attempt.
961 */
962 public function notify_attempt_modified(question_attempt $qa);
963
964 /**
965 * Called when a new question attempt is added to this usage.
966 * @param question_attempt $qa the newly added question attempt.
967 */
968 public function notify_attempt_added(question_attempt $qa);
969
970 /**
94815ccf
TH
971 * Called when a new step is added to a question attempt in this usage.
972 * @param question_attempt_step $step the new step.
973 * @param question_attempt $qa the usage it is being added to.
974 * @param int $seq the sequence number of the new step.
dcd03928 975 */
94815ccf 976 public function notify_step_added(question_attempt_step $step, question_attempt $qa, $seq);
dcd03928
TH
977
978 /**
94815ccf
TH
979 * Called when a new step is updated in a question attempt in this usage.
980 * @param question_attempt_step $step the step that was updated.
981 * @param question_attempt $qa the usage it is being added to.
982 * @param int $seq the sequence number of the new step.
dcd03928 983 */
94815ccf
TH
984 public function notify_step_modified(question_attempt_step $step, question_attempt $qa, $seq);
985
986 /**
987 * Called when a new step is updated in a question attempt in this usage.
988 * @param question_attempt_step $step the step to delete.
989 * @param question_attempt $qa the usage it is being added to.
990 */
991 public function notify_step_deleted(question_attempt_step $step, question_attempt $qa);
992
dcd03928
TH
993}
994
995
996/**
997 * Null implmentation of the {@link question_usage_watcher} interface.
998 * Does nothing.
999 *
1000 * @copyright 2009 The Open University
1001 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1002 */
1003class question_usage_null_observer implements question_usage_observer {
1004 public function notify_modified() {
1005 }
1006 public function notify_attempt_modified(question_attempt $qa) {
1007 }
1008 public function notify_attempt_added(question_attempt $qa) {
1009 }
dcd03928
TH
1010 public function notify_step_added(question_attempt_step $step, question_attempt $qa, $seq) {
1011 }
94815ccf
TH
1012 public function notify_step_modified(question_attempt_step $step, question_attempt $qa, $seq) {
1013 }
1014 public function notify_step_deleted(question_attempt_step $step, question_attempt $qa) {
1015 }
dcd03928 1016}