mod/quiz/attemptlib.php

   1 <?php
   2
   3 // This file is part of Moodle - http://moodle.org/
   4 //
   5 // Moodle is free software: you can redistribute it and/or modify
   6 // it under the terms of the GNU General Public License as published by
   7 // the Free Software Foundation, either version 3 of the License, or
   8 // (at your option) any later version.
   9 //
  10 // Moodle is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 // GNU General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU General Public License
  16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  17
  18 /**
  19  * 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  */
  28
  29
  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 }
  46
  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.
  67
  68     // Fields set later if that data is needed.
  69     protected $questions = null;
  70     protected $accessmanager = null;
  71     protected $ispreviewuser = null;
  72
  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     }
  92
  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;
 102
 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         }
 112
 113         // Update quiz with override information
 114         $quiz = quiz_update_effective_access($quiz, $userid);
 115
 116         return new quiz($quiz, $cm, $course);
 117     }
 118
 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     }
 129
 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     }
 143
 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     }
 161
 162     // Simple getters ======================================================================
 163     /** @return integer the course id. */
 164     public function get_courseid() {
 165         return $this->course->id;
 166     }
 167
 168     /** @return object the row of the course table. */
 169     public function get_course() {
 170         return $this->course;
 171     }
 172
 173     /** @return integer the quiz id. */
 174     public function get_quizid() {
 175         return $this->quiz->id;
 176     }
 177
 178     /** @return object the row of the quiz table. */
 179     public function get_quiz() {
 180         return $this->quiz;
 181     }
 182
 183     /** @return string the name of this quiz. */
 184     public function get_quiz_name() {
 185         return $this->quiz->name;
 186     }
 187
 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     }
 192
 193     /** @return integer the course_module id. */
 194     public function get_cmid() {
 195         return $this->cm->id;
 196     }
 197
 198     /** @return object the course_module object. */
 199     public function get_cm() {
 200         return $this->cm;
 201     }
 202
 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     }
 213
 214     /**
 215      * @return integer number fo pages in this quiz.
 216      */
 217     public function get_num_pages() {
 218         return count($this->pagequestionids);
 219     }
 220
 221
 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     }
 229
 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     }
 237
 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     }
 252
 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     }
 273
 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     }
 285
 286     public function get_overall_feedback($grade) {
 287         return quiz_feedback_for_grade($grade, $this->quiz, $this->context, $this->cm);
 288     }
 289
 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     }
 296
 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     }
 303
 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     }
 312
 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     }
 320
 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     }
 329
 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     }
 337
 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         return new moodle_url('/mod/quiz/review.php', array('attempt' => $attemptid));
 344     }
 345
 346     // Bits of content =====================================================================
 347
 348     /**
 349      * @param string $title the name of this particular quiz page.
 350      * @return array the data that needs to be sent to print_header_simple as the $navigation
 351      * parameter.
 352      */
 353     public function navigation($title) {
 354         global $PAGE;
 355         $PAGE->navbar->add($title);
 356         return '';
 357     }
 358
 359     // Private methods =====================================================================
 360     /**
 361      *  Check that the definition of a particular question is loaded, and if not throw an exception.
 362      *  @param $id a questionid.
 363      */
 364     protected function ensure_question_loaded($id) {
 365         if (isset($this->questions[$id]->_partiallyloaded)) {
 366             throw new moodle_quiz_exception($this, 'questionnotloaded', $id);
 367         }
 368     }
 369
 370     /**
 371      * Populate {@link $questionids} and {@link $pagequestionids} from the layout.
 372      */
 373     protected function determine_layout() {
 374         $this->questionids = array();
 375         $this->pagequestionids = array();
 376
 377         // Get the appropriate layout string (from quiz or attempt).
 378         $layout = quiz_clean_layout($this->get_layout_string(), true);
 379         if (empty($layout)) {
 380             // Nothing to do.
 381             return;
 382         }
 383
 384         // Break up the layout string into pages.
 385         $pagelayouts = explode(',0', $layout);
 386
 387         // Strip off any empty last page (normally there is one).
 388         if (end($pagelayouts) == '') {
 389             array_pop($pagelayouts);
 390         }
 391
 392         // File the ids into the arrays.
 393         $this->questionids = array();
 394         $this->pagequestionids = array();
 395         foreach ($pagelayouts as $page => $pagelayout) {
 396             $pagelayout = trim($pagelayout, ',');
 397             if ($pagelayout == '') continue;
 398             $this->pagequestionids[$page] = explode(',', $pagelayout);
 399             foreach ($this->pagequestionids[$page] as $id) {
 400                 $this->questionids[] = $id;
 401             }
 402         }
 403     }
 404
 405     /**
 406      * Number the questions, adding a _number field to each one.
 407      */
 408     private function number_questions() {
 409         $number = 1;
 410         foreach ($this->pagequestionids as $page => $questionids) {
 411             foreach ($questionids as $id) {
 412                 if ($this->questions[$id]->length > 0) {
 413                     $this->questions[$id]->_number = $number;
 414                     $number += $this->questions[$id]->length;
 415                 } else {
 416                     $this->questions[$id]->_number = get_string('infoshort', 'quiz');
 417                 }
 418                 $this->questions[$id]->_page = $page;
 419             }
 420         }
 421     }
 422
 423     /**
 424      * @return string the layout of this quiz. Used by number_questions to
 425      * work out which questions are on which pages.
 426      */
 427     protected function get_layout_string() {
 428         return $this->quiz->questions;
 429     }
 430 }
 431
 432 /**
 433  * This class extends the quiz class to hold data about the state of a particular attempt,
 434  * in addition to the data about the quiz.
 435  *
 436  * @copyright 2008 Tim Hunt
 437  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 438  * @since Moodle 2.0
 439  */
 440 class quiz_attempt extends quiz {
 441     // Fields initialised in the constructor.
 442     protected $attempt;
 443
 444     // Fields set later if that data is needed.
 445     protected $states = array();
 446     protected $reviewoptions = null;
 447
 448     // Constructor =========================================================================
 449     /**
 450      * Constructor assuming we already have the necessary data loaded.
 451      *
 452      * @param object $attempt the row of the quiz_attempts table.
 453      * @param object $quiz the quiz object for this attempt and user.
 454      * @param object $cm the course_module object for this quiz.
 455      * @param object $course the row from the course table for the course we belong to.
 456      */
 457     function __construct($attempt, $quiz, $cm, $course) {
 458         $this->attempt = $attempt;
 459         parent::__construct($quiz, $cm, $course);
 460         $this->preload_questions();
 461         $this->preload_question_states();
 462     }
 463
 464     /**
 465      * Static function to create a new quiz_attempt object given an attemptid.
 466      *
 467      * @param integer $attemptid the attempt id.
 468      * @return quiz_attempt the new quiz_attempt object
 469      */
 470     static public function create($attemptid) {
 471         global $DB;
 472
 473         if (!$attempt = quiz_load_attempt($attemptid)) {
 474             throw new moodle_exception('invalidattemptid', 'quiz');
 475         }
 476         if (!$quiz = $DB->get_record('quiz', array('id' => $attempt->quiz))) {
 477             throw new moodle_exception('invalidquizid', 'quiz');
 478         }
 479         if (!$course = $DB->get_record('course', array('id' => $quiz->course))) {
 480             throw new moodle_exception('invalidcoursemodule');
 481         }
 482         if (!$cm = get_coursemodule_from_instance('quiz', $quiz->id, $course->id)) {
 483             throw new moodle_exception('invalidcoursemodule');
 484         }
 485         // Update quiz with override information
 486         $quiz = quiz_update_effective_access($quiz, $attempt->userid);
 487
 488         return new quiz_attempt($attempt, $quiz, $cm, $course);
 489     }
 490
 491     // Functions for loading more data =====================================================
 492     /**
 493      * Load the state of a number of questions that have already been loaded.
 494      *
 495      * @param array $questionids question ids to process. Blank = all.
 496      */
 497     public function load_question_states($questionids = null) {
 498         if (is_null($questionids)) {
 499             $questionids = $this->questionids;
 500         }
 501         $questionstoprocess = array();
 502         foreach ($questionids as $id) {
 503             $this->ensure_question_loaded($id);
 504             $questionstoprocess[$id] = $this->questions[$id];
 505         }
 506         if (!question_load_states($questionstoprocess, $this->states,
 507                 $this->quiz, $this->attempt)) {
 508             throw new moodle_quiz_exception($this, 'cannotrestore');
 509         }
 510     }
 511
 512     /**
 513      * Load basic information about the state of each question.
 514      *
 515      * This is enough to, for example, show the state of each question in the
 516      * navigation panel, but only takes one DB query.
 517      */
 518     public function preload_question_states() {
 519         if (empty($this->questionids)) {
 520             throw new moodle_quiz_exception($this, 'noquestions', $this->edit_url());
 521         }
 522         $this->states = question_preload_states($this->attempt->uniqueid);
 523         if (!$this->states) {
 524             $this->states = array();
 525         }
 526     }
 527
 528     /**
 529      * Load a particular state of a particular question. Used by the reviewquestion.php
 530      * script to let the teacher walk through the entire sequence of a student's
 531      * interaction with a question.
 532      *
 533      * @param $questionid the question id
 534      * @param $stateid the id of the particular state to load.
 535      */
 536     public function load_specific_question_state($questionid, $stateid) {
 537         global $DB;
 538         $state = question_load_specific_state($this->questions[$questionid],
 539                 $this->quiz, $this->attempt->uniqueid, $stateid);
 540         if ($state === false) {
 541             throw new moodle_quiz_exception($this, 'invalidstateid');
 542         }
 543         $this->states[$questionid] = $state;
 544     }
 545
 546     // Simple getters ======================================================================
 547     /** @return integer the attempt id. */
 548     public function get_attemptid() {
 549         return $this->attempt->id;
 550     }
 551
 552     /** @return integer the attempt unique id. */
 553     public function get_uniqueid() {
 554         return $this->attempt->uniqueid;
 555     }
 556
 557     /** @return object the row from the quiz_attempts table. */
 558     public function get_attempt() {
 559         return $this->attempt;
 560     }
 561
 562     /** @return integer the number of this attemp (is it this user's first, second, ... attempt). */
 563     public function get_attempt_number() {
 564         return $this->attempt->attempt;
 565     }
 566
 567     /** @return integer the id of the user this attempt belongs to. */
 568     public function get_userid() {
 569         return $this->attempt->userid;
 570     }
 571
 572     /** @return boolean whether this attempt has been finished (true) or is still in progress (false). */
 573     public function is_finished() {
 574         return $this->attempt->timefinish != 0;
 575     }
 576
 577     /** @return boolean whether this attempt is a preview attempt. */
 578     public function is_preview() {
 579         return $this->attempt->preview;
 580     }
 581
 582     /**
 583      * Is this a student dealing with their own attempt/teacher previewing,
 584      * or someone with 'mod/quiz:viewreports' reviewing someone elses attempt.
 585      *
 586      * @return boolean whether this situation should be treated as someone looking at their own
 587      * attempt. The distinction normally only matters when an attempt is being reviewed.
 588      */
 589     public function is_own_attempt() {
 590         global $USER;
 591         return $this->attempt->userid == $USER->id &&
 592                 (!$this->is_preview_user() || $this->attempt->preview);
 593     }
 594
 595     /**
 596      * Check the appropriate capability to see whether this user may review their own attempt.
 597      * If not, prints an error.
 598      */
 599     public function check_review_capability() {
 600         if (!$this->has_capability('mod/quiz:viewreports')) {
 601             if ($this->get_review_options()->quizstate == QUIZ_STATE_IMMEDIATELY) {
 602                 $this->require_capability('mod/quiz:attempt');
 603             } else {
 604                 $this->require_capability('mod/quiz:reviewmyattempts');
 605             }
 606         }
 607     }
 608
 609     /**
 610      * Get the current state of a question in the attempt.
 611      *
 612      * @param $questionid a questionid.
 613      * @return object the state.
 614      */
 615     public function get_question_state($questionid) {
 616         return $this->states[$questionid];
 617     }
 618
 619     /**
 620      * Wrapper that calls quiz_get_reviewoptions with the appropriate arguments.
 621      *
 622      * @return object the review options for this user on this attempt.
 623      */
 624     public function get_review_options() {
 625         if (is_null($this->reviewoptions)) {
 626             $this->reviewoptions = quiz_get_reviewoptions($this->quiz, $this->attempt, $this->context);
 627         }
 628         return $this->reviewoptions;
 629     }
 630
 631     /**
 632      * Wrapper that calls get_render_options with the appropriate arguments.
 633      *
 634      * @param integer questionid the quetsion to get the render options for.
 635      * @return object the render options for this user on this attempt.
 636      */
 637     public function get_render_options($questionid) {
 638         return quiz_get_renderoptions($this->quiz, $this->attempt, $this->context,
 639                 $this->get_question_state($questionid));
 640     }
 641
 642     /**
 643      * Get a quiz_attempt_question_iterator for either a page of the quiz, or a whole quiz.
 644      * You must have called load_questions with an appropriate argument first.
 645      *
 646      * @param mixed $page as for the @see{get_question_ids} method.
 647      * @return quiz_attempt_question_iterator the requested iterator.
 648      */
 649     public function get_question_iterator($page = 'all') {
 650         return new quiz_attempt_question_iterator($this, $page);
 651     }
 652
 653     /**
 654      * Return a summary of the current state of a question in this attempt. You must previously
 655      * have called load_question_states to load the state data about this question.
 656      *
 657      * @param integer $questionid question id of a question that belongs to this quiz.
 658      * @return string a brief string (that could be used as a CSS class name, for example)
 659      * that describes the current state of a question in this attempt. Possible results are:
 660      * open|saved|closed|correct|partiallycorrect|incorrect.
 661      */
 662     public function get_question_status($questionid) {
 663         $state = $this->states[$questionid];
 664         switch ($state->event) {
 665             case QUESTION_EVENTOPEN:
 666                 return 'open';
 667
 668             case QUESTION_EVENTSAVE:
 669             case QUESTION_EVENTGRADE:
 670             case QUESTION_EVENTSUBMIT:
 671                 return 'answered';
 672
 673             case QUESTION_EVENTCLOSEANDGRADE:
 674             case QUESTION_EVENTCLOSE:
 675             case QUESTION_EVENTMANUALGRADE:
 676                 $options = $this->get_render_options($questionid);
 677                 if ($options->scores && $this->questions[$questionid]->maxgrade > 0) {
 678                     return question_get_feedback_class($state->last_graded->raw_grade /
 679                             $this->questions[$questionid]->maxgrade);
 680                 } else {
 681                     return 'closed';
 682                 }
 683
 684             default:
 685                 $a = new stdClass;
 686                 $a->event = $state->event;
 687                 $a->questionid = $questionid;
 688                 $a->attemptid = $this->attempt->id;
 689                 throw new moodle_quiz_exception($this, 'errorunexpectedevent', $a);
 690         }
 691     }
 692
 693     /**
 694      * @param integer $questionid question id of a question that belongs to this quiz.
 695      * @return boolean whether this question hss been flagged by the attempter.
 696      */
 697     public function is_question_flagged($questionid) {
 698         $state = $this->states[$questionid];
 699         return $state->flagged;
 700     }
 701
 702     /**
 703      * Return the grade obtained on a particular question, if the user is permitted to see it.
 704      * You must previously have called load_question_states to load the state data about this question.
 705      *
 706      * @param integer $questionid question id of a question that belongs to this quiz.
 707      * @return string the formatted grade, to the number of decimal places specified by the quiz.
 708      */
 709     public function get_question_score($questionid) {
 710         $options = $this->get_render_options($questionid);
 711         if ($options->scores) {
 712             return quiz_format_question_grade($this->quiz, $this->states[$questionid]->last_graded->grade);
 713         } else {
 714             return '';
 715         }
 716     }
 717
 718     // URLs related to this attempt ========================================================
 719     /**
 720      * @param integer $questionid a question id. If set, will add a fragment to the URL
 721      * to jump to a particuar question on the page.
 722      * @param integer $page if specified, the URL of this particular page of the attempt, otherwise
 723      * the URL will go to the first page. If -1, deduce $page from $questionid.
 724      * @param integer $thispage if not -1, the current page. Will cause links to other things on
 725      * this page to be output as only a fragment.
 726      * @return string the URL to continue this attempt.
 727      */
 728     public function attempt_url($questionid = 0, $page = -1, $thispage = -1) {
 729         return $this->page_and_question_url('attempt', $questionid, $page, false, $thispage);
 730     }
 731
 732     /**
 733      * @return string the URL of this quiz's summary page.
 734      */
 735     public function summary_url() {
 736         global $CFG;
 737         return $CFG->wwwroot . '/mod/quiz/summary.php?attempt=' . $this->attempt->id;
 738     }
 739
 740     /**
 741      * @return string the URL of this quiz's summary page.
 742      */
 743     public function processattempt_url() {
 744         global $CFG;
 745         return $CFG->wwwroot . '/mod/quiz/processattempt.php';
 746     }
 747
 748     /**
 749      * @param integer $questionid a question id. If set, will add a fragment to the URL
 750      * to jump to a particuar question on the page. If -1, deduce $page from $questionid.
 751      * @param integer $page if specified, the URL of this particular page of the attempt, otherwise
 752      * the URL will go to the first page.
 753      * @param boolean $showall if true, the URL will be to review the entire attempt on one page,
 754      * and $page will be ignored.
 755      * @param integer $thispage if not -1, the current page. Will cause links to other things on
 756      * this page to be output as only a fragment.
 757      * @return string the URL to review this attempt.
 758      */
 759     public function review_url($questionid = 0, $page = -1, $showall = false, $thispage = -1) {
 760         return $this->page_and_question_url('review', $questionid, $page, $showall, $thispage);
 761     }
 762
 763     // Bits of content =====================================================================
 764     /**
 765      * Initialise the JS etc. required all the questions on a page..
 766      * @param mixed $page a page number, or 'all'.
 767      */
 768     public function get_html_head_contributions($page = 'all') {
 769         global $PAGE;
 770         question_get_html_head_contributions($this->get_question_ids($page), $this->questions, $this->states);
 771     }
 772
 773     /**
 774      * Initialise the JS etc. required by one question.
 775      * @param integer $questionid the question id.
 776      */
 777     public function get_question_html_head_contributions($questionid) {
 778         question_get_html_head_contributions(array($questionid), $this->questions, $this->states);
 779     }
 780
 781     /**
 782      * Print the HTML for the start new preview button.
 783      */
 784     public function print_restart_preview_button() {
 785         global $CFG, $OUTPUT;
 786         echo $OUTPUT->container_start('controls');
 787         $url = new moodle_url($this->start_attempt_url(), array('forcenew' => true));
 788         echo $OUTPUT->single_button($url, get_string('startagain', 'quiz'));
 789         echo $OUTPUT->container_end();
 790     }
 791
 792     /**
 793      * Return the HTML of the quiz timer.
 794      * @return string HTML content.
 795      */
 796     public function get_timer_html() {
 797         return '<div id="quiz-timer">' . get_string('timeleft', 'quiz') .
 798                 ' <span id="quiz-time-left"></span></div>';
 799     }
 800
 801     /**
 802      * Wrapper round print_question from lib/questionlib.php.
 803      *
 804      * @param integer $id the id of a question in this quiz attempt.
 805      * @param boolean $reviewing is the being printed on an attempt or a review page.
 806      * @param string $thispageurl the URL of the page this question is being printed on.
 807      */
 808     public function print_question($id, $reviewing, $thispageurl = '') {
 809         global $CFG;
 810
 811         if ($reviewing) {
 812             $options = $this->get_review_options();
 813         } else {
 814             $options = $this->get_render_options($id);
 815         }
 816         if ($thispageurl instanceof moodle_url) {
 817             $thispageurl = $thispageurl->out(false);
 818         }
 819         if ($thispageurl) {
 820             $this->quiz->thispageurl = str_replace($CFG->wwwroot, '', $thispageurl);
 821         } else {
 822             unset($thispageurl);
 823         }
 824         print_question($this->questions[$id], $this->states[$id], $this->questions[$id]->_number,
 825                 $this->quiz, $options);
 826     }
 827
 828     public function check_file_access($questionid, $isreviewing, $contextid, $component,
 829             $filearea, $args, $forcedownload) {
 830         if ($isreviewing) {
 831             $options = $this->get_review_options();
 832         } else {
 833             $options = $this->get_render_options($questionid);
 834         }
 835         // XXX: mulitichoice type needs quiz id to get maxgrade
 836         $options->quizid = $this->attempt->quiz;
 837         return question_check_file_access($this->questions[$questionid],
 838                 $this->get_question_state($questionid), $options, $contextid,
 839                 $component, $filearea, $args, $forcedownload);
 840     }
 841
 842     /**
 843      * Triggers the sending of the notification emails at the end of this attempt.
 844      */
 845     public function quiz_send_notification_emails() {
 846         quiz_send_notification_emails($this->course, $this->quiz, $this->attempt,
 847                 $this->context, $this->cm);
 848     }
 849
 850     /**
 851      * Get the navigation panel object for this attempt.
 852      *
 853      * @param $panelclass The type of panel, quiz_attempt_nav_panel or quiz_review_nav_panel
 854      * @param $page the current page number.
 855      * @param $showall whether we are showing the whole quiz on one page. (Used by review.php)
 856      * @return quiz_nav_panel_base the requested object.
 857      */
 858     public function get_navigation_panel($panelclass, $page, $showall = false) {
 859         $panel = new $panelclass($this, $this->get_review_options(), $page, $showall);
 860         return $panel->get_contents();
 861     }
 862
 863     /**
 864      * Given a URL containing attempt={this attempt id}, return an array of variant URLs
 865      * @param $url a URL.
 866      * @return string HTML fragment. Comma-separated list of links to the other
 867      * attempts with the attempt number as the link text. The curent attempt is
 868      * included but is not a link.
 869      */
 870     public function links_to_other_attempts($url) {
 871         $search = '/\battempt=' . $this->attempt->id . '\b/';
 872         $attempts = quiz_get_user_attempts($this->quiz->id, $this->attempt->userid, 'all');
 873         if (count($attempts) <= 1) {
 874             return false;
 875         }
 876         $attemptlist = array();
 877         foreach ($attempts as $at) {
 878             if ($at->id == $this->attempt->id) {
 879                 $attemptlist[] = '<strong>' . $at->attempt . '</strong>';
 880             } else {
 881                 $changedurl = preg_replace($search, 'attempt=' . $at->id, $url);
 882                 $attemptlist[] = '<a href="' . s($changedurl) . '">' . $at->attempt . '</a>';
 883             }
 884         }
 885         return implode(', ', $attemptlist);
 886     }
 887
 888     // Methods for processing manual comments ==============================================
 889     /**
 890      * Process a manual comment for a question in this attempt.
 891      * @param $questionid
 892      * @param integer $questionid the question id
 893      * @param string $comment the new comment from the teacher.
 894      * @param mixed $grade the grade the teacher assigned, or '' to not change the grade.
 895      * @return mixed true on success, a string error message if a problem is detected
 896      *         (for example score out of range).
 897      */
 898     public function process_comment($questionid, $comment, $commentformat, $grade) {
 899         // I am not sure it is a good idea to have update methods here - this
 900         // class is only about getting data out of the question engine, and
 901         // helping to display it, apart from this.
 902         $this->ensure_question_loaded($questionid);
 903         $this->ensure_state_loaded($questionid);
 904         $state = $this->states[$questionid];
 905
 906         $error = question_process_comment($this->questions[$questionid],
 907                 $state, $this->attempt, $comment, $commentformat, $grade);
 908
 909         // If the state was update (successfully), save the changes.
 910         if (!is_string($error) && $state->changed) {
 911             if (!save_question_session($this->questions[$questionid], $state)) {
 912                 $error = get_string('errorudpatingquestionsession', 'quiz');
 913             }
 914             if (!quiz_save_best_grade($this->quiz, $this->attempt->userid)) {
 915                 $error = get_string('errorudpatingbestgrade', 'quiz');
 916             }
 917         }
 918         return $error;
 919     }
 920
 921     /**
 922      * Print the fields of the comment form for questions in this attempt.
 923      * @param $questionid a question id.
 924      * @param $prefix Prefix to add to all field names.
 925      */
 926     public function question_print_comment_fields($questionid, $prefix) {
 927         global $DB;
 928
 929         $this->ensure_question_loaded($questionid);
 930         $this->ensure_state_loaded($questionid);
 931
 932     /// Work out a nice title.
 933         $student = $DB->get_record('user', array('id' => $this->get_userid()));
 934         $a = new stdClass();
 935         $a->fullname = fullname($student, true);
 936         $a->attempt = $this->get_attempt_number();
 937
 938         question_print_comment_fields($this->questions[$questionid],
 939                 $this->states[$questionid], $prefix, $this->quiz, get_string('gradingattempt', 'quiz_grading', $a));
 940     }
 941
 942     // Private methods =====================================================================
 943     /**
 944      * Check that the state of a particular question is loaded, and if not throw an exception.
 945      * @param integer $id a question id.
 946      */
 947     private function ensure_state_loaded($id) {
 948         if (!array_key_exists($id, $this->states) || isset($this->states[$id]->_partiallyloaded)) {
 949             throw new moodle_quiz_exception($this, 'statenotloaded', $id);
 950         }
 951     }
 952
 953     /**
 954      * @return string the layout of this quiz. Used by number_questions to
 955      * work out which questions are on which pages.
 956      */
 957     protected function get_layout_string() {
 958         return $this->attempt->layout;
 959     }
 960
 961     /**
 962      * Get a URL for a particular question on a particular page of the quiz.
 963      * Used by {@link attempt_url()} and {@link review_url()}.
 964      *
 965      * @param string $script. Used in the URL like /mod/quiz/$script.php
 966      * @param integer $questionid the id of a particular question on the page to jump to. 0 to just use the $page parameter.
 967      * @param integer $page -1 to look up the page number from the questionid, otherwise the page number to go to.
 968      * @param boolean $showall if true, return a URL with showall=1, and not page number
 969      * @param integer $thispage the page we are currently on. Links to questoins on this
 970      *      page will just be a fragment #q123. -1 to disable this.
 971      * @return The requested URL.
 972      */
 973     protected function page_and_question_url($script, $questionid, $page, $showall, $thispage) {
 974         global $CFG;
 975
 976         // Fix up $page
 977         if ($page == -1) {
 978             if ($questionid && !$showall) {
 979                 $page = $this->questions[$questionid]->_page;
 980             } else {
 981                 $page = 0;
 982             }
 983         }
 984         if ($showall) {
 985             $page = 0;
 986         }
 987
 988         // Work out the correct start to the URL.
 989         if ($thispage == $page) {
 990             $url = '';
 991         } else {
 992             $url = $CFG->wwwroot . '/mod/quiz/' . $script . '.php?attempt=' . $this->attempt->id;
 993             if ($showall) {
 994                 $url .= '&showall=1';
 995             } else if ($page > 0) {
 996                 $url .= '&page=' . $page;
 997             }
 998         }
 999
1000         // Add a fragment to scroll down to the question.
1001         if ($questionid) {
1002             if ($questionid == reset($this->pagequestionids[$page])) {
1003                 // First question on page, go to top.
1004                 $url .= '#';
1005             } else {
1006                 $url .= '#q' . $questionid;
1007             }
1008         }
1009
1010         return $url;
1011     }
1012 }
1013
1014 /**
1015  * A PHP Iterator for conviniently looping over the questions in a quiz. The keys are the question
1016  * numbers (with 'i' for descriptions) and the values are the question objects.
1017  *
1018  * @copyright 2008 Tim Hunt
1019  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1020  * @since Moodle 2.0
1021  */
1022 class quiz_attempt_question_iterator implements Iterator {
1023     private $attemptobj; // Reference to the quiz_attempt object we provide access to.
1024     private $questionids; // Array of the question ids within that attempt we are iterating over.
1025
1026     /**
1027      * Constructor. Normally, you don't want to call this directly. Instead call
1028      * quiz_attempt::get_question_iterator
1029      *
1030      * @param quiz_attempt $attemptobj the quiz_attempt object we will be providing access to.
1031      * @param mixed $page as for @see{quiz_attempt::get_question_iterator}.
1032      */
1033     public function __construct(quiz_attempt $attemptobj, $page = 'all') {
1034         $this->attemptobj = $attemptobj;
1035         $this->questionids = $attemptobj->get_question_ids($page);
1036     }
1037
1038     // Implementation of the Iterator interface ============================================
1039     public function rewind() {
1040         reset($this->questionids);
1041     }
1042
1043     public function current() {
1044         $id = current($this->questionids);
1045         if ($id) {
1046             return $this->attemptobj->get_question($id);
1047         } else {
1048             return false;
1049         }
1050     }
1051
1052     public function key() {
1053         $id = current($this->questionids);
1054         if ($id) {
1055             return $this->attemptobj->get_question($id)->_number;
1056         } else {
1057             return false;
1058         }
1059     }
1060
1061     public function next() {
1062         $id = next($this->questionids);
1063         if ($id) {
1064             return $this->attemptobj->get_question($id);
1065         } else {
1066             return false;
1067         }
1068     }
1069
1070     public function valid() {
1071         return $this->current() !== false;
1072     }
1073 }
1074
1075 /**
1076  * Represents the navigation panel, and builds a {@link block_contents} to allow
1077  * it to be output.
1078  *
1079  * @copyright 2008 Tim Hunt
1080  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1081  * @since Moodle 2.0
1082  */
1083 abstract class quiz_nav_panel_base {
1084     /** @var quiz_attempt */
1085     protected $attemptobj;
1086     /** @var question_display_options */
1087     protected $options;
1088     /** @var integer */
1089     protected $page;
1090     /** @var boolean */
1091     protected $showall;
1092
1093     public function __construct(quiz_attempt $attemptobj, $options, $page, $showall) {
1094         $this->attemptobj = $attemptobj;
1095         $this->options = $options;
1096         $this->page = $page;
1097         $this->showall = $showall;
1098     }
1099
1100     protected function get_question_buttons() {
1101         $html = '<div class="qn_buttons">' . "\n";
1102         foreach ($this->attemptobj->get_question_iterator() as $number => $question) {
1103             $html .= $this->get_question_button($number, $question) . "\n";
1104         }
1105         $html .= "</div>\n";
1106         return $html;
1107     }
1108
1109     protected function get_question_button($number, $question) {
1110         $strstate = get_string($this->attemptobj->get_question_status($question->id), 'quiz');
1111         $flagstate = '';
1112         if ($this->attemptobj->is_question_flagged($question->id)) {
1113             $flagstate = get_string('flagged', 'question');
1114         }
1115         return '<a href="' . s($this->get_question_url($question)) .
1116                 '" class="qnbutton ' . $this->get_question_state_classes($question) .
1117                 '" id="quiznavbutton' . $question->id . '" title="' . $strstate . '">' .
1118                 $number . ' <span class="accesshide"> (' . $strstate . '
1119                     <span class="flagstate">' . $flagstate . '</span>)</span></a>';
1120     }
1121
1122     protected function get_before_button_bits() {
1123         return '';
1124     }
1125
1126     abstract protected function get_end_bits();
1127
1128     abstract protected function get_question_url($question);
1129
1130     protected function get_user_picture() {
1131         global $DB, $OUTPUT;
1132         $user = $DB->get_record('user', array('id' => $this->attemptobj->get_userid()));
1133         $output = '';
1134         $output .= '<div id="user-picture" class="clearfix">';
1135         $output .= $OUTPUT->user_picture($user, array('courseid'=>$this->attemptobj->get_courseid()));
1136         $output .= ' ' . fullname($user);
1137         $output .= '</div>';
1138         return $output;
1139     }
1140
1141     protected function get_question_state_classes($question) {
1142         // The current status of the question.
1143         $classes = $this->attemptobj->get_question_status($question->id);
1144
1145         // Plus a marker for the current page.
1146         if ($this->showall || $question->_page == $this->page) {
1147             $classes .= ' thispage';
1148         }
1149
1150         // Plus a marker for flagged questions.
1151         if ($this->attemptobj->is_question_flagged($question->id)) {
1152             $classes .= ' flagged';
1153         }
1154         return $classes;
1155     }
1156
1157     public function get_contents() {
1158         global $PAGE;
1159         $PAGE->requires->js_init_call('M.mod_quiz.nav.init', null, false, quiz_get_js_module());
1160
1161         $content = '';
1162         if ($this->attemptobj->get_quiz()->showuserpicture) {
1163             $content .= $this->get_user_picture() . "\n";
1164         }
1165         $content .= $this->get_before_button_bits();
1166         $content .= $this->get_question_buttons() . "\n";
1167         $content .= '<div class="othernav">' . "\n" . $this->get_end_bits() . "\n</div>\n";
1168
1169         $bc = new block_contents();
1170         $bc->id = 'quiznavigation';
1171         $bc->title = get_string('quiznavigation', 'quiz');
1172         $bc->content = $content;
1173         return $bc;
1174     }
1175 }
1176
1177 /**
1178  * Specialisation of {@link quiz_nav_panel_base} for the attempt quiz page.
1179  *
1180  * @copyright 2008 Tim Hunt
1181  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1182  * @since Moodle 2.0
1183  */
1184 class quiz_attempt_nav_panel extends quiz_nav_panel_base {
1185     protected function get_question_url($question) {
1186         return $this->attemptobj->attempt_url($question->id, -1, $this->page);
1187     }
1188
1189     protected function get_before_button_bits() {
1190         return '<div id="quiznojswarning">' . get_string('navnojswarning', 'quiz') . "</div>\n";
1191     }
1192
1193     protected function get_end_bits() {
1194         global $PAGE;
1195         $output = '';
1196         $output .= '<a href="' . s($this->attemptobj->summary_url()) . '" class="endtestlink">' . get_string('finishattemptdots', 'quiz') . '</a>';
1197         $output .= $this->attemptobj->get_timer_html();
1198         return $output;
1199     }
1200 }
1201
1202 /**
1203  * Specialisation of {@link quiz_nav_panel_base} for the review quiz page.
1204  *
1205  * @copyright 2008 Tim Hunt
1206  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1207  * @since Moodle 2.0
1208  */
1209 class quiz_review_nav_panel extends quiz_nav_panel_base {
1210     protected function get_question_url($question) {
1211         return $this->attemptobj->review_url($question->id, -1, $this->showall, $this->page);
1212     }
1213
1214     protected function get_end_bits() {
1215         $html = '';
1216         if ($this->attemptobj->get_num_pages() > 1) {
1217             if ($this->showall) {
1218                 $html .= '<a href="' . s($this->attemptobj->review_url(0, 0, false)) . '">' . get_string('showeachpage', 'quiz') . '</a>';
1219             } else {
1220                 $html .= '<a href="' . s($this->attemptobj->review_url(0, 0, true)) . '">' . get_string('showall', 'quiz') . '</a>';
1221             }
1222         }
1223         $accessmanager = $this->attemptobj->get_access_manager(time());
1224         $html .= $accessmanager->print_finish_review_link($this->attemptobj->is_preview_user(), true);
1225         return $html;
1226     }
1227 }