Merge branch 'MDL-67830' of https://github.com/timhunt/moodle
[moodle.git] / mod / quiz / attemptlib.php
1 <?php
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/>.
17 /**
18  * Back-end code for handling data about quizzes and the current user's attempt.
19  *
20  * There are classes for loading all the information about a quiz and attempts,
21  * and for displaying the navigation panel.
22  *
23  * @package   mod_quiz
24  * @copyright 2008 onwards Tim Hunt
25  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26  */
29 defined('MOODLE_INTERNAL') || die();
32 /**
33  * Class for quiz exceptions. Just saves a couple of arguments on the
34  * constructor for a moodle_exception.
35  *
36  * @copyright 2008 Tim Hunt
37  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
38  * @since     Moodle 2.0
39  */
40 class moodle_quiz_exception extends moodle_exception {
41     public function __construct($quizobj, $errorcode, $a = null, $link = '', $debuginfo = null) {
42         if (!$link) {
43             $link = $quizobj->view_url();
44         }
45         parent::__construct($errorcode, 'quiz', $link, $a, $debuginfo);
46     }
47 }
50 /**
51  * A class encapsulating a quiz and the questions it contains, and making the
52  * information available to scripts like view.php.
53  *
54  * Initially, it only loads a minimal amout of information about each question - loading
55  * extra information only when necessary or when asked. The class tracks which questions
56  * are loaded.
57  *
58  * @copyright  2008 Tim Hunt
59  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
60  * @since      Moodle 2.0
61  */
62 class quiz {
63     /** @var stdClass the course settings from the database. */
64     protected $course;
65     /** @var stdClass the course_module settings from the database. */
66     protected $cm;
67     /** @var stdClass the quiz settings from the database. */
68     protected $quiz;
69     /** @var context the quiz context. */
70     protected $context;
72     /** @var array of questions augmented with slot information. */
73     protected $questions = null;
74     /** @var array of quiz_section rows. */
75     protected $sections = null;
76     /** @var quiz_access_manager the access manager for this quiz. */
77     protected $accessmanager = null;
78     /** @var bool whether the current user has capability mod/quiz:preview. */
79     protected $ispreviewuser = null;
81     // Constructor =============================================================
82     /**
83      * Constructor, assuming we already have the necessary data loaded.
84      *
85      * @param object $quiz the row from the quiz table.
86      * @param object $cm the course_module object for this quiz.
87      * @param object $course the row from the course table for the course we belong to.
88      * @param bool $getcontext intended for testing - stops the constructor getting the context.
89      */
90     public function __construct($quiz, $cm, $course, $getcontext = true) {
91         $this->quiz = $quiz;
92         $this->cm = $cm;
93         $this->quiz->cmid = $this->cm->id;
94         $this->course = $course;
95         if ($getcontext && !empty($cm->id)) {
96             $this->context = context_module::instance($cm->id);
97         }
98     }
100     /**
101      * Static function to create a new quiz object for a specific user.
102      *
103      * @param int $quizid the the quiz id.
104      * @param int $userid the the userid.
105      * @return quiz the new quiz object
106      */
107     public static function create($quizid, $userid = null) {
108         global $DB;
110         $quiz = quiz_access_manager::load_quiz_and_settings($quizid);
111         $course = $DB->get_record('course', array('id' => $quiz->course), '*', MUST_EXIST);
112         $cm = get_coursemodule_from_instance('quiz', $quiz->id, $course->id, false, MUST_EXIST);
114         // Update quiz with override information.
115         if ($userid) {
116             $quiz = quiz_update_effective_access($quiz, $userid);
117         }
119         return new quiz($quiz, $cm, $course);
120     }
122     /**
123      * Create a {@link quiz_attempt} for an attempt at this quiz.
124      * @param object $attemptdata row from the quiz_attempts table.
125      * @return quiz_attempt the new quiz_attempt object.
126      */
127     public function create_attempt_object($attemptdata) {
128         return new quiz_attempt($attemptdata, $this->quiz, $this->cm, $this->course);
129     }
131     // Functions for loading more data =========================================
133     /**
134      * Load just basic information about all the questions in this quiz.
135      */
136     public function preload_questions() {
137         $this->questions = question_preload_questions(null,
138                 'slot.maxmark, slot.id AS slotid, slot.slot, slot.page,
139                  slot.questioncategoryid AS randomfromcategory,
140                  slot.includingsubcategories AS randomincludingsubcategories',
141                 '{quiz_slots} slot ON slot.quizid = :quizid AND q.id = slot.questionid',
142                 array('quizid' => $this->quiz->id), 'slot.slot');
143     }
145     /**
146      * Fully load some or all of the questions for this quiz. You must call
147      * {@link preload_questions()} first.
148      *
149      * @param array $questionids question ids of the questions to load. null for all.
150      */
151     public function load_questions($questionids = null) {
152         if ($this->questions === null) {
153             throw new coding_exception('You must call preload_questions before calling load_questions.');
154         }
155         if (is_null($questionids)) {
156             $questionids = array_keys($this->questions);
157         }
158         $questionstoprocess = array();
159         foreach ($questionids as $id) {
160             if (array_key_exists($id, $this->questions)) {
161                 $questionstoprocess[$id] = $this->questions[$id];
162             }
163         }
164         get_question_options($questionstoprocess);
165     }
167     /**
168      * Get an instance of the {@link \mod_quiz\structure} class for this quiz.
169      * @return \mod_quiz\structure describes the questions in the quiz.
170      */
171     public function get_structure() {
172         return \mod_quiz\structure::create_for_quiz($this);
173     }
175     // Simple getters ==========================================================
176     /** @return int the course id. */
177     public function get_courseid() {
178         return $this->course->id;
179     }
181     /** @return object the row of the course table. */
182     public function get_course() {
183         return $this->course;
184     }
186     /** @return int the quiz id. */
187     public function get_quizid() {
188         return $this->quiz->id;
189     }
191     /** @return object the row of the quiz table. */
192     public function get_quiz() {
193         return $this->quiz;
194     }
196     /** @return string the name of this quiz. */
197     public function get_quiz_name() {
198         return $this->quiz->name;
199     }
201     /** @return int the quiz navigation method. */
202     public function get_navigation_method() {
203         return $this->quiz->navmethod;
204     }
206     /** @return int the number of attempts allowed at this quiz (0 = infinite). */
207     public function get_num_attempts_allowed() {
208         return $this->quiz->attempts;
209     }
211     /** @return int the course_module id. */
212     public function get_cmid() {
213         return $this->cm->id;
214     }
216     /** @return object the course_module object. */
217     public function get_cm() {
218         return $this->cm;
219     }
221     /** @return object the module context for this quiz. */
222     public function get_context() {
223         return $this->context;
224     }
226     /**
227      * @return bool wether the current user is someone who previews the quiz,
228      * rather than attempting it.
229      */
230     public function is_preview_user() {
231         if (is_null($this->ispreviewuser)) {
232             $this->ispreviewuser = has_capability('mod/quiz:preview', $this->context);
233         }
234         return $this->ispreviewuser;
235     }
237     /**
238      * Checks user enrollment in the current course.
239      *
240      * @param int $userid
241      * @return null|stdClass user record
242      */
243     public function is_participant($userid) {
244         return is_enrolled($this->get_context(), $userid, 'mod/quiz:attempt', $this->show_only_active_users());
245     }
247     /**
248      * Check is only active users in course should be shown.
249      *
250      * @return bool true if only active users should be shown.
251      */
252     public function show_only_active_users() {
253         return !has_capability('moodle/course:viewsuspendedusers', $this->get_context());
254     }
256     /**
257      * @return whether any questions have been added to this quiz.
258      */
259     public function has_questions() {
260         if ($this->questions === null) {
261             $this->preload_questions();
262         }
263         return !empty($this->questions);
264     }
266     /**
267      * @param int $id the question id.
268      * @return object the question object with that id.
269      */
270     public function get_question($id) {
271         return $this->questions[$id];
272     }
274     /**
275      * @param array $questionids question ids of the questions to load. null for all.
276      */
277     public function get_questions($questionids = null) {
278         if (is_null($questionids)) {
279             $questionids = array_keys($this->questions);
280         }
281         $questions = array();
282         foreach ($questionids as $id) {
283             if (!array_key_exists($id, $this->questions)) {
284                 throw new moodle_exception('cannotstartmissingquestion', 'quiz', $this->view_url());
285             }
286             $questions[$id] = $this->questions[$id];
287             $this->ensure_question_loaded($id);
288         }
289         return $questions;
290     }
292     /**
293      * Get all the sections in this quiz.
294      * @return array 0, 1, 2, ... => quiz_sections row from the database.
295      */
296     public function get_sections() {
297         global $DB;
298         if ($this->sections === null) {
299             $this->sections = array_values($DB->get_records('quiz_sections',
300                     array('quizid' => $this->get_quizid()), 'firstslot'));
301         }
302         return $this->sections;
303     }
305     /**
306      * Return quiz_access_manager and instance of the quiz_access_manager class
307      * for this quiz at this time.
308      * @param int $timenow the current time as a unix timestamp.
309      * @return quiz_access_manager and instance of the quiz_access_manager class
310      *      for this quiz at this time.
311      */
312     public function get_access_manager($timenow) {
313         if (is_null($this->accessmanager)) {
314             $this->accessmanager = new quiz_access_manager($this, $timenow,
315                     has_capability('mod/quiz:ignoretimelimits', $this->context, null, false));
316         }
317         return $this->accessmanager;
318     }
320     /**
321      * Wrapper round the has_capability funciton that automatically passes in the quiz context.
322      */
323     public function has_capability($capability, $userid = null, $doanything = true) {
324         return has_capability($capability, $this->context, $userid, $doanything);
325     }
327     /**
328      * Wrapper round the require_capability funciton that automatically passes in the quiz context.
329      */
330     public function require_capability($capability, $userid = null, $doanything = true) {
331         return require_capability($capability, $this->context, $userid, $doanything);
332     }
334     // URLs related to this attempt ============================================
335     /**
336      * @return string the URL of this quiz's view page.
337      */
338     public function view_url() {
339         global $CFG;
340         return $CFG->wwwroot . '/mod/quiz/view.php?id=' . $this->cm->id;
341     }
343     /**
344      * @return string the URL of this quiz's edit page.
345      */
346     public function edit_url() {
347         global $CFG;
348         return $CFG->wwwroot . '/mod/quiz/edit.php?cmid=' . $this->cm->id;
349     }
351     /**
352      * @param int $attemptid the id of an attempt.
353      * @param int $page optional page number to go to in the attempt.
354      * @return string the URL of that attempt.
355      */
356     public function attempt_url($attemptid, $page = 0) {
357         global $CFG;
358         $url = $CFG->wwwroot . '/mod/quiz/attempt.php?attempt=' . $attemptid;
359         if ($page) {
360             $url .= '&page=' . $page;
361         }
362         $url .= '&cmid=' . $this->get_cmid();
363         return $url;
364     }
366     /**
367      * @return string the URL of this quiz's edit page. Needs to be POSTed to with a cmid parameter.
368      */
369     public function start_attempt_url($page = 0) {
370         $params = array('cmid' => $this->cm->id, 'sesskey' => sesskey());
371         if ($page) {
372             $params['page'] = $page;
373         }
374         return new moodle_url('/mod/quiz/startattempt.php', $params);
375     }
377     /**
378      * @param int $attemptid the id of an attempt.
379      * @return string the URL of the review of that attempt.
380      */
381     public function review_url($attemptid) {
382         return new moodle_url('/mod/quiz/review.php', array('attempt' => $attemptid, 'cmid' => $this->get_cmid()));
383     }
385     /**
386      * @param int $attemptid the id of an attempt.
387      * @return string the URL of the review of that attempt.
388      */
389     public function summary_url($attemptid) {
390         return new moodle_url('/mod/quiz/summary.php', array('attempt' => $attemptid, 'cmid' => $this->get_cmid()));
391     }
393     // Bits of content =========================================================
395     /**
396      * @param bool $notused not used.
397      * @return string an empty string.
398      * @deprecated since 3.1. This sort of functionality is now entirely handled by quiz access rules.
399      */
400     public function confirm_start_attempt_message($notused) {
401         debugging('confirm_start_attempt_message is deprecated. ' .
402                 'This sort of functionality is now entirely handled by quiz access rules.');
403         return '';
404     }
406     /**
407      * If $reviewoptions->attempt is false, meaning that students can't review this
408      * attempt at the moment, return an appropriate string explaining why.
409      *
410      * @param int $when One of the mod_quiz_display_options::DURING,
411      *      IMMEDIATELY_AFTER, LATER_WHILE_OPEN or AFTER_CLOSE constants.
412      * @param bool $short if true, return a shorter string.
413      * @return string an appropraite message.
414      */
415     public function cannot_review_message($when, $short = false) {
417         if ($short) {
418             $langstrsuffix = 'short';
419             $dateformat = get_string('strftimedatetimeshort', 'langconfig');
420         } else {
421             $langstrsuffix = '';
422             $dateformat = '';
423         }
425         if ($when == mod_quiz_display_options::DURING ||
426                 $when == mod_quiz_display_options::IMMEDIATELY_AFTER) {
427             return '';
428         } else if ($when == mod_quiz_display_options::LATER_WHILE_OPEN && $this->quiz->timeclose &&
429                 $this->quiz->reviewattempt & mod_quiz_display_options::AFTER_CLOSE) {
430             return get_string('noreviewuntil' . $langstrsuffix, 'quiz',
431                     userdate($this->quiz->timeclose, $dateformat));
432         } else {
433             return get_string('noreview' . $langstrsuffix, 'quiz');
434         }
435     }
437     /**
438      * @param string $title the name of this particular quiz page.
439      * @return array the data that needs to be sent to print_header_simple as the $navigation
440      * parameter.
441      */
442     public function navigation($title) {
443         global $PAGE;
444         $PAGE->navbar->add($title);
445         return '';
446     }
448     // Private methods =========================================================
449     /**
450      * Check that the definition of a particular question is loaded, and if not throw an exception.
451      * @param $id a questionid.
452      */
453     protected function ensure_question_loaded($id) {
454         if (isset($this->questions[$id]->_partiallyloaded)) {
455             throw new moodle_quiz_exception($this, 'questionnotloaded', $id);
456         }
457     }
459     /**
460      * Return all the question types used in this quiz.
461      *
462      * @param  boolean $includepotential if the quiz include random questions, setting this flag to true will make the function to
463      * return all the possible question types in the random questions category
464      * @return array a sorted array including the different question types
465      * @since  Moodle 3.1
466      */
467     public function get_all_question_types_used($includepotential = false) {
468         $questiontypes = array();
470         // To control if we need to look in categories for questions.
471         $qcategories = array();
473         // We must be careful with random questions, if we find a random question we must assume that the quiz may content
474         // any of the questions in the referenced category (or subcategories).
475         foreach ($this->get_questions() as $questiondata) {
476             if ($questiondata->qtype == 'random' and $includepotential) {
477                 $includesubcategories = (bool) $questiondata->questiontext;
478                 if (!isset($qcategories[$questiondata->category])) {
479                     $qcategories[$questiondata->category] = false;
480                 }
481                 if ($includesubcategories) {
482                     $qcategories[$questiondata->category] = true;
483                 }
484             } else {
485                 if (!in_array($questiondata->qtype, $questiontypes)) {
486                     $questiontypes[] = $questiondata->qtype;
487                 }
488             }
489         }
491         if (!empty($qcategories)) {
492             // We have to look for all the question types in these categories.
493             $categoriestolook = array();
494             foreach ($qcategories as $cat => $includesubcats) {
495                 if ($includesubcats) {
496                     $categoriestolook = array_merge($categoriestolook, question_categorylist($cat));
497                 } else {
498                     $categoriestolook[] = $cat;
499                 }
500             }
501             $questiontypesincategories = question_bank::get_all_question_types_in_categories($categoriestolook);
502             $questiontypes = array_merge($questiontypes, $questiontypesincategories);
503         }
504         $questiontypes = array_unique($questiontypes);
505         sort($questiontypes);
507         return $questiontypes;
508     }
512 /**
513  * This class extends the quiz class to hold data about the state of a particular attempt,
514  * in addition to the data about the quiz.
515  *
516  * @copyright  2008 Tim Hunt
517  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
518  * @since      Moodle 2.0
519  */
520 class quiz_attempt {
522     /** @var string to identify the in progress state. */
523     const IN_PROGRESS = 'inprogress';
524     /** @var string to identify the overdue state. */
525     const OVERDUE     = 'overdue';
526     /** @var string to identify the finished state. */
527     const FINISHED    = 'finished';
528     /** @var string to identify the abandoned state. */
529     const ABANDONED   = 'abandoned';
531     /** @var int maximum number of slots in the quiz for the review page to default to show all. */
532     const MAX_SLOTS_FOR_DEFAULT_REVIEW_SHOW_ALL = 50;
534     /** @var quiz object containing the quiz settings. */
535     protected $quizobj;
537     /** @var stdClass the quiz_attempts row. */
538     protected $attempt;
540     /** @var question_usage_by_activity the question usage for this quiz attempt. */
541     protected $quba;
543     /**
544      * @var array of slot information. These objects contain ->slot (int),
545      *      ->requireprevious (bool), ->questionids (int) the original question for random questions,
546      *      ->firstinsection (bool), ->section (stdClass from $this->sections).
547      *      This does not contain page - get that from {@link get_question_page()} -
548      *      or maxmark - get that from $this->quba.
549      */
550     protected $slots;
552     /** @var array of quiz_sections rows, with a ->lastslot field added. */
553     protected $sections;
555     /** @var array page no => array of slot numbers on the page in order. */
556     protected $pagelayout;
558     /** @var array slot => displayed question number for this slot. (E.g. 1, 2, 3 or 'i'.) */
559     protected $questionnumbers;
561     /** @var array slot => page number for this slot. */
562     protected $questionpages;
564     /** @var mod_quiz_display_options cache for the appropriate review options. */
565     protected $reviewoptions = null;
567     // Constructor =============================================================
568     /**
569      * Constructor assuming we already have the necessary data loaded.
570      *
571      * @param object $attempt the row of the quiz_attempts table.
572      * @param object $quiz the quiz object for this attempt and user.
573      * @param object $cm the course_module object for this quiz.
574      * @param object $course the row from the course table for the course we belong to.
575      * @param bool $loadquestions (optional) if true, the default, load all the details
576      *      of the state of each question. Else just set up the basic details of the attempt.
577      */
578     public function __construct($attempt, $quiz, $cm, $course, $loadquestions = true) {
579         $this->attempt = $attempt;
580         $this->quizobj = new quiz($quiz, $cm, $course);
582         if ($loadquestions) {
583             $this->load_questions();
584         }
585     }
587     /**
588      * Used by {create()} and {create_from_usage_id()}.
589      * @param array $conditions passed to $DB->get_record('quiz_attempts', $conditions).
590      */
591     protected static function create_helper($conditions) {
592         global $DB;
594         $attempt = $DB->get_record('quiz_attempts', $conditions, '*', MUST_EXIST);
595         $quiz = quiz_access_manager::load_quiz_and_settings($attempt->quiz);
596         $course = $DB->get_record('course', array('id' => $quiz->course), '*', MUST_EXIST);
597         $cm = get_coursemodule_from_instance('quiz', $quiz->id, $course->id, false, MUST_EXIST);
599         // Update quiz with override information.
600         $quiz = quiz_update_effective_access($quiz, $attempt->userid);
602         return new quiz_attempt($attempt, $quiz, $cm, $course);
603     }
605     /**
606      * Static function to create a new quiz_attempt object given an attemptid.
607      *
608      * @param int $attemptid the attempt id.
609      * @return quiz_attempt the new quiz_attempt object
610      */
611     public static function create($attemptid) {
612         return self::create_helper(array('id' => $attemptid));
613     }
615     /**
616      * Static function to create a new quiz_attempt object given a usage id.
617      *
618      * @param int $usageid the attempt usage id.
619      * @return quiz_attempt the new quiz_attempt object
620      */
621     public static function create_from_usage_id($usageid) {
622         return self::create_helper(array('uniqueid' => $usageid));
623     }
625     /**
626      * @param string $state one of the state constants like IN_PROGRESS.
627      * @return string the human-readable state name.
628      */
629     public static function state_name($state) {
630         return quiz_attempt_state_name($state);
631     }
633     /**
634      * This method can be called later if the object was constructed with $loadqusetions = false.
635      */
636     public function load_questions() {
637         global $DB;
639         if (isset($this->quba)) {
640             throw new coding_exception('This quiz attempt has already had the questions loaded.');
641         }
643         $this->quba = question_engine::load_questions_usage_by_activity($this->attempt->uniqueid);
644         $this->slots = $DB->get_records('quiz_slots',
645                 array('quizid' => $this->get_quizid()), 'slot',
646                 'slot, id, requireprevious, questionid, includingsubcategories');
647         $this->sections = array_values($DB->get_records('quiz_sections',
648                 array('quizid' => $this->get_quizid()), 'firstslot'));
650         $this->link_sections_and_slots();
651         $this->determine_layout();
652         $this->number_questions();
653     }
655     /**
656      * Let each slot know which section it is part of.
657      */
658     protected function link_sections_and_slots() {
659         foreach ($this->sections as $i => $section) {
660             if (isset($this->sections[$i + 1])) {
661                 $section->lastslot = $this->sections[$i + 1]->firstslot - 1;
662             } else {
663                 $section->lastslot = count($this->slots);
664             }
665             for ($slot = $section->firstslot; $slot <= $section->lastslot; $slot += 1) {
666                 $this->slots[$slot]->section = $section;
667             }
668         }
669     }
671     /**
672      * Parse attempt->layout to populate the other arrays the represent the layout.
673      */
674     protected function determine_layout() {
675         $this->pagelayout = array();
677         // Break up the layout string into pages.
678         $pagelayouts = explode(',0', $this->attempt->layout);
680         // Strip off any empty last page (normally there is one).
681         if (end($pagelayouts) == '') {
682             array_pop($pagelayouts);
683         }
685         // File the ids into the arrays.
686         // Tracking which is the first slot in each section in this attempt is
687         // trickier than you might guess, since the slots in this section
688         // may be shuffled, so $section->firstslot (the lowest numbered slot in
689         // the section) may not be the first one.
690         $unseensections = $this->sections;
691         $this->pagelayout = array();
692         foreach ($pagelayouts as $page => $pagelayout) {
693             $pagelayout = trim($pagelayout, ',');
694             if ($pagelayout == '') {
695                 continue;
696             }
697             $this->pagelayout[$page] = explode(',', $pagelayout);
698             foreach ($this->pagelayout[$page] as $slot) {
699                 $sectionkey = array_search($this->slots[$slot]->section, $unseensections);
700                 if ($sectionkey !== false) {
701                     $this->slots[$slot]->firstinsection = true;
702                     unset($unseensections[$sectionkey]);
703                 } else {
704                     $this->slots[$slot]->firstinsection = false;
705                 }
706             }
707         }
708     }
710     /**
711      * Work out the number to display for each question/slot.
712      */
713     protected function number_questions() {
714         $number = 1;
715         foreach ($this->pagelayout as $page => $slots) {
716             foreach ($slots as $slot) {
717                 if ($length = $this->is_real_question($slot)) {
718                     $this->questionnumbers[$slot] = $number;
719                     $number += $length;
720                 } else {
721                     $this->questionnumbers[$slot] = get_string('infoshort', 'quiz');
722                 }
723                 $this->questionpages[$slot] = $page;
724             }
725         }
726     }
728     /**
729      * If the given page number is out of range (before the first page, or after
730      * the last page, chnage it to be within range).
731      * @param int $page the requested page number.
732      * @return int a safe page number to use.
733      */
734     public function force_page_number_into_range($page) {
735         return min(max($page, 0), count($this->pagelayout) - 1);
736     }
738     // Simple getters ==========================================================
739     public function get_quiz() {
740         return $this->quizobj->get_quiz();
741     }
743     public function get_quizobj() {
744         return $this->quizobj;
745     }
747     /** @return int the course id. */
748     public function get_courseid() {
749         return $this->quizobj->get_courseid();
750     }
752     /** @return int the course id. */
753     public function get_course() {
754         return $this->quizobj->get_course();
755     }
757     /** @return int the quiz id. */
758     public function get_quizid() {
759         return $this->quizobj->get_quizid();
760     }
762     /** @return string the name of this quiz. */
763     public function get_quiz_name() {
764         return $this->quizobj->get_quiz_name();
765     }
767     /** @return int the quiz navigation method. */
768     public function get_navigation_method() {
769         return $this->quizobj->get_navigation_method();
770     }
772     /** @return object the course_module object. */
773     public function get_cm() {
774         return $this->quizobj->get_cm();
775     }
777     /** @return object the course_module object. */
778     public function get_cmid() {
779         return $this->quizobj->get_cmid();
780     }
782     /**
783      * @return bool wether the current user is someone who previews the quiz,
784      * rather than attempting it.
785      */
786     public function is_preview_user() {
787         return $this->quizobj->is_preview_user();
788     }
790     /** @return int the number of attempts allowed at this quiz (0 = infinite). */
791     public function get_num_attempts_allowed() {
792         return $this->quizobj->get_num_attempts_allowed();
793     }
795     /** @return int number fo pages in this quiz. */
796     public function get_num_pages() {
797         return count($this->pagelayout);
798     }
800     /**
801      * @param int $timenow the current time as a unix timestamp.
802      * @return quiz_access_manager and instance of the quiz_access_manager class
803      *      for this quiz at this time.
804      */
805     public function get_access_manager($timenow) {
806         return $this->quizobj->get_access_manager($timenow);
807     }
809     /** @return int the attempt id. */
810     public function get_attemptid() {
811         return $this->attempt->id;
812     }
814     /** @return int the attempt unique id. */
815     public function get_uniqueid() {
816         return $this->attempt->uniqueid;
817     }
819     /** @return object the row from the quiz_attempts table. */
820     public function get_attempt() {
821         return $this->attempt;
822     }
824     /** @return int the number of this attemp (is it this user's first, second, ... attempt). */
825     public function get_attempt_number() {
826         return $this->attempt->attempt;
827     }
829     /** @return string one of the quiz_attempt::IN_PROGRESS, FINISHED, OVERDUE or ABANDONED constants. */
830     public function get_state() {
831         return $this->attempt->state;
832     }
834     /** @return int the id of the user this attempt belongs to. */
835     public function get_userid() {
836         return $this->attempt->userid;
837     }
839     /** @return int the current page of the attempt. */
840     public function get_currentpage() {
841         return $this->attempt->currentpage;
842     }
844     public function get_sum_marks() {
845         return $this->attempt->sumgrades;
846     }
848     /**
849      * @return bool whether this attempt has been finished (true) or is still
850      *     in progress (false). Be warned that this is not just state == self::FINISHED,
851      *     it also includes self::ABANDONED.
852      */
853     public function is_finished() {
854         return $this->attempt->state == self::FINISHED || $this->attempt->state == self::ABANDONED;
855     }
857     /** @return bool whether this attempt is a preview attempt. */
858     public function is_preview() {
859         return $this->attempt->preview;
860     }
862     /**
863      * Is this someone dealing with their own attempt or preview?
864      *
865      * @return bool true => own attempt/preview. false => reviewing someone elses.
866      */
867     public function is_own_attempt() {
868         global $USER;
869         return $this->attempt->userid == $USER->id;
870     }
872     /**
873      * @return bool whether this attempt is a preview belonging to the current user.
874      */
875     public function is_own_preview() {
876         global $USER;
877         return $this->is_own_attempt() &&
878                 $this->is_preview_user() && $this->attempt->preview;
879     }
881     /**
882      * Is the current user allowed to review this attempt. This applies when
883      * {@link is_own_attempt()} returns false.
884      * @return bool whether the review should be allowed.
885      */
886     public function is_review_allowed() {
887         if (!$this->has_capability('mod/quiz:viewreports')) {
888             return false;
889         }
891         $cm = $this->get_cm();
892         if ($this->has_capability('moodle/site:accessallgroups') ||
893                 groups_get_activity_groupmode($cm) != SEPARATEGROUPS) {
894             return true;
895         }
897         // Check the users have at least one group in common.
898         $teachersgroups = groups_get_activity_allowed_groups($cm);
899         $studentsgroups = groups_get_all_groups(
900                 $cm->course, $this->attempt->userid, $cm->groupingid);
901         return $teachersgroups && $studentsgroups &&
902                 array_intersect(array_keys($teachersgroups), array_keys($studentsgroups));
903     }
905     /**
906      * Has the student, in this attempt, engaged with the quiz in a non-trivial way?
907      * That is, is there any question worth a non-zero number of marks, where
908      * the student has made some response that we have saved?
909      * @return bool true if we have saved a response for at least one graded question.
910      */
911     public function has_response_to_at_least_one_graded_question() {
912         foreach ($this->quba->get_attempt_iterator() as $qa) {
913             if ($qa->get_max_mark() == 0) {
914                 continue;
915             }
916             if ($qa->get_num_steps() > 1) {
917                 return true;
918             }
919         }
920         return false;
921     }
923     /**
924      * Get extra summary information about this attempt.
925      *
926      * Some behaviours may be able to provide interesting summary information
927      * about the attempt as a whole, and this method provides access to that data.
928      * To see how this works, try setting a quiz to one of the CBM behaviours,
929      * and then look at the extra information displayed at the top of the quiz
930      * review page once you have sumitted an attempt.
931      *
932      * In the return value, the array keys are identifiers of the form
933      * qbehaviour_behaviourname_meaningfullkey. For qbehaviour_deferredcbm_highsummary.
934      * The values are arrays with two items, title and content. Each of these
935      * will be either a string, or a renderable.
936      *
937      * @param question_display_options $options the display options for this quiz attempt at this time.
938      * @return array as described above.
939      */
940     public function get_additional_summary_data(question_display_options $options) {
941         return $this->quba->get_summary_information($options);
942     }
944     /**
945      * Get the overall feedback corresponding to a particular mark.
946      * @param $grade a particular grade.
947      */
948     public function get_overall_feedback($grade) {
949         return quiz_feedback_for_grade($grade, $this->get_quiz(),
950                 $this->quizobj->get_context());
951     }
953     /**
954      * Wrapper round the has_capability funciton that automatically passes in the quiz context.
955      */
956     public function has_capability($capability, $userid = null, $doanything = true) {
957         return $this->quizobj->has_capability($capability, $userid, $doanything);
958     }
960     /**
961      * Wrapper round the require_capability funciton that automatically passes in the quiz context.
962      */
963     public function require_capability($capability, $userid = null, $doanything = true) {
964         return $this->quizobj->require_capability($capability, $userid, $doanything);
965     }
967     /**
968      * Check the appropriate capability to see whether this user may review their own attempt.
969      * If not, prints an error.
970      */
971     public function check_review_capability() {
972         if ($this->get_attempt_state() == mod_quiz_display_options::IMMEDIATELY_AFTER) {
973             $capability = 'mod/quiz:attempt';
974         } else {
975             $capability = 'mod/quiz:reviewmyattempts';
976         }
978         // These next tests are in a slighly funny order. The point is that the
979         // common and most performance-critical case is students attempting a quiz
980         // so we want to check that permisison first.
982         if ($this->has_capability($capability)) {
983             // User has the permission that lets you do the quiz as a student. Fine.
984             return;
985         }
987         if ($this->has_capability('mod/quiz:viewreports') ||
988                 $this->has_capability('mod/quiz:preview')) {
989             // User has the permission that lets teachers review. Fine.
990             return;
991         }
993         // They should not be here. Trigger the standard no-permission error
994         // but using the name of the student capability.
995         // We know this will fail. We just want the stadard exception thown.
996         $this->require_capability($capability);
997     }
999     /**
1000      * Checks whether a user may navigate to a particular slot
1001      */
1002     public function can_navigate_to($slot) {
1003         switch ($this->get_navigation_method()) {
1004             case QUIZ_NAVMETHOD_FREE:
1005                 return true;
1006                 break;
1007             case QUIZ_NAVMETHOD_SEQ:
1008                 return false;
1009                 break;
1010         }
1011         return true;
1012     }
1014     /**
1015      * @return int one of the mod_quiz_display_options::DURING,
1016      *      IMMEDIATELY_AFTER, LATER_WHILE_OPEN or AFTER_CLOSE constants.
1017      */
1018     public function get_attempt_state() {
1019         return quiz_attempt_state($this->get_quiz(), $this->attempt);
1020     }
1022     /**
1023      * Wrapper that the correct mod_quiz_display_options for this quiz at the
1024      * moment.
1025      *
1026      * @return question_display_options the render options for this user on this attempt.
1027      */
1028     public function get_display_options($reviewing) {
1029         if ($reviewing) {
1030             if (is_null($this->reviewoptions)) {
1031                 $this->reviewoptions = quiz_get_review_options($this->get_quiz(),
1032                         $this->attempt, $this->quizobj->get_context());
1033                 if ($this->is_own_preview()) {
1034                     // It should  always be possible for a teacher to review their
1035                     // own preview irrespective of the review options settings.
1036                     $this->reviewoptions->attempt = true;
1037                 }
1038             }
1039             return $this->reviewoptions;
1041         } else {
1042             $options = mod_quiz_display_options::make_from_quiz($this->get_quiz(),
1043                     mod_quiz_display_options::DURING);
1044             $options->flags = quiz_get_flag_option($this->attempt, $this->quizobj->get_context());
1045             return $options;
1046         }
1047     }
1049     /**
1050      * Wrapper that the correct mod_quiz_display_options for this quiz at the
1051      * moment.
1052      *
1053      * @param bool $reviewing true for review page, else attempt page.
1054      * @param int $slot which question is being displayed.
1055      * @param moodle_url $thispageurl to return to after the editing form is
1056      *      submitted or cancelled. If null, no edit link will be generated.
1057      *
1058      * @return question_display_options the render options for this user on this
1059      *      attempt, with extra info to generate an edit link, if applicable.
1060      */
1061     public function get_display_options_with_edit_link($reviewing, $slot, $thispageurl) {
1062         $options = clone($this->get_display_options($reviewing));
1064         if (!$thispageurl) {
1065             return $options;
1066         }
1068         if (!($reviewing || $this->is_preview())) {
1069             return $options;
1070         }
1072         $question = $this->quba->get_question($slot);
1073         if (!question_has_capability_on($question, 'edit', $question->category)) {
1074             return $options;
1075         }
1077         $options->editquestionparams['cmid'] = $this->get_cmid();
1078         $options->editquestionparams['returnurl'] = $thispageurl;
1080         return $options;
1081     }
1083     /**
1084      * @param int $page page number
1085      * @return bool true if this is the last page of the quiz.
1086      */
1087     public function is_last_page($page) {
1088         return $page == count($this->pagelayout) - 1;
1089     }
1091     /**
1092      * Return the list of slot numbers for either a given page of the quiz, or for the
1093      * whole quiz.
1094      *
1095      * @param mixed $page string 'all' or integer page number.
1096      * @return array the requested list of slot numbers.
1097      */
1098     public function get_slots($page = 'all') {
1099         if ($page === 'all') {
1100             $numbers = array();
1101             foreach ($this->pagelayout as $numbersonpage) {
1102                 $numbers = array_merge($numbers, $numbersonpage);
1103             }
1104             return $numbers;
1105         } else {
1106             return $this->pagelayout[$page];
1107         }
1108     }
1110     /**
1111      * Return the list of slot numbers for either a given page of the quiz, or for the
1112      * whole quiz.
1113      *
1114      * @param mixed $page string 'all' or integer page number.
1115      * @return array the requested list of slot numbers.
1116      */
1117     public function get_active_slots($page = 'all') {
1118         $activeslots = array();
1119         foreach ($this->get_slots($page) as $slot) {
1120             if (!$this->is_blocked_by_previous_question($slot)) {
1121                 $activeslots[] = $slot;
1122             }
1123         }
1124         return $activeslots;
1125     }
1127     /**
1128      * Helper method for unit tests. Get the underlying question usage object.
1129      * @return question_usage_by_activity the usage.
1130      */
1131     public function get_question_usage() {
1132         if (!(PHPUNIT_TEST || defined('BEHAT_TEST'))) {
1133             throw new coding_exception('get_question_usage is only for use in unit tests. ' .
1134                     'For other operations, use the quiz_attempt api, or extend it properly.');
1135         }
1136         return $this->quba;
1137     }
1139     /**
1140      * Get the question_attempt object for a particular question in this attempt.
1141      * @param int $slot the number used to identify this question within this attempt.
1142      * @return question_attempt
1143      */
1144     public function get_question_attempt($slot) {
1145         return $this->quba->get_question_attempt($slot);
1146     }
1148     /**
1149      * Get the question_attempt object for a particular question in this attempt.
1150      * @param int $slot the number used to identify this question within this attempt.
1151      * @return question_attempt
1152      */
1153     public function all_question_attempts_originally_in_slot($slot) {
1154         $qas = array();
1155         foreach ($this->quba->get_attempt_iterator() as $qa) {
1156             if ($qa->get_metadata('originalslot') == $slot) {
1157                 $qas[] = $qa;
1158             }
1159         }
1160         $qas[] = $this->quba->get_question_attempt($slot);
1161         return $qas;
1162     }
1164     /**
1165      * Is a particular question in this attempt a real question, or something like a description.
1166      * @param int $slot the number used to identify this question within this attempt.
1167      * @return int whether that question is a real question. Actually returns the
1168      *     question length, which could theoretically be greater than one.
1169      */
1170     public function is_real_question($slot) {
1171         return $this->quba->get_question($slot)->length;
1172     }
1174     /**
1175      * Is a particular question in this attempt a real question, or something like a description.
1176      * @param int $slot the number used to identify this question within this attempt.
1177      * @return bool whether that question is a real question.
1178      */
1179     public function is_question_flagged($slot) {
1180         return $this->quba->get_question_attempt($slot)->is_flagged();
1181     }
1183     /**
1184      * Checks whether the question in this slot requires the previous question to have been completed.
1185      *
1186      * @param int $slot the number used to identify this question within this attempt.
1187      * @return bool whether the previous question must have been completed before this one can be seen.
1188      */
1189     public function is_blocked_by_previous_question($slot) {
1190         return $slot > 1 && isset($this->slots[$slot]) && $this->slots[$slot]->requireprevious &&
1191                 !$this->slots[$slot]->section->shufflequestions &&
1192                 !$this->slots[$slot - 1]->section->shufflequestions &&
1193                 $this->get_navigation_method() != QUIZ_NAVMETHOD_SEQ &&
1194                 !$this->get_question_state($slot - 1)->is_finished() &&
1195                 $this->quba->can_question_finish_during_attempt($slot - 1);
1196     }
1198     /**
1199      * Is it possible for this question to be re-started within this attempt?
1200      *
1201      * @param int $slot the number used to identify this question within this attempt.
1202      * @return whether the student should be given the option to restart this question now.
1203      */
1204     public function can_question_be_redone_now($slot) {
1205         return $this->get_quiz()->canredoquestions && !$this->is_finished() &&
1206                 $this->get_question_state($slot)->is_finished();
1207     }
1209     /**
1210      * Given a slot in this attempt, which may or not be a redone question, return the original slot.
1211      *
1212      * @param int $slot identifies a particular question in this attempt.
1213      * @return int the slot where this question was originally.
1214      */
1215     public function get_original_slot($slot) {
1216         $originalslot = $this->quba->get_question_attempt_metadata($slot, 'originalslot');
1217         if ($originalslot) {
1218             return $originalslot;
1219         } else {
1220             return $slot;
1221         }
1222     }
1224     /**
1225      * Get the displayed question number for a slot.
1226      * @param int $slot the number used to identify this question within this attempt.
1227      * @return string the displayed question number for the question in this slot.
1228      *      For example '1', '2', '3' or 'i'.
1229      */
1230     public function get_question_number($slot) {
1231         return $this->questionnumbers[$slot];
1232     }
1234     /**
1235      * If the section heading, if any, that should come just before this slot.
1236      * @param int $slot identifies a particular question in this attempt.
1237      * @return string the required heading, or null if there is not one here.
1238      */
1239     public function get_heading_before_slot($slot) {
1240         if ($this->slots[$slot]->firstinsection) {
1241             return $this->slots[$slot]->section->heading;
1242         } else {
1243             return null;
1244         }
1245     }
1247     /**
1248      * Return the page of the quiz where this question appears.
1249      * @param int $slot the number used to identify this question within this attempt.
1250      * @return int the page of the quiz this question appears on.
1251      */
1252     public function get_question_page($slot) {
1253         return $this->questionpages[$slot];
1254     }
1256     /**
1257      * Return the grade obtained on a particular question, if the user is permitted
1258      * to see it. You must previously have called load_question_states to load the
1259      * state data about this question.
1260      *
1261      * @param int $slot the number used to identify this question within this attempt.
1262      * @return string the formatted grade, to the number of decimal places specified
1263      *      by the quiz.
1264      */
1265     public function get_question_name($slot) {
1266         return $this->quba->get_question($slot)->name;
1267     }
1269     /**
1270      * Return the {@link question_state} that this question is in.
1271      *
1272      * @param int $slot the number used to identify this question within this attempt.
1273      * @return question_state the state this question is in.
1274      */
1275     public function get_question_state($slot) {
1276         return $this->quba->get_question_state($slot);
1277     }
1279     /**
1280      * Return the grade obtained on a particular question, if the user is permitted
1281      * to see it. You must previously have called load_question_states to load the
1282      * state data about this question.
1283      *
1284      * @param int $slot the number used to identify this question within this attempt.
1285      * @param bool $showcorrectness Whether right/partial/wrong states should
1286      * be distinguised.
1287      * @return string the formatted grade, to the number of decimal places specified
1288      *      by the quiz.
1289      */
1290     public function get_question_status($slot, $showcorrectness) {
1291         return $this->quba->get_question_state_string($slot, $showcorrectness);
1292     }
1294     /**
1295      * Return the grade obtained on a particular question, if the user is permitted
1296      * to see it. You must previously have called load_question_states to load the
1297      * state data about this question.
1298      *
1299      * @param int $slot the number used to identify this question within this attempt.
1300      * @param bool $showcorrectness Whether right/partial/wrong states should
1301      * be distinguised.
1302      * @return string class name for this state.
1303      */
1304     public function get_question_state_class($slot, $showcorrectness) {
1305         return $this->quba->get_question_state_class($slot, $showcorrectness);
1306     }
1308     /**
1309      * Return the grade obtained on a particular question.
1310      * You must previously have called load_question_states to load the state
1311      * data about this question.
1312      *
1313      * @param int $slot the number used to identify this question within this attempt.
1314      * @return string the formatted grade, to the number of decimal places specified by the quiz.
1315      */
1316     public function get_question_mark($slot) {
1317         return quiz_format_question_grade($this->get_quiz(), $this->quba->get_question_mark($slot));
1318     }
1320     /**
1321      * Get the time of the most recent action performed on a question.
1322      * @param int $slot the number used to identify this question within this usage.
1323      * @return int timestamp.
1324      */
1325     public function get_question_action_time($slot) {
1326         return $this->quba->get_question_action_time($slot);
1327     }
1329     /**
1330      * Return the question type name for a given slot within the current attempt.
1331      *
1332      * @param int $slot the number used to identify this question within this attempt.
1333      * @return string the question type name
1334      * @since  Moodle 3.1
1335      */
1336     public function get_question_type_name($slot) {
1337         return $this->quba->get_question($slot)->get_type_name();
1338     }
1340     /**
1341      * Get the time remaining for an in-progress attempt, if the time is short
1342      * enought that it would be worth showing a timer.
1343      * @param int $timenow the time to consider as 'now'.
1344      * @return int|false the number of seconds remaining for this attempt.
1345      *      False if there is no limit.
1346      */
1347     public function get_time_left_display($timenow) {
1348         if ($this->attempt->state != self::IN_PROGRESS) {
1349             return false;
1350         }
1351         return $this->get_access_manager($timenow)->get_time_left_display($this->attempt, $timenow);
1352     }
1355     /**
1356      * @return int the time when this attempt was submitted. 0 if it has not been
1357      * submitted yet.
1358      */
1359     public function get_submitted_date() {
1360         return $this->attempt->timefinish;
1361     }
1363     /**
1364      * If the attempt is in an applicable state, work out the time by which the
1365      * student should next do something.
1366      * @return int timestamp by which the student needs to do something.
1367      */
1368     public function get_due_date() {
1369         $deadlines = array();
1370         if ($this->quizobj->get_quiz()->timelimit) {
1371             $deadlines[] = $this->attempt->timestart + $this->quizobj->get_quiz()->timelimit;
1372         }
1373         if ($this->quizobj->get_quiz()->timeclose) {
1374             $deadlines[] = $this->quizobj->get_quiz()->timeclose;
1375         }
1376         if ($deadlines) {
1377             $duedate = min($deadlines);
1378         } else {
1379             return false;
1380         }
1382         switch ($this->attempt->state) {
1383             case self::IN_PROGRESS:
1384                 return $duedate;
1386             case self::OVERDUE:
1387                 return $duedate + $this->quizobj->get_quiz()->graceperiod;
1389             default:
1390                 throw new coding_exception('Unexpected state: ' . $this->attempt->state);
1391         }
1392     }
1394     // URLs related to this attempt ============================================
1395     /**
1396      * @return string quiz view url.
1397      */
1398     public function view_url() {
1399         return $this->quizobj->view_url();
1400     }
1402     /**
1403      * @return string the URL of this quiz's edit page. Needs to be POSTed to with a cmid parameter.
1404      */
1405     public function start_attempt_url($slot = null, $page = -1) {
1406         if ($page == -1 && !is_null($slot)) {
1407             $page = $this->get_question_page($slot);
1408         } else {
1409             $page = 0;
1410         }
1411         return $this->quizobj->start_attempt_url($page);
1412     }
1414     /**
1415      * Generates the title of the attempt page.
1416      *
1417      * @param int $page the page number (starting with 0) in the attempt.
1418      * @return string
1419      */
1420     public function attempt_page_title(int $page) : string {
1421         if ($this->get_num_pages() > 1) {
1422             $a = new stdClass();
1423             $a->name = $this->get_quiz_name();
1424             $a->currentpage = $page + 1;
1425             $a->totalpages = $this->get_num_pages();
1426             $title = get_string('attempttitlepaged', 'quiz', $a);
1427         } else {
1428             $title = get_string('attempttitle', 'quiz', $this->get_quiz_name());
1429         }
1431         return $title;
1432     }
1434     /**
1435      * @param int $slot if speified, the slot number of a specific question to link to.
1436      * @param int $page if specified, a particular page to link to. If not givem deduced
1437      *      from $slot, or goes to the first page.
1438      * @param int $thispage if not -1, the current page. Will cause links to other things on
1439      * this page to be output as only a fragment.
1440      * @return string the URL to continue this attempt.
1441      */
1442     public function attempt_url($slot = null, $page = -1, $thispage = -1) {
1443         return $this->page_and_question_url('attempt', $slot, $page, false, $thispage);
1444     }
1446     /**
1447      * Generates the title of the summary page.
1448      *
1449      * @return string
1450      */
1451     public function summary_page_title() : string {
1452         return get_string('attemptsummarytitle', 'quiz', $this->get_quiz_name());
1453     }
1455     /**
1456      * @return string the URL of this quiz's summary page.
1457      */
1458     public function summary_url() {
1459         return new moodle_url('/mod/quiz/summary.php', array('attempt' => $this->attempt->id, 'cmid' => $this->get_cmid()));
1460     }
1462     /**
1463      * @return string the URL of this quiz's summary page.
1464      */
1465     public function processattempt_url() {
1466         return new moodle_url('/mod/quiz/processattempt.php');
1467     }
1469     /**
1470      * Generates the title of the review page.
1471      *
1472      * @param int $page the page number (starting with 0) in the attempt.
1473      * @param bool $showall whether the review page contains the entire attempt on one page.
1474      * @return string
1475      */
1476     public function review_page_title(int $page, bool $showall = false) : string {
1477         if (!$showall && $this->get_num_pages() > 1) {
1478             $a = new stdClass();
1479             $a->name = $this->get_quiz_name();
1480             $a->currentpage = $page + 1;
1481             $a->totalpages = $this->get_num_pages();
1482             $title = get_string('attemptreviewtitlepaged', 'quiz', $a);
1483         } else {
1484             $title = get_string('attemptreviewtitle', 'quiz', $this->get_quiz_name());
1485         }
1487         return $title;
1488     }
1490     /**
1491      * @param int $slot indicates which question to link to.
1492      * @param int $page if specified, the URL of this particular page of the attempt, otherwise
1493      * the URL will go to the first page.  If -1, deduce $page from $slot.
1494      * @param bool|null $showall if true, the URL will be to review the entire attempt on one page,
1495      * and $page will be ignored. If null, a sensible default will be chosen.
1496      * @param int $thispage if not -1, the current page. Will cause links to other things on
1497      * this page to be output as only a fragment.
1498      * @return string the URL to review this attempt.
1499      */
1500     public function review_url($slot = null, $page = -1, $showall = null, $thispage = -1) {
1501         return $this->page_and_question_url('review', $slot, $page, $showall, $thispage);
1502     }
1504     /**
1505      * By default, should this script show all questions on one page for this attempt?
1506      * @param string $script the script name, e.g. 'attempt', 'summary', 'review'.
1507      * @return whether show all on one page should be on by default.
1508      */
1509     public function get_default_show_all($script) {
1510         return $script == 'review' && count($this->questionpages) < self::MAX_SLOTS_FOR_DEFAULT_REVIEW_SHOW_ALL;
1511     }
1513     // Bits of content =========================================================
1515     /**
1516      * If $reviewoptions->attempt is false, meaning that students can't review this
1517      * attempt at the moment, return an appropriate string explaining why.
1518      *
1519      * @param bool $short if true, return a shorter string.
1520      * @return string an appropraite message.
1521      */
1522     public function cannot_review_message($short = false) {
1523         return $this->quizobj->cannot_review_message(
1524                 $this->get_attempt_state(), $short);
1525     }
1527     /**
1528      * Initialise the JS etc. required all the questions on a page.
1529      * @param mixed $page a page number, or 'all'.
1530      */
1531     public function get_html_head_contributions($page = 'all', $showall = false) {
1532         if ($showall) {
1533             $page = 'all';
1534         }
1535         $result = '';
1536         foreach ($this->get_slots($page) as $slot) {
1537             $result .= $this->quba->render_question_head_html($slot);
1538         }
1539         $result .= question_engine::initialise_js();
1540         return $result;
1541     }
1543     /**
1544      * Initialise the JS etc. required by one question.
1545      * @param int $questionid the question id.
1546      */
1547     public function get_question_html_head_contributions($slot) {
1548         return $this->quba->render_question_head_html($slot) .
1549                 question_engine::initialise_js();
1550     }
1552     /**
1553      * Print the HTML for the start new preview button, if the current user
1554      * is allowed to see one.
1555      */
1556     public function restart_preview_button() {
1557         global $OUTPUT;
1558         if ($this->is_preview() && $this->is_preview_user()) {
1559             return $OUTPUT->single_button(new moodle_url(
1560                     $this->start_attempt_url(), array('forcenew' => true)),
1561                     get_string('startnewpreview', 'quiz'));
1562         } else {
1563             return '';
1564         }
1565     }
1567     /**
1568      * Generate the HTML that displayes the question in its current state, with
1569      * the appropriate display options.
1570      *
1571      * @param int $slot identifies the question in the attempt.
1572      * @param bool $reviewing is the being printed on an attempt or a review page.
1573      * @param mod_quiz_renderer $renderer the quiz renderer.
1574      * @param moodle_url $thispageurl the URL of the page this question is being printed on.
1575      * @return string HTML for the question in its current state.
1576      */
1577     public function render_question($slot, $reviewing, mod_quiz_renderer $renderer, $thispageurl = null) {
1578         if ($this->is_blocked_by_previous_question($slot)) {
1579             $placeholderqa = $this->make_blocked_question_placeholder($slot);
1581             $displayoptions = $this->get_display_options($reviewing);
1582             $displayoptions->manualcomment = question_display_options::HIDDEN;
1583             $displayoptions->history = question_display_options::HIDDEN;
1584             $displayoptions->readonly = true;
1586             return html_writer::div($placeholderqa->render($displayoptions,
1587                     $this->get_question_number($this->get_original_slot($slot))),
1588                     'mod_quiz-blocked_question_warning');
1589         }
1591         return $this->render_question_helper($slot, $reviewing, $thispageurl, $renderer, null);
1592     }
1594     /**
1595      * Helper used by {@link render_question()} and {@link render_question_at_step()}.
1596      *
1597      * @param int $slot identifies the question in the attempt.
1598      * @param bool $reviewing is the being printed on an attempt or a review page.
1599      * @param moodle_url $thispageurl the URL of the page this question is being printed on.
1600      * @param mod_quiz_renderer $renderer the quiz renderer.
1601      * @param int|null $seq the seq number of the past state to display.
1602      * @return string HTML fragment.
1603      */
1604     protected function render_question_helper($slot, $reviewing, $thispageurl, mod_quiz_renderer $renderer, $seq) {
1605         $originalslot = $this->get_original_slot($slot);
1606         $number = $this->get_question_number($originalslot);
1607         $displayoptions = $this->get_display_options_with_edit_link($reviewing, $slot, $thispageurl);
1609         if ($slot != $originalslot) {
1610             $originalmaxmark = $this->get_question_attempt($slot)->get_max_mark();
1611             $this->get_question_attempt($slot)->set_max_mark($this->get_question_attempt($originalslot)->get_max_mark());
1612         }
1614         if ($this->can_question_be_redone_now($slot)) {
1615             $displayoptions->extrainfocontent = $renderer->redo_question_button(
1616                     $slot, $displayoptions->readonly);
1617         }
1619         if ($displayoptions->history && $displayoptions->questionreviewlink) {
1620             $links = $this->links_to_other_redos($slot, $displayoptions->questionreviewlink);
1621             if ($links) {
1622                 $displayoptions->extrahistorycontent = html_writer::tag('p',
1623                         get_string('redoesofthisquestion', 'quiz', $renderer->render($links)));
1624             }
1625         }
1627         if ($seq === null) {
1628             $output = $this->quba->render_question($slot, $displayoptions, $number);
1629         } else {
1630             $output = $this->quba->render_question_at_step($slot, $seq, $displayoptions, $number);
1631         }
1633         if ($slot != $originalslot) {
1634             $this->get_question_attempt($slot)->set_max_mark($originalmaxmark);
1635         }
1637         return $output;
1638     }
1640     /**
1641      * Create a fake question to be displayed in place of a question that is blocked
1642      * until the previous question has been answered.
1643      *
1644      * @param int $slot int slot number of the question to replace.
1645      * @return question_definition the placeholde question.
1646      */
1647     protected function make_blocked_question_placeholder($slot) {
1648         $replacedquestion = $this->get_question_attempt($slot)->get_question();
1650         question_bank::load_question_definition_classes('description');
1651         $question = new qtype_description_question();
1652         $question->id = $replacedquestion->id;
1653         $question->category = null;
1654         $question->parent = 0;
1655         $question->qtype = question_bank::get_qtype('description');
1656         $question->name = '';
1657         $question->questiontext = get_string('questiondependsonprevious', 'quiz');
1658         $question->questiontextformat = FORMAT_HTML;
1659         $question->generalfeedback = '';
1660         $question->defaultmark = $this->quba->get_question_max_mark($slot);
1661         $question->length = $replacedquestion->length;
1662         $question->penalty = 0;
1663         $question->stamp = '';
1664         $question->version = 0;
1665         $question->hidden = 0;
1666         $question->timecreated = null;
1667         $question->timemodified = null;
1668         $question->createdby = null;
1669         $question->modifiedby = null;
1671         $placeholderqa = new question_attempt($question, $this->quba->get_id(),
1672                 null, $this->quba->get_question_max_mark($slot));
1673         $placeholderqa->set_slot($slot);
1674         $placeholderqa->start($this->get_quiz()->preferredbehaviour, 1);
1675         $placeholderqa->set_flagged($this->is_question_flagged($slot));
1676         return $placeholderqa;
1677     }
1679     /**
1680      * Like {@link render_question()} but displays the question at the past step
1681      * indicated by $seq, rather than showing the latest step.
1682      *
1683      * @param int $id the id of a question in this quiz attempt.
1684      * @param int $seq the seq number of the past state to display.
1685      * @param bool $reviewing is the being printed on an attempt or a review page.
1686      * @param mod_quiz_renderer $renderer the quiz renderer.
1687      * @param string $thispageurl the URL of the page this question is being printed on.
1688      * @return string HTML for the question in its current state.
1689      */
1690     public function render_question_at_step($slot, $seq, $reviewing, mod_quiz_renderer $renderer, $thispageurl = '') {
1691         return $this->render_question_helper($slot, $reviewing, $thispageurl, $renderer, $seq);
1692     }
1694     /**
1695      * Wrapper round print_question from lib/questionlib.php.
1696      *
1697      * @param int $id the id of a question in this quiz attempt.
1698      */
1699     public function render_question_for_commenting($slot) {
1700         $options = $this->get_display_options(true);
1701         $options->hide_all_feedback();
1702         $options->manualcomment = question_display_options::EDITABLE;
1703         return $this->quba->render_question($slot, $options,
1704                 $this->get_question_number($slot));
1705     }
1707     /**
1708      * Check wheter access should be allowed to a particular file.
1709      *
1710      * @param int $id the id of a question in this quiz attempt.
1711      * @param bool $reviewing is the being printed on an attempt or a review page.
1712      * @param string $thispageurl the URL of the page this question is being printed on.
1713      * @return string HTML for the question in its current state.
1714      */
1715     public function check_file_access($slot, $reviewing, $contextid, $component,
1716             $filearea, $args, $forcedownload) {
1717         $options = $this->get_display_options($reviewing);
1719         // Check permissions - warning there is similar code in review.php and
1720         // reviewquestion.php. If you change on, change them all.
1721         if ($reviewing && $this->is_own_attempt() && !$options->attempt) {
1722             return false;
1723         }
1725         if ($reviewing && !$this->is_own_attempt() && !$this->is_review_allowed()) {
1726             return false;
1727         }
1729         return $this->quba->check_file_access($slot, $options,
1730                 $component, $filearea, $args, $forcedownload);
1731     }
1733     /**
1734      * Get the navigation panel object for this attempt.
1735      *
1736      * @param $panelclass The type of panel, quiz_attempt_nav_panel or quiz_review_nav_panel
1737      * @param $page the current page number.
1738      * @param $showall whether we are showing the whole quiz on one page. (Used by review.php)
1739      * @return quiz_nav_panel_base the requested object.
1740      */
1741     public function get_navigation_panel(mod_quiz_renderer $output,
1742              $panelclass, $page, $showall = false) {
1743         $panel = new $panelclass($this, $this->get_display_options(true), $page, $showall);
1745         $bc = new block_contents();
1746         $bc->attributes['id'] = 'mod_quiz_navblock';
1747         $bc->attributes['role'] = 'navigation';
1748         $bc->attributes['aria-labelledby'] = 'mod_quiz_navblock_title';
1749         $bc->title = html_writer::span(get_string('quiznavigation', 'quiz'), '', array('id' => 'mod_quiz_navblock_title'));
1750         $bc->content = $output->navigation_panel($panel);
1751         return $bc;
1752     }
1754     /**
1755      * Return an array of variant URLs to other attempts at this quiz.
1756      *
1757      * The $url passed in must contain an attempt parameter.
1758      *
1759      * The {@link mod_quiz_links_to_other_attempts} object returned contains an
1760      * array with keys that are the attempt number, 1, 2, 3.
1761      * The array values are either a {@link moodle_url} with the attmept parameter
1762      * updated to point to the attempt id of the other attempt, or null corresponding
1763      * to the current attempt number.
1764      *
1765      * @param moodle_url $url a URL.
1766      * @return mod_quiz_links_to_other_attempts containing array int => null|moodle_url.
1767      */
1768     public function links_to_other_attempts(moodle_url $url) {
1769         $attempts = quiz_get_user_attempts($this->get_quiz()->id, $this->attempt->userid, 'all');
1770         if (count($attempts) <= 1) {
1771             return false;
1772         }
1774         $links = new mod_quiz_links_to_other_attempts();
1775         foreach ($attempts as $at) {
1776             if ($at->id == $this->attempt->id) {
1777                 $links->links[$at->attempt] = null;
1778             } else {
1779                 $links->links[$at->attempt] = new moodle_url($url, array('attempt' => $at->id));
1780             }
1781         }
1782         return $links;
1783     }
1785     /**
1786      * Return an array of variant URLs to other redos of the question in a particular slot.
1787      *
1788      * The $url passed in must contain a slot parameter.
1789      *
1790      * The {@link mod_quiz_links_to_other_attempts} object returned contains an
1791      * array with keys that are the redo number, 1, 2, 3.
1792      * The array values are either a {@link moodle_url} with the slot parameter
1793      * updated to point to the slot that has that redo of this question; or null
1794      * corresponding to the redo identified by $slot.
1795      *
1796      * @param int $slot identifies a question in this attempt.
1797      * @param moodle_url $baseurl the base URL to modify to generate each link.
1798      * @return mod_quiz_links_to_other_attempts|null containing array int => null|moodle_url,
1799      *      or null if the question in this slot has not been redone.
1800      */
1801     public function links_to_other_redos($slot, moodle_url $baseurl) {
1802         $originalslot = $this->get_original_slot($slot);
1804         $qas = $this->all_question_attempts_originally_in_slot($originalslot);
1805         if (count($qas) <= 1) {
1806             return null;
1807         }
1809         $links = new mod_quiz_links_to_other_attempts();
1810         $index = 1;
1811         foreach ($qas as $qa) {
1812             if ($qa->get_slot() == $slot) {
1813                 $links->links[$index] = null;
1814             } else {
1815                 $url = new moodle_url($baseurl, array('slot' => $qa->get_slot()));
1816                 $links->links[$index] = new action_link($url, $index,
1817                         new popup_action('click', $url, 'reviewquestion',
1818                                 array('width' => 450, 'height' => 650)),
1819                         array('title' => get_string('reviewresponse', 'question')));
1820             }
1821             $index++;
1822         }
1823         return $links;
1824     }
1826     // Methods for processing ==================================================
1828     /**
1829      * Check this attempt, to see if there are any state transitions that should
1830      * happen automatically.  This function will update the attempt checkstatetime.
1831      * @param int $timestamp the timestamp that should be stored as the modifed
1832      * @param bool $studentisonline is the student currently interacting with Moodle?
1833      */
1834     public function handle_if_time_expired($timestamp, $studentisonline) {
1835         global $DB;
1837         $timeclose = $this->get_access_manager($timestamp)->get_end_time($this->attempt);
1839         if ($timeclose === false || $this->is_preview()) {
1840             $this->update_timecheckstate(null);
1841             return; // No time limit
1842         }
1843         if ($timestamp < $timeclose) {
1844             $this->update_timecheckstate($timeclose);
1845             return; // Time has not yet expired.
1846         }
1848         // If the attempt is already overdue, look to see if it should be abandoned ...
1849         if ($this->attempt->state == self::OVERDUE) {
1850             $timeoverdue = $timestamp - $timeclose;
1851             $graceperiod = $this->quizobj->get_quiz()->graceperiod;
1852             if ($timeoverdue >= $graceperiod) {
1853                 $this->process_abandon($timestamp, $studentisonline);
1854             } else {
1855                 // Overdue time has not yet expired
1856                 $this->update_timecheckstate($timeclose + $graceperiod);
1857             }
1858             return; // ... and we are done.
1859         }
1861         if ($this->attempt->state != self::IN_PROGRESS) {
1862             $this->update_timecheckstate(null);
1863             return; // Attempt is already in a final state.
1864         }
1866         // Otherwise, we were in quiz_attempt::IN_PROGRESS, and time has now expired.
1867         // Transition to the appropriate state.
1868         switch ($this->quizobj->get_quiz()->overduehandling) {
1869             case 'autosubmit':
1870                 $this->process_finish($timestamp, false);
1871                 return;
1873             case 'graceperiod':
1874                 $this->process_going_overdue($timestamp, $studentisonline);
1875                 return;
1877             case 'autoabandon':
1878                 $this->process_abandon($timestamp, $studentisonline);
1879                 return;
1880         }
1882         // This is an overdue attempt with no overdue handling defined, so just abandon.
1883         $this->process_abandon($timestamp, $studentisonline);
1884         return;
1885     }
1887     /**
1888      * Process all the actions that were submitted as part of the current request.
1889      *
1890      * @param int  $timestamp  the timestamp that should be stored as the modifed
1891      *                         time in the database for these actions. If null, will use the current time.
1892      * @param bool $becomingoverdue
1893      * @param array|null $simulatedresponses If not null, then we are testing, and this is an array of simulated data.
1894      *      There are two formats supported here, for historical reasons. The newer approach is to pass an array created by
1895      *      {@link core_question_generator::get_simulated_post_data_for_questions_in_usage()}.
1896      *      the second is to pass an array slot no => contains arrays representing student
1897      *      responses which will be passed to {@link question_definition::prepare_simulated_post_data()}.
1898      *      This second method will probably get deprecated one day.
1899      */
1900     public function process_submitted_actions($timestamp, $becomingoverdue = false, $simulatedresponses = null) {
1901         global $DB;
1903         $transaction = $DB->start_delegated_transaction();
1905         if ($simulatedresponses !== null) {
1906             if (is_int(key($simulatedresponses))) {
1907                 // Legacy approach. Should be removed one day.
1908                 $simulatedpostdata = $this->quba->prepare_simulated_post_data($simulatedresponses);
1909             } else {
1910                 $simulatedpostdata = $simulatedresponses;
1911             }
1912         } else {
1913             $simulatedpostdata = null;
1914         }
1916         $this->quba->process_all_actions($timestamp, $simulatedpostdata);
1917         question_engine::save_questions_usage_by_activity($this->quba);
1919         $this->attempt->timemodified = $timestamp;
1920         if ($this->attempt->state == self::FINISHED) {
1921             $this->attempt->sumgrades = $this->quba->get_total_mark();
1922         }
1923         if ($becomingoverdue) {
1924             $this->process_going_overdue($timestamp, true);
1925         } else {
1926             $DB->update_record('quiz_attempts', $this->attempt);
1927         }
1929         if (!$this->is_preview() && $this->attempt->state == self::FINISHED) {
1930             quiz_save_best_grade($this->get_quiz(), $this->get_userid());
1931         }
1933         $transaction->allow_commit();
1934     }
1936     /**
1937      * Replace a question in an attempt with a new attempt at the same question.
1938      *
1939      * Well, for randomised questions, it won't be the same question, it will be
1940      * a different randomised selection.
1941      *
1942      * @param int $slot the question to restart.
1943      * @param int $timestamp the timestamp to record for this action.
1944      */
1945     public function process_redo_question($slot, $timestamp) {
1946         global $DB;
1948         if (!$this->can_question_be_redone_now($slot)) {
1949             throw new coding_exception('Attempt to restart the question in slot ' . $slot .
1950                     ' when it is not in a state to be restarted.');
1951         }
1953         $qubaids = new \mod_quiz\question\qubaids_for_users_attempts(
1954                 $this->get_quizid(), $this->get_userid(), 'all', true);
1956         $transaction = $DB->start_delegated_transaction();
1958         // Choose the replacement question.
1959         $questiondata = $DB->get_record('question',
1960                 array('id' => $this->slots[$slot]->questionid));
1961         if ($questiondata->qtype != 'random') {
1962             $newqusetionid = $questiondata->id;
1963         } else {
1964             $tagids = quiz_retrieve_slot_tag_ids($this->slots[$slot]->id);
1966             $randomloader = new \core_question\bank\random_question_loader($qubaids, array());
1967             $newqusetionid = $randomloader->get_next_question_id($questiondata->category,
1968                     (bool) $questiondata->questiontext, $tagids);
1969             if ($newqusetionid === null) {
1970                 throw new moodle_exception('notenoughrandomquestions', 'quiz',
1971                         $this->quizobj->view_url(), $questiondata);
1972             }
1973         }
1975         // Add the question to the usage. It is important we do this before we choose a variant.
1976         $newquestion = question_bank::load_question($newqusetionid);
1977         $newslot = $this->quba->add_question_in_place_of_other($slot, $newquestion);
1979         // Choose the variant.
1980         if ($newquestion->get_num_variants() == 1) {
1981             $variant = 1;
1982         } else {
1983             $variantstrategy = new core_question\engine\variants\least_used_strategy(
1984                     $this->quba, $qubaids);
1985             $variant = $variantstrategy->choose_variant($newquestion->get_num_variants(),
1986                     $newquestion->get_variants_selection_seed());
1987         }
1989         // Start the question.
1990         $this->quba->start_question($slot, $variant);
1991         $this->quba->set_max_mark($newslot, 0);
1992         $this->quba->set_question_attempt_metadata($newslot, 'originalslot', $slot);
1993         question_engine::save_questions_usage_by_activity($this->quba);
1995         $transaction->allow_commit();
1996     }
1998     /**
1999      * Process all the autosaved data that was part of the current request.
2000      *
2001      * @param int $timestamp the timestamp that should be stored as the modifed
2002      * time in the database for these actions. If null, will use the current time.
2003      */
2004     public function process_auto_save($timestamp) {
2005         global $DB;
2007         $transaction = $DB->start_delegated_transaction();
2009         $this->quba->process_all_autosaves($timestamp);
2010         question_engine::save_questions_usage_by_activity($this->quba);
2012         $transaction->allow_commit();
2013     }
2015     /**
2016      * Update the flagged state for all question_attempts in this usage, if their
2017      * flagged state was changed in the request.
2018      */
2019     public function save_question_flags() {
2020         global $DB;
2022         $transaction = $DB->start_delegated_transaction();
2023         $this->quba->update_question_flags();
2024         question_engine::save_questions_usage_by_activity($this->quba);
2025         $transaction->allow_commit();
2026     }
2028     public function process_finish($timestamp, $processsubmitted) {
2029         global $DB;
2031         $transaction = $DB->start_delegated_transaction();
2033         if ($processsubmitted) {
2034             $this->quba->process_all_actions($timestamp);
2035         }
2036         $this->quba->finish_all_questions($timestamp);
2038         question_engine::save_questions_usage_by_activity($this->quba);
2040         $this->attempt->timemodified = $timestamp;
2041         $this->attempt->timefinish = $timestamp;
2042         $this->attempt->sumgrades = $this->quba->get_total_mark();
2043         $this->attempt->state = self::FINISHED;
2044         $this->attempt->timecheckstate = null;
2045         $DB->update_record('quiz_attempts', $this->attempt);
2047         if (!$this->is_preview()) {
2048             quiz_save_best_grade($this->get_quiz(), $this->attempt->userid);
2050             // Trigger event.
2051             $this->fire_state_transition_event('\mod_quiz\event\attempt_submitted', $timestamp);
2053             // Tell any access rules that care that the attempt is over.
2054             $this->get_access_manager($timestamp)->current_attempt_finished();
2055         }
2057         $transaction->allow_commit();
2058     }
2060     /**
2061      * Update this attempt timecheckstate if necessary.
2062      * @param int|null the timecheckstate
2063      */
2064     public function update_timecheckstate($time) {
2065         global $DB;
2066         if ($this->attempt->timecheckstate !== $time) {
2067             $this->attempt->timecheckstate = $time;
2068             $DB->set_field('quiz_attempts', 'timecheckstate', $time, array('id' => $this->attempt->id));
2069         }
2070     }
2072     /**
2073      * Mark this attempt as now overdue.
2074      * @param int $timestamp the time to deem as now.
2075      * @param bool $studentisonline is the student currently interacting with Moodle?
2076      */
2077     public function process_going_overdue($timestamp, $studentisonline) {
2078         global $DB;
2080         $transaction = $DB->start_delegated_transaction();
2081         $this->attempt->timemodified = $timestamp;
2082         $this->attempt->state = self::OVERDUE;
2083         // If we knew the attempt close time, we could compute when the graceperiod ends.
2084         // Instead we'll just fix it up through cron.
2085         $this->attempt->timecheckstate = $timestamp;
2086         $DB->update_record('quiz_attempts', $this->attempt);
2088         $this->fire_state_transition_event('\mod_quiz\event\attempt_becameoverdue', $timestamp);
2090         $transaction->allow_commit();
2092         quiz_send_overdue_message($this);
2093     }
2095     /**
2096      * Mark this attempt as abandoned.
2097      * @param int $timestamp the time to deem as now.
2098      * @param bool $studentisonline is the student currently interacting with Moodle?
2099      */
2100     public function process_abandon($timestamp, $studentisonline) {
2101         global $DB;
2103         $transaction = $DB->start_delegated_transaction();
2104         $this->attempt->timemodified = $timestamp;
2105         $this->attempt->state = self::ABANDONED;
2106         $this->attempt->timecheckstate = null;
2107         $DB->update_record('quiz_attempts', $this->attempt);
2109         $this->fire_state_transition_event('\mod_quiz\event\attempt_abandoned', $timestamp);
2111         $transaction->allow_commit();
2112     }
2114     /**
2115      * Fire a state transition event.
2116      * the same event information.
2117      * @param string $eventclass the event class name.
2118      * @param int $timestamp the timestamp to include in the event.
2119      * @return void
2120      */
2121     protected function fire_state_transition_event($eventclass, $timestamp) {
2122         global $USER;
2123         $quizrecord = $this->get_quiz();
2124         $params = array(
2125             'context' => $this->get_quizobj()->get_context(),
2126             'courseid' => $this->get_courseid(),
2127             'objectid' => $this->attempt->id,
2128             'relateduserid' => $this->attempt->userid,
2129             'other' => array(
2130                 'submitterid' => CLI_SCRIPT ? null : $USER->id,
2131                 'quizid' => $quizrecord->id
2132             )
2133         );
2135         $event = $eventclass::create($params);
2136         $event->add_record_snapshot('quiz', $this->get_quiz());
2137         $event->add_record_snapshot('quiz_attempts', $this->get_attempt());
2138         $event->trigger();
2139     }
2141     // Private methods =========================================================
2143     /**
2144      * Get a URL for a particular question on a particular page of the quiz.
2145      * Used by {@link attempt_url()} and {@link review_url()}.
2146      *
2147      * @param string $script. Used in the URL like /mod/quiz/$script.php
2148      * @param int $slot identifies the specific question on the page to jump to.
2149      *      0 to just use the $page parameter.
2150      * @param int $page -1 to look up the page number from the slot, otherwise
2151      *      the page number to go to.
2152      * @param bool|null $showall if true, return a URL with showall=1, and not page number.
2153      *      if null, then an intelligent default will be chosen.
2154      * @param int $thispage the page we are currently on. Links to questions on this
2155      *      page will just be a fragment #q123. -1 to disable this.
2156      * @return The requested URL.
2157      */
2158     protected function page_and_question_url($script, $slot, $page, $showall, $thispage) {
2160         $defaultshowall = $this->get_default_show_all($script);
2161         if ($showall === null && ($page == 0 || $page == -1)) {
2162             $showall = $defaultshowall;
2163         }
2165         // Fix up $page.
2166         if ($page == -1) {
2167             if ($slot !== null && !$showall) {
2168                 $page = $this->get_question_page($slot);
2169             } else {
2170                 $page = 0;
2171             }
2172         }
2174         if ($showall) {
2175             $page = 0;
2176         }
2178         // Add a fragment to scroll down to the question.
2179         $fragment = '';
2180         if ($slot !== null) {
2181             if ($slot == reset($this->pagelayout[$page])) {
2182                 // First question on page, go to top.
2183                 $fragment = '#';
2184             } else {
2185                 $qa = $this->get_question_attempt($slot);
2186                 $fragment = '#' . $qa->get_outer_question_div_unique_id();
2187             }
2188         }
2190         // Work out the correct start to the URL.
2191         if ($thispage == $page) {
2192             return new moodle_url($fragment);
2194         } else {
2195             $url = new moodle_url('/mod/quiz/' . $script . '.php' . $fragment,
2196                     array('attempt' => $this->attempt->id, 'cmid' => $this->get_cmid()));
2197             if ($page == 0 && $showall != $defaultshowall) {
2198                 $url->param('showall', (int) $showall);
2199             } else if ($page > 0) {
2200                 $url->param('page', $page);
2201             }
2202             return $url;
2203         }
2204     }
2206     /**
2207      * Process responses during an attempt at a quiz.
2208      *
2209      * @param  int $timenow time when the processing started
2210      * @param  bool $finishattempt whether to finish the attempt or not
2211      * @param  bool $timeup true if form was submitted by timer
2212      * @param  int $thispage current page number
2213      * @return string the attempt state once the data has been processed
2214      * @since  Moodle 3.1
2215      * @throws  moodle_exception
2216      */
2217     public function process_attempt($timenow, $finishattempt, $timeup, $thispage) {
2218         global $DB;
2220         $transaction = $DB->start_delegated_transaction();
2222         // If there is only a very small amount of time left, there is no point trying
2223         // to show the student another page of the quiz. Just finish now.
2224         $graceperiodmin = null;
2225         $accessmanager = $this->get_access_manager($timenow);
2226         $timeclose = $accessmanager->get_end_time($this->get_attempt());
2228         // Don't enforce timeclose for previews.
2229         if ($this->is_preview()) {
2230             $timeclose = false;
2231         }
2232         $toolate = false;
2233         if ($timeclose !== false && $timenow > $timeclose - QUIZ_MIN_TIME_TO_CONTINUE) {
2234             $timeup = true;
2235             $graceperiodmin = get_config('quiz', 'graceperiodmin');
2236             if ($timenow > $timeclose + $graceperiodmin) {
2237                 $toolate = true;
2238             }
2239         }
2241         // If time is running out, trigger the appropriate action.
2242         $becomingoverdue = false;
2243         $becomingabandoned = false;
2244         if ($timeup) {
2245             if ($this->get_quiz()->overduehandling == 'graceperiod') {
2246                 if (is_null($graceperiodmin)) {
2247                     $graceperiodmin = get_config('quiz', 'graceperiodmin');
2248                 }
2249                 if ($timenow > $timeclose + $this->get_quiz()->graceperiod + $graceperiodmin) {
2250                     // Grace period has run out.
2251                     $finishattempt = true;
2252                     $becomingabandoned = true;
2253                 } else {
2254                     $becomingoverdue = true;
2255                 }
2256             } else {
2257                 $finishattempt = true;
2258             }
2259         }
2261         // Don't log - we will end with a redirect to a page that is logged.
2263         if (!$finishattempt) {
2264             // Just process the responses for this page and go to the next page.
2265             if (!$toolate) {
2266                 try {
2267                     $this->process_submitted_actions($timenow, $becomingoverdue);
2269                 } catch (question_out_of_sequence_exception $e) {
2270                     throw new moodle_exception('submissionoutofsequencefriendlymessage', 'question',
2271                             $this->attempt_url(null, $thispage));
2273                 } catch (Exception $e) {
2274                     // This sucks, if we display our own custom error message, there is no way
2275                     // to display the original stack trace.
2276                     $debuginfo = '';
2277                     if (!empty($e->debuginfo)) {
2278                         $debuginfo = $e->debuginfo;
2279                     }
2280                     throw new moodle_exception('errorprocessingresponses', 'question',
2281                             $this->attempt_url(null, $thispage), $e->getMessage(), $debuginfo);
2282                 }
2284                 if (!$becomingoverdue) {
2285                     foreach ($this->get_slots() as $slot) {
2286                         if (optional_param('redoslot' . $slot, false, PARAM_BOOL)) {
2287                             $this->process_redo_question($slot, $timenow);
2288                         }
2289                     }
2290                 }
2292             } else {
2293                 // The student is too late.
2294                 $this->process_going_overdue($timenow, true);
2295             }
2297             $transaction->allow_commit();
2299             return $becomingoverdue ? self::OVERDUE : self::IN_PROGRESS;
2300         }
2302         // Update the quiz attempt record.
2303         try {
2304             if ($becomingabandoned) {
2305                 $this->process_abandon($timenow, true);
2306             } else {
2307                 $this->process_finish($timenow, !$toolate);
2308             }
2310         } catch (question_out_of_sequence_exception $e) {
2311             throw new moodle_exception('submissionoutofsequencefriendlymessage', 'question',
2312                     $this->attempt_url(null, $thispage));
2314         } catch (Exception $e) {
2315             // This sucks, if we display our own custom error message, there is no way
2316             // to display the original stack trace.
2317             $debuginfo = '';
2318             if (!empty($e->debuginfo)) {
2319                 $debuginfo = $e->debuginfo;
2320             }
2321             throw new moodle_exception('errorprocessingresponses', 'question',
2322                     $this->attempt_url(null, $thispage), $e->getMessage(), $debuginfo);
2323         }
2325         // Send the user to the review page.
2326         $transaction->allow_commit();
2328         return $becomingabandoned ? self::ABANDONED : self::FINISHED;
2329     }
2331     /**
2332      * Check a page access to see if is an out of sequence access.
2333      *
2334      * @param  int $page page number
2335      * @return boolean false is is an out of sequence access, true otherwise.
2336      * @since Moodle 3.1
2337      */
2338     public function check_page_access($page) {
2339         global $DB;
2341         if ($this->get_currentpage() != $page) {
2342             if ($this->get_navigation_method() == QUIZ_NAVMETHOD_SEQ && $this->get_currentpage() > $page) {
2343                 return false;
2344             }
2345         }
2346         return true;
2347     }
2349     /**
2350      * Update attempt page.
2351      *
2352      * @param  int $page page number
2353      * @return boolean true if everything was ok, false otherwise (out of sequence access).
2354      * @since Moodle 3.1
2355      */
2356     public function set_currentpage($page) {
2357         global $DB;
2359         if ($this->check_page_access($page)) {
2360             $DB->set_field('quiz_attempts', 'currentpage', $page, array('id' => $this->get_attemptid()));
2361             return true;
2362         }
2363         return false;
2364     }
2366     /**
2367      * Trigger the attempt_viewed event.
2368      *
2369      * @since Moodle 3.1
2370      */
2371     public function fire_attempt_viewed_event() {
2372         $params = array(
2373             'objectid' => $this->get_attemptid(),
2374             'relateduserid' => $this->get_userid(),
2375             'courseid' => $this->get_courseid(),
2376             'context' => context_module::instance($this->get_cmid()),
2377             'other' => array(
2378                 'quizid' => $this->get_quizid()
2379             )
2380         );
2381         $event = \mod_quiz\event\attempt_viewed::create($params);
2382         $event->add_record_snapshot('quiz_attempts', $this->get_attempt());
2383         $event->trigger();
2384     }
2386     /**
2387      * Trigger the attempt_summary_viewed event.
2388      *
2389      * @since Moodle 3.1
2390      */
2391     public function fire_attempt_summary_viewed_event() {
2393         $params = array(
2394             'objectid' => $this->get_attemptid(),
2395             'relateduserid' => $this->get_userid(),
2396             'courseid' => $this->get_courseid(),
2397             'context' => context_module::instance($this->get_cmid()),
2398             'other' => array(
2399                 'quizid' => $this->get_quizid()
2400             )
2401         );
2402         $event = \mod_quiz\event\attempt_summary_viewed::create($params);
2403         $event->add_record_snapshot('quiz_attempts', $this->get_attempt());
2404         $event->trigger();
2405     }
2407     /**
2408      * Trigger the attempt_reviewed event.
2409      *
2410      * @since Moodle 3.1
2411      */
2412     public function fire_attempt_reviewed_event() {
2414         $params = array(
2415             'objectid' => $this->get_attemptid(),
2416             'relateduserid' => $this->get_userid(),
2417             'courseid' => $this->get_courseid(),
2418             'context' => context_module::instance($this->get_cmid()),
2419             'other' => array(
2420                 'quizid' => $this->get_quizid()
2421             )
2422         );
2423         $event = \mod_quiz\event\attempt_reviewed::create($params);
2424         $event->add_record_snapshot('quiz_attempts', $this->get_attempt());
2425         $event->trigger();
2426     }
2428     /**
2429      * Update the timemodifiedoffline attempt field.
2430      * This function should be used only when web services are being used.
2431      *
2432      * @param int $time time stamp
2433      * @return boolean false if the field is not updated because web services aren't being used.
2434      * @since Moodle 3.2
2435      */
2436     public function set_offline_modified_time($time) {
2437         global $DB;
2439         // Update the timemodifiedoffline field only if web services are being used.
2440         if (WS_SERVER) {
2441             $this->attempt->timemodifiedoffline = $time;
2442             return true;
2443         }
2444         return false;
2445     }
2450 /**
2451  * Represents a heading in the navigation panel.
2452  *
2453  * @copyright  2015 The Open University
2454  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2455  * @since      Moodle 2.9
2456  */
2457 class quiz_nav_section_heading implements renderable {
2458     /** @var string the heading text. */
2459     public $heading;
2461     /**
2462      * Constructor.
2463      * @param string $heading the heading text
2464      */
2465     public function __construct($heading) {
2466         $this->heading = $heading;
2467     }
2471 /**
2472  * Represents a single link in the navigation panel.
2473  *
2474  * @copyright  2011 The Open University
2475  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2476  * @since      Moodle 2.1
2477  */
2478 class quiz_nav_question_button implements renderable {
2479     /** @var string id="..." to add to the HTML for this button. */
2480     public $id;
2481     /** @var string number to display in this button. Either the question number of 'i'. */
2482     public $number;
2483     /** @var string class to add to the class="" attribute to represnt the question state. */
2484     public $stateclass;
2485     /** @var string Textual description of the question state, e.g. to use as a tool tip. */
2486     public $statestring;
2487     /** @var int the page number this question is on. */
2488     public $page;
2489     /** @var bool true if this question is on the current page. */
2490     public $currentpage;
2491     /** @var bool true if this question has been flagged. */
2492     public $flagged;
2493     /** @var moodle_url the link this button goes to, or null if there should not be a link. */
2494     public $url;
2498 /**
2499  * Represents the navigation panel, and builds a {@link block_contents} to allow
2500  * it to be output.
2501  *
2502  * @copyright  2008 Tim Hunt
2503  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2504  * @since      Moodle 2.0
2505  */
2506 abstract class quiz_nav_panel_base {
2507     /** @var quiz_attempt */
2508     protected $attemptobj;
2509     /** @var question_display_options */
2510     protected $options;
2511     /** @var integer */
2512     protected $page;
2513     /** @var boolean */
2514     protected $showall;
2516     public function __construct(quiz_attempt $attemptobj,
2517             question_display_options $options, $page, $showall) {
2518         $this->attemptobj = $attemptobj;
2519         $this->options = $options;
2520         $this->page = $page;
2521         $this->showall = $showall;
2522     }
2524     /**
2525      * Get the buttons and section headings to go in the quiz navigation block.
2526      * @return renderable[] the buttons, possibly interleaved with section headings.
2527      */
2528     public function get_question_buttons() {
2529         $buttons = array();
2530         foreach ($this->attemptobj->get_slots() as $slot) {
2531             if ($heading = $this->attemptobj->get_heading_before_slot($slot)) {
2532                 $buttons[] = new quiz_nav_section_heading(format_string($heading));
2533             }
2535             $qa = $this->attemptobj->get_question_attempt($slot);
2536             $showcorrectness = $this->options->correctness && $qa->has_marks();
2538             $button = new quiz_nav_question_button();
2539             $button->id          = 'quiznavbutton' . $slot;
2540             $button->number      = $this->attemptobj->get_question_number($slot);
2541             $button->stateclass  = $qa->get_state_class($showcorrectness);
2542             $button->navmethod   = $this->attemptobj->get_navigation_method();
2543             if (!$showcorrectness && $button->stateclass == 'notanswered') {
2544                 $button->stateclass = 'complete';
2545             }
2546             $button->statestring = $this->get_state_string($qa, $showcorrectness);
2547             $button->page        = $this->attemptobj->get_question_page($slot);
2548             $button->currentpage = $this->showall || $button->page == $this->page;
2549             $button->flagged     = $qa->is_flagged();
2550             $button->url         = $this->get_question_url($slot);
2551             if ($this->attemptobj->is_blocked_by_previous_question($slot)) {
2552                 $button->url = null;
2553                 $button->stateclass = 'blocked';
2554                 $button->statestring = get_string('questiondependsonprevious', 'quiz');
2555             }
2556             $buttons[] = $button;
2557         }
2559         return $buttons;
2560     }
2562     protected function get_state_string(question_attempt $qa, $showcorrectness) {
2563         if ($qa->get_question()->length > 0) {
2564             return $qa->get_state_string($showcorrectness);
2565         }
2567         // Special case handling for 'information' items.
2568         if ($qa->get_state() == question_state::$todo) {
2569             return get_string('notyetviewed', 'quiz');
2570         } else {
2571             return get_string('viewed', 'quiz');
2572         }
2573     }
2575     public function render_before_button_bits(mod_quiz_renderer $output) {
2576         return '';
2577     }
2579     abstract public function render_end_bits(mod_quiz_renderer $output);
2581     protected function render_restart_preview_link($output) {
2582         if (!$this->attemptobj->is_own_preview()) {
2583             return '';
2584         }
2585         return $output->restart_preview_button(new moodle_url(
2586                 $this->attemptobj->start_attempt_url(), array('forcenew' => true)));
2587     }
2589     protected abstract function get_question_url($slot);
2591     public function user_picture() {
2592         global $DB;
2593         if ($this->attemptobj->get_quiz()->showuserpicture == QUIZ_SHOWIMAGE_NONE) {
2594             return null;
2595         }
2596         $user = $DB->get_record('user', array('id' => $this->attemptobj->get_userid()));
2597         $userpicture = new user_picture($user);
2598         $userpicture->courseid = $this->attemptobj->get_courseid();
2599         if ($this->attemptobj->get_quiz()->showuserpicture == QUIZ_SHOWIMAGE_LARGE) {
2600             $userpicture->size = true;
2601         }
2602         return $userpicture;
2603     }
2605     /**
2606      * Return 'allquestionsononepage' as CSS class name when $showall is set,
2607      * otherwise, return 'multipages' as CSS class name.
2608      * @return string, CSS class name
2609      */
2610     public function get_button_container_class() {
2611         // Quiz navigation is set on 'Show all questions on one page'.
2612         if ($this->showall) {
2613             return 'allquestionsononepage';
2614         }
2615         // Quiz navigation is set on 'Show one page at a time'.
2616         return 'multipages';
2617     }
2621 /**
2622  * Specialisation of {@link quiz_nav_panel_base} for the attempt quiz page.
2623  *
2624  * @copyright  2008 Tim Hunt
2625  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2626  * @since      Moodle 2.0
2627  */
2628 class quiz_attempt_nav_panel extends quiz_nav_panel_base {
2629     public function get_question_url($slot) {
2630         if ($this->attemptobj->can_navigate_to($slot)) {
2631             return $this->attemptobj->attempt_url($slot, -1, $this->page);
2632         } else {
2633             return null;
2634         }
2635     }
2637     public function render_before_button_bits(mod_quiz_renderer $output) {
2638         return html_writer::tag('div', get_string('navnojswarning', 'quiz'),
2639                 array('id' => 'quiznojswarning'));
2640     }
2642     public function render_end_bits(mod_quiz_renderer $output) {
2643         return html_writer::link($this->attemptobj->summary_url(),
2644                 get_string('endtest', 'quiz'), array('class' => 'endtestlink')) .
2645                 $output->countdown_timer($this->attemptobj, time()) .
2646                 $this->render_restart_preview_link($output);
2647     }
2651 /**
2652  * Specialisation of {@link quiz_nav_panel_base} for the review quiz page.
2653  *
2654  * @copyright  2008 Tim Hunt
2655  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
2656  * @since      Moodle 2.0
2657  */
2658 class quiz_review_nav_panel extends quiz_nav_panel_base {
2659     public function get_question_url($slot) {
2660         return $this->attemptobj->review_url($slot, -1, $this->showall, $this->page);
2661     }
2663     public function render_end_bits(mod_quiz_renderer $output) {
2664         $html = '';
2665         if ($this->attemptobj->get_num_pages() > 1) {
2666             if ($this->showall) {
2667                 $html .= html_writer::link($this->attemptobj->review_url(null, 0, false),
2668                         get_string('showeachpage', 'quiz'));
2669             } else {
2670                 $html .= html_writer::link($this->attemptobj->review_url(null, 0, true),
2671                         get_string('showall', 'quiz'));
2672             }
2673         }
2674         $html .= $output->finish_review_link($this->attemptobj);
2675         $html .= $this->render_restart_preview_link($output);
2676         return $html;
2677     }