MDL-16094 File storage conversion Quiz and Questions
[moodle.git] / mod / quiz / attemptlib.php
1 <?php
3 // This file is part of Moodle - http://moodle.org/
4 //
5 // Moodle is free software: you can redistribute it and/or modify
6 // it under the terms of the GNU General Public License as published by
7 // the Free Software Foundation, either version 3 of the License, or
8 // (at your option) any later version.
9 //
10 // Moodle is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 // GNU General Public License for more details.
14 //
15 // You should have received a copy of the GNU General Public License
16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
18 /**
19  * Back-end code for handling data about quizzes and the current user's attempt.
20  *
21  * There are classes for loading all the information about a quiz and attempts,
22  * and for displaying the navigation panel.
23  *
24  * @package quiz
25  * @copyright 2008 onwards Tim Hunt
26  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
27  */
30 /**
31  * Class for quiz exceptions. Just saves a couple of arguments on the
32  * constructor for a moodle_exception.
33  *
34  * @copyright 2008 Tim Hunt
35  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
36  * @since Moodle 2.0
37  */
38 class moodle_quiz_exception extends moodle_exception {
39     function __construct($quizobj, $errorcode, $a = NULL, $link = '', $debuginfo = null) {
40         if (!$link) {
41             $link = $quizobj->view_url();
42         }
43         parent::__construct($errorcode, 'quiz', $link, $a, $debuginfo);
44     }
45 }
47 /**
48  * A class encapsulating a quiz and the questions it contains, and making the
49  * information available to scripts like view.php.
50  *
51  * Initially, it only loads a minimal amout of information about each question - loading
52  * extra information only when necessary or when asked. The class tracks which questions
53  * are loaded.
54  *
55  * @copyright 2008 Tim Hunt
56  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
57  * @since Moodle 2.0
58  */
59 class quiz {
60     // Fields initialised in the constructor.
61     protected $course;
62     protected $cm;
63     protected $quiz;
64     protected $context;
65     protected $questionids; // All question ids in order that they appear in the quiz.
66     protected $pagequestionids; // array page no => array of questionids on the page in order.
68     // Fields set later if that data is needed.
69     protected $questions = null;
70     protected $accessmanager = null;
71     protected $ispreviewuser = null;
73     // Constructor =========================================================================
74     /**
75      * Constructor, assuming we already have the necessary data loaded.
76      *
77      * @param object $quiz the row from the quiz table.
78      * @param object $cm the course_module object for this quiz.
79      * @param object $course the row from the course table for the course we belong to.
80      * @param boolean $getcontext intended for testing - stops the constructor getting the context.
81      */
82     function __construct($quiz, $cm, $course, $getcontext = true) {
83         $this->quiz = $quiz;
84         $this->cm = $cm;
85         $this->quiz->cmid = $this->cm->id;
86         $this->course = $course;
87         if ($getcontext && !empty($cm->id)) {
88             $this->context = get_context_instance(CONTEXT_MODULE, $cm->id);
89         }
90         $this->determine_layout();
91     }
93     /**
94      * Static function to create a new quiz object for a specific user.
95      *
96      * @param integer $quizid the the quiz id.
97      * @param integer $userid the the userid.
98      * @return quiz the new quiz object
99      */
100     static public function create($quizid, $userid) {
101         global $DB;
103         if (!$quiz = $DB->get_record('quiz', array('id' => $quizid))) {
104             throw new moodle_exception('invalidquizid', 'quiz');
105         }
106         if (!$course = $DB->get_record('course', array('id' => $quiz->course))) {
107             throw new moodle_exception('invalidcoursemodule');
108         }
109         if (!$cm = get_coursemodule_from_instance('quiz', $quiz->id, $course->id)) {
110             throw new moodle_exception('invalidcoursemodule');
111         }
113         // Update quiz with override information
114         $quiz = quiz_update_effective_access($quiz, $userid);
116         return new quiz($quiz, $cm, $course);
117     }
119     // Functions for loading more data =====================================================
120     /**
121      * Convenience method. Calls {@link load_questions()} with the list of
122      * question ids for a given page.
123      *
124      * @param integer $page a page number.
125      */
126     public function load_questions_on_page($page) {
127         $this->load_questions($this->pagequestionids[$page]);
128     }
130     /**
131      * Load just basic information about all the questions in this quiz.
132      */
133     public function preload_questions() {
134         if (empty($this->questionids)) {
135             throw new moodle_quiz_exception($this, 'noquestions', $this->edit_url());
136         }
137         $this->questions = question_preload_questions($this->questionids,
138                 'qqi.grade AS maxgrade, qqi.id AS instance',
139                 '{quiz_question_instances} qqi ON qqi.quiz = :quizid AND q.id = qqi.question',
140                 array('quizid' => $this->quiz->id));
141         $this->number_questions();
142     }
144    /**
145      * Fully load some or all of the questions for this quiz. You must call {@link preload_questions()} first.
146      *
147      * @param array $questionids question ids of the questions to load. null for all.
148      */
149     public function load_questions($questionids = null) {
150         if (is_null($questionids)) {
151             $questionids = $this->questionids;
152         }
153         $questionstoprocess = array();
154         foreach ($questionids as $id) {
155             $questionstoprocess[$id] = $this->questions[$id];
156         }
157         if (!get_question_options($questionstoprocess)) {
158             throw new moodle_quiz_exception($this, 'loadingquestionsfailed', implode(', ', $questionids));
159         }
160     }
162     // Simple getters ======================================================================
163     /** @return integer the course id. */
164     public function get_courseid() {
165         return $this->course->id;
166     }
168     /** @return object the row of the course table. */
169     public function get_course() {
170         return $this->course;
171     }
173     /** @return integer the quiz id. */
174     public function get_quizid() {
175         return $this->quiz->id;
176     }
178     /** @return object the row of the quiz table. */
179     public function get_quiz() {
180         return $this->quiz;
181     }
183     /** @return string the name of this quiz. */
184     public function get_quiz_name() {
185         return $this->quiz->name;
186     }
188     /** @return integer the number of attempts allowed at this quiz (0 = infinite). */
189     public function get_num_attempts_allowed() {
190         return $this->quiz->attempts;
191     }
193     /** @return integer the course_module id. */
194     public function get_cmid() {
195         return $this->cm->id;
196     }
198     /** @return object the course_module object. */
199     public function get_cm() {
200         return $this->cm;
201     }
203     /**
204      * @return boolean wether the current user is someone who previews the quiz,
205      * rather than attempting it.
206      */
207     public function is_preview_user() {
208         if (is_null($this->ispreviewuser)) {
209             $this->ispreviewuser = has_capability('mod/quiz:preview', $this->context);
210         }
211         return $this->ispreviewuser;
212     }
214     /**
215      * @return integer number fo pages in this quiz.
216      */
217     public function get_num_pages() {
218         return count($this->pagequestionids);
219     }
222     /**
223      * @param int $page page number
224      * @return boolean true if this is the last page of the quiz.
225      */
226     public function is_last_page($page) {
227         return $page == count($this->pagequestionids) - 1;
228     }
230     /**
231      * @param integer $id the question id.
232      * @return object the question object with that id.
233      */
234     public function get_question($id) {
235         return $this->questions[$id];
236     }
238     /**
239      * @param array $questionids question ids of the questions to load. null for all.
240      */
241     public function get_questions($questionids = null) {
242         if (is_null($questionids)) {
243             $questionids = $this->questionids;
244         }
245         $questions = array();
246         foreach ($questionids as $id) {
247             $questions[$id] = $this->questions[$id];
248             $this->ensure_question_loaded($id);
249         }
250         return $questions;
251     }
253     /**
254      * Return the list of question ids for either a given page of the quiz, or for the
255      * whole quiz.
256      *
257      * @param mixed $page string 'all' or integer page number.
258      * @return array the reqested list of question ids.
259      */
260     public function get_question_ids($page = 'all') {
261         if ($page === 'all') {
262             $list = $this->questionids;
263         } else {
264             $list = $this->pagequestionids[$page];
265         }
266         // Clone the array, so our private arrays cannot be modified.
267         $result = array();
268         foreach ($list as $id) {
269             $result[] = $id;
270         }
271         return $result;
272     }
274     /**
275      * @param integer $timenow the current time as a unix timestamp.
276      * @return quiz_access_manager and instance of the quiz_access_manager class for this quiz at this time.
277      */
278     public function get_access_manager($timenow) {
279         if (is_null($this->accessmanager)) {
280             $this->accessmanager = new quiz_access_manager($this, $timenow,
281                     has_capability('mod/quiz:ignoretimelimits', $this->context, NULL, false));
282         }
283         return $this->accessmanager;
284     }
286     public function get_overall_feedback($grade) {
287         return quiz_feedback_for_grade($grade, $this->quiz, $this->context, $this->cm);
288     }
290     /**
291      * Wrapper round the has_capability funciton that automatically passes in the quiz context.
292      */
293     public function has_capability($capability, $userid = NULL, $doanything = true) {
294         return has_capability($capability, $this->context, $userid, $doanything);
295     }
297     /**
298      * Wrapper round the require_capability funciton that automatically passes in the quiz context.
299      */
300     public function require_capability($capability, $userid = NULL, $doanything = true) {
301         return require_capability($capability, $this->context, $userid, $doanything);
302     }
304     // URLs related to this attempt ========================================================
305     /**
306      * @return string the URL of this quiz's view page.
307      */
308     public function view_url() {
309         global $CFG;
310         return $CFG->wwwroot . '/mod/quiz/view.php?id=' . $this->cm->id;
311     }
313     /**
314      * @return string the URL of this quiz's edit page.
315      */
316     public function edit_url() {
317         global $CFG;
318         return $CFG->wwwroot . '/mod/quiz/edit.php?cmid=' . $this->cm->id;
319     }
321     /**
322      * @param integer $attemptid the id of an attempt.
323      * @return string the URL of that attempt.
324      */
325     public function attempt_url($attemptid) {
326         global $CFG;
327         return $CFG->wwwroot . '/mod/quiz/attempt.php?attempt=' . $attemptid;
328     }
330     /**
331      * @return string the URL of this quiz's edit page. Needs to be POSTed to with a cmid parameter.
332      */
333     public function start_attempt_url() {
334         return new moodle_url('/mod/quiz/startattempt.php',
335                 array('cmid' => $this->cm->id, 'sesskey' => sesskey()));
336     }
338     /**
339      * @param integer $attemptid the id of an attempt.
340      * @return string the URL of the review of that attempt.
341      */
342     public function review_url($attemptid) {
343         global $CFG;
344         return $CFG->wwwroot . '/mod/quiz/review.php?attempt=' . $attemptid;
345     }
347     // Bits of content =====================================================================
349     /**
350      * @param string $title the name of this particular quiz page.
351      * @return array the data that needs to be sent to print_header_simple as the $navigation
352      * parameter.
353      */
354     public function navigation($title) {
355         global $PAGE;
356         $PAGE->navbar->add($title);
357         return '';
358     }
360     // Private methods =====================================================================
361     /**
362      *  Check that the definition of a particular question is loaded, and if not throw an exception.
363      *  @param $id a questionid.
364      */
365     protected function ensure_question_loaded($id) {
366         if (isset($this->questions[$id]->_partiallyloaded)) {
367             throw new moodle_quiz_exception($this, 'questionnotloaded', $id);
368         }
369     }
371     /**
372      * Populate {@link $questionids} and {@link $pagequestionids} from the layout.
373      */
374     protected function determine_layout() {
375         $this->questionids = array();
376         $this->pagequestionids = array();
378         // Get the appropriate layout string (from quiz or attempt).
379         $layout = $this->get_layout_string();
380         if (empty($layout)) {
381             // Nothing to do.
382             return;
383         }
385         // Break up the layout string into pages.
386         $pagelayouts = explode(',0', quiz_clean_layout($layout, true));
388         // Strip off any empty last page (normally there is one).
389         if (end($pagelayouts) == '') {
390             array_pop($pagelayouts);
391         }
393         // File the ids into the arrays.
394         $this->questionids = array();
395         $this->pagequestionids = array();
396         foreach ($pagelayouts as $page => $pagelayout) {
397             $pagelayout = trim($pagelayout, ',');
398             if ($pagelayout == '') continue;
399             $this->pagequestionids[$page] = explode(',', $pagelayout);
400             foreach ($this->pagequestionids[$page] as $id) {
401                 $this->questionids[] = $id;
402             }
403         }
404     }
406     /**
407      * Number the questions, adding a _number field to each one.
408      */
409     private function number_questions() {
410         $number = 1;
411         foreach ($this->pagequestionids as $page => $questionids) {
412             foreach ($questionids as $id) {
413                 if ($this->questions[$id]->length > 0) {
414                     $this->questions[$id]->_number = $number;
415                     $number += $this->questions[$id]->length;
416                 } else {
417                     $this->questions[$id]->_number = get_string('infoshort', 'quiz');
418                 }
419                 $this->questions[$id]->_page = $page;
420             }
421         }
422     }
424     /**
425      * @return string the layout of this quiz. Used by number_questions to
426      * work out which questions are on which pages.
427      */
428     protected function get_layout_string() {
429         return $this->quiz->questions;
430     }
433 /**
434  * This class extends the quiz class to hold data about the state of a particular attempt,
435  * in addition to the data about the quiz.
436  *
437  * @copyright 2008 Tim Hunt
438  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
439  * @since Moodle 2.0
440  */
441 class quiz_attempt extends quiz {
442     // Fields initialised in the constructor.
443     protected $attempt;
445     // Fields set later if that data is needed.
446     protected $states = array();
447     protected $reviewoptions = null;
449     // Constructor =========================================================================
450     /**
451      * Constructor assuming we already have the necessary data loaded.
452      *
453      * @param object $attempt the row of the quiz_attempts table.
454      * @param object $quiz the quiz object for this attempt and user.
455      * @param object $cm the course_module object for this quiz.
456      * @param object $course the row from the course table for the course we belong to.
457      */
458     function __construct($attempt, $quiz, $cm, $course) {
459         $this->attempt = $attempt;
460         parent::__construct($quiz, $cm, $course);
461         $this->preload_questions();
462         $this->preload_question_states();
463     }
465     /**
466      * Static function to create a new quiz_attempt object given an attemptid.
467      *
468      * @param integer $attemptid the attempt id.
469      * @return quiz_attempt the new quiz_attempt object
470      */
471     static public function create($attemptid) {
472         global $DB;
474         if (!$attempt = quiz_load_attempt($attemptid)) {
475             throw new moodle_exception('invalidattemptid', 'quiz');
476         }
477         if (!$quiz = $DB->get_record('quiz', array('id' => $attempt->quiz))) {
478             throw new moodle_exception('invalidquizid', 'quiz');
479         }
480         if (!$course = $DB->get_record('course', array('id' => $quiz->course))) {
481             throw new moodle_exception('invalidcoursemodule');
482         }
483         if (!$cm = get_coursemodule_from_instance('quiz', $quiz->id, $course->id)) {
484             throw new moodle_exception('invalidcoursemodule');
485         }
486         // Update quiz with override information
487         $quiz = quiz_update_effective_access($quiz, $attempt->userid);
489         return new quiz_attempt($attempt, $quiz, $cm, $course);
490     }
492     // Functions for loading more data =====================================================
493     /**
494      * Load the state of a number of questions that have already been loaded.
495      *
496      * @param array $questionids question ids to process. Blank = all.
497      */
498     public function load_question_states($questionids = null) {
499         if (is_null($questionids)) {
500             $questionids = $this->questionids;
501         }
502         $questionstoprocess = array();
503         foreach ($questionids as $id) {
504             $this->ensure_question_loaded($id);
505             $questionstoprocess[$id] = $this->questions[$id];
506         }
507         if (!question_load_states($questionstoprocess, $this->states,
508                 $this->quiz, $this->attempt)) {
509             throw new moodle_quiz_exception($this, 'cannotrestore');
510         }
511     }
513     /**
514      * Load basic information about the state of each question.
515      *
516      * This is enough to, for example, show the state of each question in the
517      * navigation panel, but only takes one DB query.
518      */
519     public function preload_question_states() {
520         if (empty($this->questionids)) {
521             throw new moodle_quiz_exception($this, 'noquestions', $this->edit_url());
522         }
523         $this->states = question_preload_states($this->attempt->uniqueid);
524         if (!$this->states) {
525             $this->states = array();
526         }
527     }
529     /**
530      * Load a particular state of a particular question. Used by the reviewquestion.php
531      * script to let the teacher walk through the entire sequence of a student's
532      * interaction with a question.
533      *
534      * @param $questionid the question id
535      * @param $stateid the id of the particular state to load.
536      */
537     public function load_specific_question_state($questionid, $stateid) {
538         global $DB;
539         $state = question_load_specific_state($this->questions[$questionid],
540                 $this->quiz, $this->attempt, $stateid);
541         if ($state === false) {
542             throw new moodle_quiz_exception($this, 'invalidstateid');
543         }
544         $this->states[$questionid] = $state;
545     }
547     // Simple getters ======================================================================
548     /** @return integer the attempt id. */
549     public function get_attemptid() {
550         return $this->attempt->id;
551     }
553     /** @return integer the attempt unique id. */
554     public function get_uniqueid() {
555         return $this->attempt->uniqueid;
556     }
558     /** @return object the row from the quiz_attempts table. */
559     public function get_attempt() {
560         return $this->attempt;
561     }
563     /** @return integer the number of this attemp (is it this user's first, second, ... attempt). */
564     public function get_attempt_number() {
565         return $this->attempt->attempt;
566     }
568     /** @return integer the id of the user this attempt belongs to. */
569     public function get_userid() {
570         return $this->attempt->userid;
571     }
573     /** @return boolean whether this attempt has been finished (true) or is still in progress (false). */
574     public function is_finished() {
575         return $this->attempt->timefinish != 0;
576     }
578     /** @return boolean whether this attempt is a preview attempt. */
579     public function is_preview() {
580         return $this->attempt->preview;
581     }
583     /**
584      * Is this a student dealing with their own attempt/teacher previewing,
585      * or someone with 'mod/quiz:viewreports' reviewing someone elses attempt.
586      *
587      * @return boolean whether this situation should be treated as someone looking at their own
588      * attempt. The distinction normally only matters when an attempt is being reviewed.
589      */
590     public function is_own_attempt() {
591         global $USER;
592         return $this->attempt->userid == $USER->id &&
593                 (!$this->is_preview_user() || $this->attempt->preview);
594     }
596     /**
597      * Check the appropriate capability to see whether this user may review their own attempt.
598      * If not, prints an error.
599      */
600     public function check_review_capability() {
601         if (!$this->has_capability('mod/quiz:viewreports')) {
602             if ($this->get_review_options()->quizstate == QUIZ_STATE_IMMEDIATELY) {
603                 $this->require_capability('mod/quiz:attempt');
604             } else {
605                 $this->require_capability('mod/quiz:reviewmyattempts');
606             }
607         }
608     }
610     /**
611      * Get the current state of a question in the attempt.
612      *
613      * @param $questionid a questionid.
614      * @return object the state.
615      */
616     public function get_question_state($questionid) {
617         $this->ensure_state_loaded($questionid);
618         return $this->states[$questionid];
619     }
621     /**
622      * Wrapper that calls quiz_get_reviewoptions with the appropriate arguments.
623      *
624      * @return object the review options for this user on this attempt.
625      */
626     public function get_review_options() {
627         if (is_null($this->reviewoptions)) {
628             $this->reviewoptions = quiz_get_reviewoptions($this->quiz, $this->attempt, $this->context);
629         }
630         return $this->reviewoptions;
631     }
633     /**
634      * Wrapper that calls get_render_options with the appropriate arguments.
635      *
636      * @param integer questionid the quetsion to get the render options for.
637      * @return object the render options for this user on this attempt.
638      */
639     public function get_render_options($questionid) {
640         return quiz_get_renderoptions($this->quiz, $this->attempt, $this->context,
641                 $this->get_question_state($questionid));
642     }
644     /**
645      * Get a quiz_attempt_question_iterator for either a page of the quiz, or a whole quiz.
646      * You must have called load_questions with an appropriate argument first.
647      *
648      * @param mixed $page as for the @see{get_question_ids} method.
649      * @return quiz_attempt_question_iterator the requested iterator.
650      */
651     public function get_question_iterator($page = 'all') {
652         return new quiz_attempt_question_iterator($this, $page);
653     }
655     /**
656      * Return a summary of the current state of a question in this attempt. You must previously
657      * have called load_question_states to load the state data about this question.
658      *
659      * @param integer $questionid question id of a question that belongs to this quiz.
660      * @return string a brief string (that could be used as a CSS class name, for example)
661      * that describes the current state of a question in this attempt. Possible results are:
662      * open|saved|closed|correct|partiallycorrect|incorrect.
663      */
664     public function get_question_status($questionid) {
665         $state = $this->states[$questionid];
666         switch ($state->event) {
667             case QUESTION_EVENTOPEN:
668                 return 'open';
670             case QUESTION_EVENTSAVE:
671             case QUESTION_EVENTGRADE:
672             case QUESTION_EVENTSUBMIT:
673                 return 'answered';
675             case QUESTION_EVENTCLOSEANDGRADE:
676             case QUESTION_EVENTCLOSE:
677             case QUESTION_EVENTMANUALGRADE:
678                 $options = $this->get_render_options($questionid);
679                 if ($options->scores && $this->questions[$questionid]->maxgrade > 0) {
680                     return question_get_feedback_class($state->last_graded->raw_grade /
681                             $this->questions[$questionid]->maxgrade);
682                 } else {
683                     return 'closed';
684                 }
686             default:
687                 $a = new stdClass;
688                 $a->event = $state->event;
689                 $a->questionid = $questionid;
690                 $a->attemptid = $this->attempt->id;
691                 throw new moodle_quiz_exception($this, 'errorunexpectedevent', $a);
692         }
693     }
695     /**
696      * @param integer $questionid question id of a question that belongs to this quiz.
697      * @return boolean whether this question hss been flagged by the attempter.
698      */
699     public function is_question_flagged($questionid) {
700         $state = $this->states[$questionid];
701         return $state->flagged;
702     }
704     /**
705      * Return the grade obtained on a particular question, if the user is permitted to see it.
706      * You must previously have called load_question_states to load the state data about this question.
707      *
708      * @param integer $questionid question id of a question that belongs to this quiz.
709      * @return string the formatted grade, to the number of decimal places specified by the quiz.
710      */
711     public function get_question_score($questionid) {
712         $options = $this->get_render_options($questionid);
713         if ($options->scores) {
714             return quiz_format_question_grade($this->quiz, $this->states[$questionid]->last_graded->grade);
715         } else {
716             return '';
717         }
718     }
720     // URLs related to this attempt ========================================================
721     /**
722      * @param integer $questionid a question id. If set, will add a fragment to the URL
723      * to jump to a particuar question on the page.
724      * @param integer $page if specified, the URL of this particular page of the attempt, otherwise
725      * the URL will go to the first page. If -1, deduce $page from $questionid.
726      * @param integer $thispage if not -1, the current page. Will cause links to other things on
727      * this page to be output as only a fragment.
728      * @return string the URL to continue this attempt.
729      */
730     public function attempt_url($questionid = 0, $page = -1, $thispage = -1) {
731         return $this->page_and_question_url('attempt', $questionid, $page, false, $thispage);
732     }
734     /**
735      * @return string the URL of this quiz's summary page.
736      */
737     public function summary_url() {
738         global $CFG;
739         return $CFG->wwwroot . '/mod/quiz/summary.php?attempt=' . $this->attempt->id;
740     }
742     /**
743      * @return string the URL of this quiz's summary page.
744      */
745     public function processattempt_url() {
746         global $CFG;
747         return $CFG->wwwroot . '/mod/quiz/processattempt.php';
748     }
750     /**
751      * @param integer $questionid a question id. If set, will add a fragment to the URL
752      * to jump to a particuar question on the page. If -1, deduce $page from $questionid.
753      * @param integer $page if specified, the URL of this particular page of the attempt, otherwise
754      * the URL will go to the first page.
755      * @param boolean $showall if true, the URL will be to review the entire attempt on one page,
756      * and $page will be ignored.
757      * @param integer $thispage if not -1, the current page. Will cause links to other things on
758      * this page to be output as only a fragment.
759      * @return string the URL to review this attempt.
760      */
761     public function review_url($questionid = 0, $page = -1, $showall = false, $thispage = -1) {
762         return $this->page_and_question_url('review', $questionid, $page, $showall, $thispage);
763     }
765     // Bits of content =====================================================================
766     /**
767      * Initialise the JS etc. required all the questions on a page..
768      * @param mixed $page a page number, or 'all'.
769      */
770     public function get_html_head_contributions($page = 'all') {
771         global $PAGE;
772         question_get_html_head_contributions($this->get_question_ids($page), $this->questions, $this->states);
773     }
775     /**
776      * Initialise the JS etc. required by one question.
777      * @param integer $questionid the question id.
778      */
779     public function get_question_html_head_contributions($questionid) {
780         question_get_html_head_contributions(array($questionid), $this->questions, $this->states);
781     }
783     /**
784      * Print the HTML for the start new preview button.
785      */
786     public function print_restart_preview_button() {
787         global $CFG, $OUTPUT;
788         echo $OUTPUT->container_start('controls');
789         $url = new moodle_url($this->start_attempt_url(), array('forcenew' => true));
790         echo $OUTPUT->single_button($url, get_string('startagain', 'quiz'));
791         echo $OUTPUT->container_end();
792     }
794     /**
795      * Return the HTML of the quiz timer.
796      * @return string HTML content.
797      */
798     public function get_timer_html() {
799         return '<div id="quiz-timer">' . get_string('timeleft', 'quiz') .
800                 ' <span id="quiz-time-left"></span></div>';
801     }
803     /**
804      * Wrapper round print_question from lib/questionlib.php.
805      *
806      * @param integer $id the id of a question in this quiz attempt.
807      * @param boolean $reviewing is the being printed on an attempt or a review page.
808      * @param string $thispageurl the URL of the page this question is being printed on.
809      */
810     public function print_question($id, $reviewing, $thispageurl = '') {
811         if ($reviewing) {
812             $options = $this->get_review_options();
813         } else {
814             $options = $this->get_render_options($id);
815         }
816         if ($thispageurl) {
817             $this->quiz->thispageurl = $thispageurl;
818         } else {
819             unset($thispageurl);
820         }
821         print_question($this->questions[$id], $this->states[$id], $this->questions[$id]->_number,
822                 $this->quiz, $options);
823     }
825     public function check_file_access($questionid, $isreviewing, $contextid, $component,
826             $filearea, $args, $forcedownload) {
827         if ($isreviewing) {
828             $options = $this->get_review_options();
829         } else {
830             $options = $this->get_render_options($questionid);
831         }
832         // XXX: mulitichoice type needs quiz id to get maxgrade
833         $options->quizid = $this->attempt->quiz;
834         return question_check_file_access($this->questions[$questionid],
835                 $this->get_question_state($questionid), $options, $contextid,
836                 $component, $filearea, $args, $forcedownload);
837     }
839     /**
840      * Triggers the sending of the notification emails at the end of this attempt.
841      */
842     public function quiz_send_notification_emails() {
843         quiz_send_notification_emails($this->course, $this->quiz, $this->attempt,
844                 $this->context, $this->cm);
845     }
847     /**
848      * Get the navigation panel object for this attempt.
849      *
850      * @param $panelclass The type of panel, quiz_attempt_nav_panel or quiz_review_nav_panel
851      * @param $page the current page number.
852      * @param $showall whether we are showing the whole quiz on one page. (Used by review.php)
853      * @return quiz_nav_panel_base the requested object.
854      */
855     public function get_navigation_panel($panelclass, $page, $showall = false) {
856         $panel = new $panelclass($this, $this->get_review_options(), $page, $showall);
857         return $panel->get_contents();
858     }
860     /**
861      * Given a URL containing attempt={this attempt id}, return an array of variant URLs
862      * @param $url a URL.
863      * @return string HTML fragment. Comma-separated list of links to the other
864      * attempts with the attempt number as the link text. The curent attempt is
865      * included but is not a link.
866      */
867     public function links_to_other_attempts($url) {
868         $search = '/\battempt=' . $this->attempt->id . '\b/';
869         $attempts = quiz_get_user_attempts($this->quiz->id, $this->attempt->userid, 'all');
870         if (count($attempts) <= 1) {
871             return false;
872         }
873         $attemptlist = array();
874         foreach ($attempts as $at) {
875             if ($at->id == $this->attempt->id) {
876                 $attemptlist[] = '<strong>' . $at->attempt . '</strong>';
877             } else {
878                 $changedurl = preg_replace($search, 'attempt=' . $at->id, $url);
879                 $attemptlist[] = '<a href="' . s($changedurl) . '">' . $at->attempt . '</a>';
880             }
881         }
882         return implode(', ', $attemptlist);
883     }
885     // Methods for processing manual comments ==============================================
886     /**
887      * Process a manual comment for a question in this attempt.
888      * @param $questionid
889      * @param integer $questionid the question id
890      * @param string $comment the new comment from the teacher.
891      * @param mixed $grade the grade the teacher assigned, or '' to not change the grade.
892      * @return mixed true on success, a string error message if a problem is detected
893      *         (for example score out of range).
894      */
895     public function process_comment($questionid, $comment, $grade) {
896         // I am not sure it is a good idea to have update methods here - this
897         // class is only about getting data out of the question engine, and
898         // helping to display it, apart from this.
899         $this->ensure_question_loaded($questionid);
900         $this->ensure_state_loaded($questionid);
901         $state = $this->states[$questionid];
903         $error = question_process_comment($this->questions[$questionid],
904                 $state, $this->attempt, $comment, $grade);
906         // If the state was update (successfully), save the changes.
907         if (!is_string($error) && $state->changed) {
908             if (!save_question_session($this->questions[$questionid], $state)) {
909                 $error = get_string('errorudpatingquestionsession', 'quiz');
910             }
911             if (!quiz_save_best_grade($this->quiz, $this->attempt->userid)) {
912                 $error = get_string('errorudpatingbestgrade', 'quiz');
913             }
914         }
915         return $error;
916     }
918     /**
919      * Print the fields of the comment form for questions in this attempt.
920      * @param $questionid a question id.
921      * @param $prefix Prefix to add to all field names.
922      */
923     public function question_print_comment_fields($questionid, $prefix) {
924         global $DB;
926         $this->ensure_question_loaded($questionid);
927         $this->ensure_state_loaded($questionid);
929     /// Work out a nice title.
930         $student = $DB->get_record('user', array('id' => $this->get_userid()));
931         $a = new object();
932         $a->fullname = fullname($student, true);
933         $a->attempt = $this->get_attempt_number();
935         question_print_comment_fields($this->questions[$questionid],
936                 $this->states[$questionid], $prefix, $this->quiz, get_string('gradingattempt', 'quiz_grading', $a));
937     }
939     // Private methods =====================================================================
940     /**
941      * Check that the state of a particular question is loaded, and if not throw an exception.
942      * @param integer $id a question id.
943      */
944     private function ensure_state_loaded($id) {
945         if (!array_key_exists($id, $this->states) || isset($this->states[$id]->_partiallyloaded)) {
946             throw new moodle_quiz_exception($this, 'statenotloaded', $id);
947         }
948     }
950     /**
951      * @return string the layout of this quiz. Used by number_questions to
952      * work out which questions are on which pages.
953      */
954     protected function get_layout_string() {
955         return $this->attempt->layout;
956     }
958     /**
959      * Get a URL for a particular question on a particular page of the quiz.
960      * Used by {@link attempt_url()} and {@link review_url()}.
961      *
962      * @param string $script. Used in the URL like /mod/quiz/$script.php
963      * @param integer $questionid the id of a particular question on the page to jump to. 0 to just use the $page parameter.
964      * @param integer $page -1 to look up the page number from the questionid, otherwise the page number to go to.
965      * @param boolean $showall if true, return a URL with showall=1, and not page number
966      * @param integer $thispage the page we are currently on. Links to questoins on this
967      *      page will just be a fragment #q123. -1 to disable this.
968      * @return The requested URL.
969      */
970     protected function page_and_question_url($script, $questionid, $page, $showall, $thispage) {
971         global $CFG;
973         // Fix up $page
974         if ($page == -1) {
975             if ($questionid && !$showall) {
976                 $page = $this->questions[$questionid]->_page;
977             } else {
978                 $page = 0;
979             }
980         }
981         if ($showall) {
982             $page = 0;
983         }
985         // Work out the correct start to the URL.
986         if ($thispage == $page) {
987             $url = '';
988         } else {
989             $url = $CFG->wwwroot . '/mod/quiz/' . $script . '.php?attempt=' . $this->attempt->id;
990             if ($showall) {
991                 $url .= '&showall=1';
992             } else if ($page > 0) {
993                 $url .= '&page=' . $page;
994             }
995         }
997         // Add a fragment to scroll down ot the question.
998         if ($questionid) {
999             if ($questionid == reset($this->pagequestionids[$page])) {
1000                 // First question on page, go to top.
1001                 $url .= '#';
1002             } else {
1003                 $url .= '#q' . $questionid;
1004             }
1005         }
1007         return $url;
1008     }
1011 /**
1012  * A PHP Iterator for conviniently looping over the questions in a quiz. The keys are the question
1013  * numbers (with 'i' for descriptions) and the values are the question objects.
1014  *
1015  * @copyright 2008 Tim Hunt
1016  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1017  * @since Moodle 2.0
1018  */
1019 class quiz_attempt_question_iterator implements Iterator {
1020     private $attemptobj; // Reference to the quiz_attempt object we provide access to.
1021     private $questionids; // Array of the question ids within that attempt we are iterating over.
1023     /**
1024      * Constructor. Normally, you don't want to call this directly. Instead call
1025      * quiz_attempt::get_question_iterator
1026      *
1027      * @param quiz_attempt $attemptobj the quiz_attempt object we will be providing access to.
1028      * @param mixed $page as for @see{quiz_attempt::get_question_iterator}.
1029      */
1030     public function __construct(quiz_attempt $attemptobj, $page = 'all') {
1031         $this->attemptobj = $attemptobj;
1032         $this->questionids = $attemptobj->get_question_ids($page);
1033     }
1035     // Implementation of the Iterator interface ============================================
1036     public function rewind() {
1037         reset($this->questionids);
1038     }
1040     public function current() {
1041         $id = current($this->questionids);
1042         if ($id) {
1043             return $this->attemptobj->get_question($id);
1044         } else {
1045             return false;
1046         }
1047     }
1049     public function key() {
1050         $id = current($this->questionids);
1051         if ($id) {
1052             return $this->attemptobj->get_question($id)->_number;
1053         } else {
1054             return false;
1055         }
1056     }
1058     public function next() {
1059         $id = next($this->questionids);
1060         if ($id) {
1061             return $this->attemptobj->get_question($id);
1062         } else {
1063             return false;
1064         }
1065     }
1067     public function valid() {
1068         return $this->current() !== false;
1069     }
1072 /**
1073  * Represents the navigation panel, and builds a {@link block_contents} to allow
1074  * it to be output.
1075  *
1076  * @copyright 2008 Tim Hunt
1077  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1078  * @since Moodle 2.0
1079  */
1080 abstract class quiz_nav_panel_base {
1081     protected $attemptobj;
1082     protected $options;
1083     protected $page;
1084     protected $showall;
1086     public function __construct(quiz_attempt $attemptobj, $options, $page, $showall) {
1087           $this->attemptobj = $attemptobj;
1088           $this->options = $options;
1089           $this->page = $page;
1090           $this->showall = $showall;
1091     }
1093     protected function get_question_buttons() {
1094         $html = '<div class="qn_buttons">' . "\n";
1095         foreach ($this->attemptobj->get_question_iterator() as $number => $question) {
1096             $html .= $this->get_question_button($number, $question) . "\n";
1097         }
1098         $html .= "</div>\n";
1099         return $html;
1100     }
1102     protected function get_question_button($number, $question) {
1103         $strstate = get_string($this->attemptobj->get_question_status($question->id), 'quiz');
1104         $flagstate = '';
1105         if ($this->attemptobj->is_question_flagged($question->id)) {
1106             $flagstate = get_string('flagged', 'question');
1107         }
1108         return '<a href="' . s($this->get_question_url($question)) .
1109                 '" class="qnbutton ' . $this->get_question_state_classes($question) .
1110                 '" id="quiznavbutton' . $question->id . '" title="' . $strstate . '">' .
1111                 $number . ' <span class="accesshide"> (' . $strstate . '
1112                     <span class="flagstate">' . $flagstate . '</span>)</span></a>';
1113     }
1115     protected function get_before_button_bits() {
1116         return '';
1117     }
1119     abstract protected function get_end_bits();
1121     abstract protected function get_question_url($question);
1123     protected function get_user_picture() {
1124         global $DB, $OUTPUT;
1125         $user = $DB->get_record('user', array('id' => $this->attemptobj->get_userid()));
1126         $output = '';
1127         $output .= '<div id="user-picture" class="clearfix">';
1128         $output .= $OUTPUT->user_picture($user, array('courseid'=>$this->attemptobj->get_courseid()));
1129         $output .= ' ' . fullname($user);
1130         $output .= '</div>';
1131         return $output;
1132     }
1134     protected function get_question_state_classes($question) {
1135         // The current status of the question.
1136         $classes = $this->attemptobj->get_question_status($question->id);
1138         // Plus a marker for the current page.
1139         if ($this->showall || $question->_page == $this->page) {
1140             $classes .= ' thispage';
1141         }
1143         // Plus a marker for flagged questions.
1144         if ($this->attemptobj->is_question_flagged($question->id)) {
1145             $classes .= ' flagged';
1146         }
1147         return $classes;
1148     }
1150     public function get_contents() {
1151         global $PAGE;
1152         $PAGE->requires->js_init_call('M.mod_quiz.nav.init', null, false, quiz_get_js_module());
1154         $content = '';
1155         if ($this->attemptobj->get_quiz()->showuserpicture) {
1156             $content .= $this->get_user_picture() . "\n";
1157         }
1158         $content .= $this->get_before_button_bits();
1159         $content .= $this->get_question_buttons() . "\n";
1160         $content .= '<div class="othernav">' . "\n" . $this->get_end_bits() . "\n</div>\n";
1162         $bc = new block_contents();
1163         $bc->id = 'quiznavigation';
1164         $bc->title = get_string('quiznavigation', 'quiz');
1165         $bc->content = $content;
1166         return $bc;
1167     }
1170 /**
1171  * Specialisation of {@link quiz_nav_panel_base} for the attempt quiz page.
1172  *
1173  * @copyright 2008 Tim Hunt
1174  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1175  * @since Moodle 2.0
1176  */
1177 class quiz_attempt_nav_panel extends quiz_nav_panel_base {
1178     protected function get_question_url($question) {
1179         return $this->attemptobj->attempt_url($question->id, -1, $this->page);
1180     }
1182     protected function get_before_button_bits() {
1183         return '<div id="quiznojswarning">' . get_string('navnojswarning', 'quiz') . "</div>\n";
1184     }
1186     protected function get_end_bits() {
1187         global $PAGE;
1188         $output = '';
1189         $output .= '<a href="' . s($this->attemptobj->summary_url()) . '" class="endtestlink">' . get_string('endtest', 'quiz') . '</a>';
1190         $output .= $this->attemptobj->get_timer_html();
1191         return $output;
1192     }
1195 /**
1196  * Specialisation of {@link quiz_nav_panel_base} for the review quiz page.
1197  *
1198  * @copyright 2008 Tim Hunt
1199  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1200  * @since Moodle 2.0
1201  */
1202 class quiz_review_nav_panel extends quiz_nav_panel_base {
1203     protected function get_question_url($question) {
1204         return $this->attemptobj->review_url($question->id, -1, $this->showall, $this->page);
1205     }
1207     protected function get_end_bits() {
1208         $html = '';
1209         if ($this->attemptobj->get_num_pages() > 1) {
1210             if ($this->showall) {
1211                 $html = '<a href="' . s($this->attemptobj->review_url(0, 0, false)) . '">' . get_string('showeachpage', 'quiz') . '</a>';
1212             } else {
1213                 $html = '<a href="' . s($this->attemptobj->review_url(0, 0, true)) . '">' . get_string('showall', 'quiz') . '</a>';
1214             }
1215         }
1216         $accessmanager = $this->attemptobj->get_access_manager(time());
1217         $html .= $accessmanager->print_finish_review_link($this->attemptobj->is_preview_user(), true);
1218         return $html;
1219     }