[Summary view]

Differences Between: [Versions 310 and 311] [Versions 311 and 400] [Versions 311 and 401] [Versions 311 and 402] [Versions 311 and 403] [Versions 39 and 311]

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