Merge branch 'MDL-57228' of git://github.com/timhunt/moodle
[moodle.git] / mod / quiz / classes / structure.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
17 /**
18  * Defines the \mod_quiz\structure class.
19  *
20  * @package   mod_quiz
21  * @copyright 2013 The Open University
22  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 namespace mod_quiz;
26 defined('MOODLE_INTERNAL') || die();
28 /**
29  * Quiz structure class.
30  *
31  * The structure of the quiz. That is, which questions it is built up
32  * from. This is used on the Edit quiz page (edit.php) and also when
33  * starting an attempt at the quiz (startattempt.php). Once an attempt
34  * has been started, then the attempt holds the specific set of questions
35  * that that student should answer, and we no longer use this class.
36  *
37  * @copyright 2014 The Open University
38  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
39  */
40 class structure {
41     /** @var \quiz the quiz this is the structure of. */
42     protected $quizobj = null;
44     /**
45      * @var \stdClass[] the questions in this quiz. Contains the row from the questions
46      * table, with the data from the quiz_slots table added, and also question_categories.contextid.
47      */
48     protected $questions = array();
50     /** @var \stdClass[] quiz_slots.id => the quiz_slots rows for this quiz, agumented by sectionid. */
51     protected $slots = array();
53     /** @var \stdClass[] quiz_slots.slot => the quiz_slots rows for this quiz, agumented by sectionid. */
54     protected $slotsinorder = array();
56     /**
57      * @var \stdClass[] currently a dummy. Holds data that will match the
58      * quiz_sections, once it exists.
59      */
60     protected $sections = array();
62     /** @var bool caches the results of can_be_edited. */
63     protected $canbeedited = null;
65     /**
66      * Create an instance of this class representing an empty quiz.
67      * @return structure
68      */
69     public static function create() {
70         return new self();
71     }
73     /**
74      * Create an instance of this class representing the structure of a given quiz.
75      * @param \quiz $quizobj the quiz.
76      * @return structure
77      */
78     public static function create_for_quiz($quizobj) {
79         $structure = self::create();
80         $structure->quizobj = $quizobj;
81         $structure->populate_structure($quizobj->get_quiz());
82         return $structure;
83     }
85     /**
86      * Whether there are any questions in the quiz.
87      * @return bool true if there is at least one question in the quiz.
88      */
89     public function has_questions() {
90         return !empty($this->questions);
91     }
93     /**
94      * Get the number of questions in the quiz.
95      * @return int the number of questions in the quiz.
96      */
97     public function get_question_count() {
98         return count($this->questions);
99     }
101     /**
102      * Get the information about the question with this id.
103      * @param int $questionid The question id.
104      * @return \stdClass the data from the questions table, augmented with
105      * question_category.contextid, and the quiz_slots data for the question in this quiz.
106      */
107     public function get_question_by_id($questionid) {
108         return $this->questions[$questionid];
109     }
111     /**
112      * Get the information about the question in a given slot.
113      * @param int $slotnumber the index of the slot in question.
114      * @return \stdClass the data from the questions table, augmented with
115      * question_category.contextid, and the quiz_slots data for the question in this quiz.
116      */
117     public function get_question_in_slot($slotnumber) {
118         return $this->questions[$this->slotsinorder[$slotnumber]->questionid];
119     }
121     /**
122      * Get the displayed question number (or 'i') for a given slot.
123      * @param int $slotnumber the index of the slot in question.
124      * @return string the question number ot display for this slot.
125      */
126     public function get_displayed_number_for_slot($slotnumber) {
127         return $this->slotsinorder[$slotnumber]->displayednumber;
128     }
130     /**
131      * Get the page a given slot is on.
132      * @param int $slotnumber the index of the slot in question.
133      * @return int the page number of the page that slot is on.
134      */
135     public function get_page_number_for_slot($slotnumber) {
136         return $this->slotsinorder[$slotnumber]->page;
137     }
139     /**
140      * Get the slot id of a given slot slot.
141      * @param int $slotnumber the index of the slot in question.
142      * @return int the page number of the page that slot is on.
143      */
144     public function get_slot_id_for_slot($slotnumber) {
145         return $this->slotsinorder[$slotnumber]->id;
146     }
148     /**
149      * Get the question type in a given slot.
150      * @param int $slotnumber the index of the slot in question.
151      * @return string the question type (e.g. multichoice).
152      */
153     public function get_question_type_for_slot($slotnumber) {
154         return $this->questions[$this->slotsinorder[$slotnumber]->questionid]->qtype;
155     }
157     /**
158      * Whether it would be possible, given the question types, etc. for the
159      * question in the given slot to require that the previous question had been
160      * answered before this one is displayed.
161      * @param int $slotnumber the index of the slot in question.
162      * @return bool can this question require the previous one.
163      */
164     public function can_question_depend_on_previous_slot($slotnumber) {
165         return $slotnumber > 1 && $this->can_finish_during_the_attempt($slotnumber - 1);
166     }
168     /**
169      * Whether it is possible for another question to depend on this one finishing.
170      * Note that the answer is not exact, because of random questions, and sometimes
171      * questions cannot be depended upon because of quiz options.
172      * @param int $slotnumber the index of the slot in question.
173      * @return bool can this question finish naturally during the attempt?
174      */
175     public function can_finish_during_the_attempt($slotnumber) {
176         if ($this->quizobj->get_navigation_method() == QUIZ_NAVMETHOD_SEQ) {
177             return false;
178         }
180         if ($this->slotsinorder[$slotnumber]->section->shufflequestions) {
181             return false;
182         }
184         if (in_array($this->get_question_type_for_slot($slotnumber), array('random', 'missingtype'))) {
185             return \question_engine::can_questions_finish_during_the_attempt(
186                     $this->quizobj->get_quiz()->preferredbehaviour);
187         }
189         if (isset($this->slotsinorder[$slotnumber]->canfinish)) {
190             return $this->slotsinorder[$slotnumber]->canfinish;
191         }
193         try {
194             $quba = \question_engine::make_questions_usage_by_activity('mod_quiz', $this->quizobj->get_context());
195             $tempslot = $quba->add_question(\question_bank::load_question(
196                     $this->slotsinorder[$slotnumber]->questionid));
197             $quba->set_preferred_behaviour($this->quizobj->get_quiz()->preferredbehaviour);
198             $quba->start_all_questions();
200             $this->slotsinorder[$slotnumber]->canfinish = $quba->can_question_finish_during_attempt($tempslot);
201             return $this->slotsinorder[$slotnumber]->canfinish;
202         } catch (\Exception $e) {
203             // If the question fails to start, this should not block editing.
204             return false;
205         }
206     }
208     /**
209      * Whether it would be possible, given the question types, etc. for the
210      * question in the given slot to require that the previous question had been
211      * answered before this one is displayed.
212      * @param int $slotnumber the index of the slot in question.
213      * @return bool can this question require the previous one.
214      */
215     public function is_question_dependent_on_previous_slot($slotnumber) {
216         return $this->slotsinorder[$slotnumber]->requireprevious;
217     }
219     /**
220      * Is a particular question in this attempt a real question, or something like a description.
221      * @param int $slotnumber the index of the slot in question.
222      * @return bool whether that question is a real question.
223      */
224     public function is_real_question($slotnumber) {
225         return $this->get_question_in_slot($slotnumber)->length != 0;
226     }
228     /**
229      * Get the course id that the quiz belongs to.
230      * @return int the course.id for the quiz.
231      */
232     public function get_courseid() {
233         return $this->quizobj->get_courseid();
234     }
236     /**
237      * Get the course module id of the quiz.
238      * @return int the course_modules.id for the quiz.
239      */
240     public function get_cmid() {
241         return $this->quizobj->get_cmid();
242     }
244     /**
245      * Get id of the quiz.
246      * @return int the quiz.id for the quiz.
247      */
248     public function get_quizid() {
249         return $this->quizobj->get_quizid();
250     }
252     /**
253      * Get the quiz object.
254      * @return \stdClass the quiz settings row from the database.
255      */
256     public function get_quiz() {
257         return $this->quizobj->get_quiz();
258     }
260     /**
261      * Quizzes can only be repaginated if they have not been attempted, the
262      * questions are not shuffled, and there are two or more questions.
263      * @return bool whether this quiz can be repaginated.
264      */
265     public function can_be_repaginated() {
266         return $this->can_be_edited() && $this->get_question_count() >= 2;
267     }
269     /**
270      * Quizzes can only be edited if they have not been attempted.
271      * @return bool whether the quiz can be edited.
272      */
273     public function can_be_edited() {
274         if ($this->canbeedited === null) {
275             $this->canbeedited = !quiz_has_attempts($this->quizobj->get_quizid());
276         }
277         return $this->canbeedited;
278     }
280     /**
281      * This quiz can only be edited if they have not been attempted.
282      * Throw an exception if this is not the case.
283      */
284     public function check_can_be_edited() {
285         if (!$this->can_be_edited()) {
286             $reportlink = quiz_attempt_summary_link_to_reports($this->get_quiz(),
287                     $this->quizobj->get_cm(), $this->quizobj->get_context());
288             throw new \moodle_exception('cannoteditafterattempts', 'quiz',
289                     new \moodle_url('/mod/quiz/edit.php', array('cmid' => $this->get_cmid())), $reportlink);
290         }
291     }
293     /**
294      * How many questions are allowed per page in the quiz.
295      * This setting controls how frequently extra page-breaks should be inserted
296      * automatically when questions are added to the quiz.
297      * @return int the number of questions that should be on each page of the
298      * quiz by default.
299      */
300     public function get_questions_per_page() {
301         return $this->quizobj->get_quiz()->questionsperpage;
302     }
304     /**
305      * Get quiz slots.
306      * @return \stdClass[] the slots in this quiz.
307      */
308     public function get_slots() {
309         return $this->slots;
310     }
312     /**
313      * Is this slot the first one on its page?
314      * @param int $slotnumber the index of the slot in question.
315      * @return bool whether this slot the first one on its page.
316      */
317     public function is_first_slot_on_page($slotnumber) {
318         if ($slotnumber == 1) {
319             return true;
320         }
321         return $this->slotsinorder[$slotnumber]->page != $this->slotsinorder[$slotnumber - 1]->page;
322     }
324     /**
325      * Is this slot the last one on its page?
326      * @param int $slotnumber the index of the slot in question.
327      * @return bool whether this slot the last one on its page.
328      */
329     public function is_last_slot_on_page($slotnumber) {
330         if (!isset($this->slotsinorder[$slotnumber + 1])) {
331             return true;
332         }
333         return $this->slotsinorder[$slotnumber]->page != $this->slotsinorder[$slotnumber + 1]->page;
334     }
336     /**
337      * Is this slot the last one in its section?
338      * @param int $slotnumber the index of the slot in question.
339      * @return bool whether this slot the last one on its section.
340      */
341     public function is_last_slot_in_section($slotnumber) {
342         return $slotnumber == $this->slotsinorder[$slotnumber]->section->lastslot;
343     }
345     /**
346      * Is this slot the only one in its section?
347      * @param int $slotnumber the index of the slot in question.
348      * @return bool whether this slot the only one on its section.
349      */
350     public function is_only_slot_in_section($slotnumber) {
351         return $this->slotsinorder[$slotnumber]->section->firstslot ==
352                 $this->slotsinorder[$slotnumber]->section->lastslot;
353     }
355     /**
356      * Is this slot the last one in the quiz?
357      * @param int $slotnumber the index of the slot in question.
358      * @return bool whether this slot the last one in the quiz.
359      */
360     public function is_last_slot_in_quiz($slotnumber) {
361         end($this->slotsinorder);
362         return $slotnumber == key($this->slotsinorder);
363     }
365     /**
366      * Is this the first section in the quiz?
367      * @param \stdClass $section the quiz_sections row.
368      * @return bool whether this is first section in the quiz.
369      */
370     public function is_first_section($section) {
371         return $section->firstslot == 1;
372     }
374     /**
375      * Is this the last section in the quiz?
376      * @param \stdClass $section the quiz_sections row.
377      * @return bool whether this is first section in the quiz.
378      */
379     public function is_last_section($section) {
380         return $section->id == end($this->sections)->id;
381     }
383     /**
384      * Does this section only contain one slot?
385      * @param \stdClass $section the quiz_sections row.
386      * @return bool whether this section contains only one slot.
387      */
388     public function is_only_one_slot_in_section($section) {
389         return $section->firstslot == $section->lastslot;
390     }
392     /**
393      * Get the final slot in the quiz.
394      * @return \stdClass the quiz_slots for for the final slot in the quiz.
395      */
396     public function get_last_slot() {
397         return end($this->slotsinorder);
398     }
400     /**
401      * Get a slot by it's id. Throws an exception if it is missing.
402      * @param int $slotid the slot id.
403      * @return \stdClass the requested quiz_slots row.
404      */
405     public function get_slot_by_id($slotid) {
406         if (!array_key_exists($slotid, $this->slots)) {
407             throw new \coding_exception('The \'slotid\' could not be found.');
408         }
409         return $this->slots[$slotid];
410     }
412     /**
413      * Check whether adding a section heading is possible
414      * @param int $pagenumber the number of the page.
415      * @return boolean
416      */
417     public function can_add_section_heading($pagenumber) {
418         // There is a default section heading on this page,
419         // do not show adding new section heading in the Add menu.
420         if ($pagenumber == 1) {
421             return false;
422         }
423         // Get an array of firstslots.
424         $firstslots = array();
425         foreach ($this->sections as $section) {
426             $firstslots[] = $section->firstslot;
427         }
428         foreach ($this->slotsinorder as $slot) {
429             if ($slot->page == $pagenumber) {
430                 if (in_array($slot->slot, $firstslots)) {
431                     return false;
432                 }
433             }
434         }
435         // Do not show the adding section heading on the last add menu.
436         if ($pagenumber == 0) {
437             return false;
438         }
439         return true;
440     }
442     /**
443      * Get all the slots in a section of the quiz.
444      * @param int $sectionid the section id.
445      * @return int[] slot numbers.
446      */
447     public function get_slots_in_section($sectionid) {
448         $slots = array();
449         foreach ($this->slotsinorder as $slot) {
450             if ($slot->section->id == $sectionid) {
451                 $slots[] = $slot->slot;
452             }
453         }
454         return $slots;
455     }
457     /**
458      * Get all the sections of the quiz.
459      * @return \stdClass[] the sections in this quiz.
460      */
461     public function get_sections() {
462         return $this->sections;
463     }
465     /**
466      * Get a particular section by id.
467      * @return \stdClass the section.
468      */
469     public function get_section_by_id($sectionid) {
470         return $this->sections[$sectionid];
471     }
473     /**
474      * Get the number of questions in the quiz.
475      * @return int the number of questions in the quiz.
476      */
477     public function get_section_count() {
478         return count($this->sections);
479     }
481     /**
482      * Get the overall quiz grade formatted for display.
483      * @return string the maximum grade for this quiz.
484      */
485     public function formatted_quiz_grade() {
486         return quiz_format_grade($this->get_quiz(), $this->get_quiz()->grade);
487     }
489     /**
490      * Get the maximum mark for a question, formatted for display.
491      * @param int $slotnumber the index of the slot in question.
492      * @return string the maximum mark for the question in this slot.
493      */
494     public function formatted_question_grade($slotnumber) {
495         return quiz_format_question_grade($this->get_quiz(), $this->slotsinorder[$slotnumber]->maxmark);
496     }
498     /**
499      * Get the number of decimal places for displyaing overall quiz grades or marks.
500      * @return int the number of decimal places.
501      */
502     public function get_decimal_places_for_grades() {
503         return $this->get_quiz()->decimalpoints;
504     }
506     /**
507      * Get the number of decimal places for displyaing question marks.
508      * @return int the number of decimal places.
509      */
510     public function get_decimal_places_for_question_marks() {
511         return quiz_get_grade_format($this->get_quiz());
512     }
514     /**
515      * Get any warnings to show at the top of the edit page.
516      * @return string[] array of strings.
517      */
518     public function get_edit_page_warnings() {
519         $warnings = array();
521         if (quiz_has_attempts($this->quizobj->get_quizid())) {
522             $reviewlink = quiz_attempt_summary_link_to_reports($this->quizobj->get_quiz(),
523                     $this->quizobj->get_cm(), $this->quizobj->get_context());
524             $warnings[] = get_string('cannoteditafterattempts', 'quiz', $reviewlink);
525         }
527         return $warnings;
528     }
530     /**
531      * Get the date information about the current state of the quiz.
532      * @return string[] array of two strings. First a short summary, then a longer
533      * explanation of the current state, e.g. for a tool-tip.
534      */
535     public function get_dates_summary() {
536         $timenow = time();
537         $quiz = $this->quizobj->get_quiz();
539         // Exact open and close dates for the tool-tip.
540         $dates = array();
541         if ($quiz->timeopen > 0) {
542             if ($timenow > $quiz->timeopen) {
543                 $dates[] = get_string('quizopenedon', 'quiz', userdate($quiz->timeopen));
544             } else {
545                 $dates[] = get_string('quizwillopen', 'quiz', userdate($quiz->timeopen));
546             }
547         }
548         if ($quiz->timeclose > 0) {
549             if ($timenow > $quiz->timeclose) {
550                 $dates[] = get_string('quizclosed', 'quiz', userdate($quiz->timeclose));
551             } else {
552                 $dates[] = get_string('quizcloseson', 'quiz', userdate($quiz->timeclose));
553             }
554         }
555         if (empty($dates)) {
556             $dates[] = get_string('alwaysavailable', 'quiz');
557         }
558         $explanation = implode(', ', $dates);
560         // Brief summary on the page.
561         if ($timenow < $quiz->timeopen) {
562             $currentstatus = get_string('quizisclosedwillopen', 'quiz',
563                     userdate($quiz->timeopen, get_string('strftimedatetimeshort', 'langconfig')));
564         } else if ($quiz->timeclose && $timenow <= $quiz->timeclose) {
565             $currentstatus = get_string('quizisopenwillclose', 'quiz',
566                     userdate($quiz->timeclose, get_string('strftimedatetimeshort', 'langconfig')));
567         } else if ($quiz->timeclose && $timenow > $quiz->timeclose) {
568             $currentstatus = get_string('quizisclosed', 'quiz');
569         } else {
570             $currentstatus = get_string('quizisopen', 'quiz');
571         }
573         return array($currentstatus, $explanation);
574     }
576     /**
577      * Set up this class with the structure for a given quiz.
578      * @param \stdClass $quiz the quiz settings.
579      */
580     public function populate_structure($quiz) {
581         global $DB;
583         $slots = $DB->get_records_sql("
584                 SELECT slot.id AS slotid, slot.slot, slot.questionid, slot.page, slot.maxmark,
585                         slot.requireprevious, q.*, qc.contextid
586                   FROM {quiz_slots} slot
587                   LEFT JOIN {question} q ON q.id = slot.questionid
588                   LEFT JOIN {question_categories} qc ON qc.id = q.category
589                  WHERE slot.quizid = ?
590               ORDER BY slot.slot", array($quiz->id));
592         $slots = $this->populate_missing_questions($slots);
594         $this->questions = array();
595         $this->slots = array();
596         $this->slotsinorder = array();
597         foreach ($slots as $slotdata) {
598             $this->questions[$slotdata->questionid] = $slotdata;
600             $slot = new \stdClass();
601             $slot->id = $slotdata->slotid;
602             $slot->slot = $slotdata->slot;
603             $slot->quizid = $quiz->id;
604             $slot->page = $slotdata->page;
605             $slot->questionid = $slotdata->questionid;
606             $slot->maxmark = $slotdata->maxmark;
607             $slot->requireprevious = $slotdata->requireprevious;
609             $this->slots[$slot->id] = $slot;
610             $this->slotsinorder[$slot->slot] = $slot;
611         }
613         // Get quiz sections in ascending order of the firstslot.
614         $this->sections = $DB->get_records('quiz_sections', array('quizid' => $quiz->id), 'firstslot ASC');
615         $this->populate_slots_with_sections();
616         $this->populate_question_numbers();
617     }
619     /**
620      * Used by populate. Make up fake data for any missing questions.
621      * @param \stdClass[] $slots the data about the slots and questions in the quiz.
622      * @return \stdClass[] updated $slots array.
623      */
624     protected function populate_missing_questions($slots) {
625         // Address missing question types.
626         foreach ($slots as $slot) {
627             if ($slot->qtype === null) {
628                 // If the questiontype is missing change the question type.
629                 $slot->id = $slot->questionid;
630                 $slot->category = 0;
631                 $slot->qtype = 'missingtype';
632                 $slot->name = get_string('missingquestion', 'quiz');
633                 $slot->slot = $slot->slot;
634                 $slot->maxmark = 0;
635                 $slot->requireprevious = 0;
636                 $slot->questiontext = ' ';
637                 $slot->questiontextformat = FORMAT_HTML;
638                 $slot->length = 1;
640             } else if (!\question_bank::qtype_exists($slot->qtype)) {
641                 $slot->qtype = 'missingtype';
642             }
643         }
645         return $slots;
646     }
648     /**
649      * Fill in the section ids for each slot.
650      */
651     public function populate_slots_with_sections() {
652         $sections = array_values($this->sections);
653         foreach ($sections as $i => $section) {
654             if (isset($sections[$i + 1])) {
655                 $section->lastslot = $sections[$i + 1]->firstslot - 1;
656             } else {
657                 $section->lastslot = count($this->slotsinorder);
658             }
659             for ($slot = $section->firstslot; $slot <= $section->lastslot; $slot += 1) {
660                 $this->slotsinorder[$slot]->section = $section;
661             }
662         }
663     }
665     /**
666      * Number the questions.
667      */
668     protected function populate_question_numbers() {
669         $number = 1;
670         foreach ($this->slots as $slot) {
671             if ($this->questions[$slot->questionid]->length == 0) {
672                 $slot->displayednumber = get_string('infoshort', 'quiz');
673             } else {
674                 $slot->displayednumber = $number;
675                 $number += 1;
676             }
677         }
678     }
680     /**
681      * Move a slot from its current location to a new location.
682      *
683      * After callig this method, this class will be in an invalid state, and
684      * should be discarded if you want to manipulate the structure further.
685      *
686      * @param int $idmove id of slot to be moved
687      * @param int $idmoveafter id of slot to come before slot being moved
688      * @param int $page new page number of slot being moved
689      * @param bool $insection if the question is moving to a place where a new
690      *      section starts, include it in that section.
691      * @return void
692      */
693     public function move_slot($idmove, $idmoveafter, $page) {
694         global $DB;
696         $this->check_can_be_edited();
698         $movingslot = $this->slots[$idmove];
699         if (empty($movingslot)) {
700             throw new \moodle_exception('Bad slot ID ' . $idmove);
701         }
702         $movingslotnumber = (int) $movingslot->slot;
704         // Empty target slot means move slot to first.
705         if (empty($idmoveafter)) {
706             $moveafterslotnumber = 0;
707         } else {
708             $moveafterslotnumber = (int) $this->slots[$idmoveafter]->slot;
709         }
711         // If the action came in as moving a slot to itself, normalise this to
712         // moving the slot to after the previous slot.
713         if ($moveafterslotnumber == $movingslotnumber) {
714             $moveafterslotnumber = $moveafterslotnumber - 1;
715         }
717         $followingslotnumber = $moveafterslotnumber + 1;
718         // Prevent checking against non-existance slot when already at the last slot.
719         if ($followingslotnumber == $movingslotnumber && !$this->is_last_slot_in_quiz($followingslotnumber)) {
720             $followingslotnumber += 1;
721         }
723         // Check the target page number is OK.
724         if ($page == 0) {
725             $page = 1;
726         }
727         if (($moveafterslotnumber > 0 && $page < $this->get_page_number_for_slot($moveafterslotnumber)) ||
728                 $page < 1) {
729             throw new \coding_exception('The target page number is too small.');
730         } else if (!$this->is_last_slot_in_quiz($moveafterslotnumber) &&
731                 $page > $this->get_page_number_for_slot($followingslotnumber)) {
732             throw new \coding_exception('The target page number is too large.');
733         }
735         // Work out how things are being moved.
736         $slotreorder = array();
737         if ($moveafterslotnumber > $movingslotnumber) {
738             // Moving down.
739             $slotreorder[$movingslotnumber] = $moveafterslotnumber;
740             for ($i = $movingslotnumber; $i < $moveafterslotnumber; $i++) {
741                 $slotreorder[$i + 1] = $i;
742             }
744             $headingmoveafter = $movingslotnumber;
745             if ($this->is_last_slot_in_quiz($moveafterslotnumber) ||
746                     $page == $this->get_page_number_for_slot($moveafterslotnumber + 1)) {
747                 // We are moving to the start of a section, so that heading needs
748                 // to be included in the ones that move up.
749                 $headingmovebefore = $moveafterslotnumber + 1;
750             } else {
751                 $headingmovebefore = $moveafterslotnumber;
752             }
753             $headingmovedirection = -1;
755         } else if ($moveafterslotnumber < $movingslotnumber - 1) {
756             // Moving up.
757             $slotreorder[$movingslotnumber] = $moveafterslotnumber + 1;
758             for ($i = $moveafterslotnumber + 1; $i < $movingslotnumber; $i++) {
759                 $slotreorder[$i] = $i + 1;
760             }
762             if ($page == $this->get_page_number_for_slot($moveafterslotnumber + 1)) {
763                 // Moving to the start of a section, don't move that section.
764                 $headingmoveafter = $moveafterslotnumber + 1;
765             } else {
766                 // Moving tot the end of the previous section, so move the heading down too.
767                 $headingmoveafter = $moveafterslotnumber;
768             }
769             $headingmovebefore = $movingslotnumber + 1;
770             $headingmovedirection = 1;
771         } else {
772             // Staying in the same place, but possibly changing page/section.
773             if ($page > $movingslot->page) {
774                 $headingmoveafter = $movingslotnumber;
775                 $headingmovebefore = $movingslotnumber + 2;
776                 $headingmovedirection = -1;
777             } else if ($page < $movingslot->page) {
778                 $headingmoveafter = $movingslotnumber - 1;
779                 $headingmovebefore = $movingslotnumber + 1;
780                 $headingmovedirection = 1;
781             } else {
782                 return; // Nothing to do.
783             }
784         }
786         if ($this->is_only_slot_in_section($movingslotnumber)) {
787             throw new \coding_exception('You cannot remove the last slot in a section.');
788         }
790         $trans = $DB->start_delegated_transaction();
792         // Slot has moved record new order.
793         if ($slotreorder) {
794             update_field_with_unique_index('quiz_slots', 'slot', $slotreorder,
795                     array('quizid' => $this->get_quizid()));
796         }
798         // Page has changed. Record it.
799         if ($movingslot->page != $page) {
800             $DB->set_field('quiz_slots', 'page', $page,
801                     array('id' => $movingslot->id));
802         }
804         // Update section fist slots.
805         quiz_update_section_firstslots($this->get_quizid(), $headingmovedirection,
806                 $headingmoveafter, $headingmovebefore);
808         // If any pages are now empty, remove them.
809         $emptypages = $DB->get_fieldset_sql("
810                 SELECT DISTINCT page - 1
811                   FROM {quiz_slots} slot
812                  WHERE quizid = ?
813                    AND page > 1
814                    AND NOT EXISTS (SELECT 1 FROM {quiz_slots} WHERE quizid = ? AND page = slot.page - 1)
815               ORDER BY page - 1 DESC
816                 ", array($this->get_quizid(), $this->get_quizid()));
818         foreach ($emptypages as $page) {
819             $DB->execute("
820                     UPDATE {quiz_slots}
821                        SET page = page - 1
822                      WHERE quizid = ?
823                        AND page > ?
824                     ", array($this->get_quizid(), $page));
825         }
827         $trans->allow_commit();
828     }
830     /**
831      * Refresh page numbering of quiz slots.
832      * @param \stdClass[] $slots (optional) array of slot objects.
833      * @return \stdClass[] array of slot objects.
834      */
835     public function refresh_page_numbers($slots = array()) {
836         global $DB;
837         // Get slots ordered by page then slot.
838         if (!count($slots)) {
839             $slots = $DB->get_records('quiz_slots', array('quizid' => $this->get_quizid()), 'slot, page');
840         }
842         // Loop slots. Start Page number at 1 and increment as required.
843         $pagenumbers = array('new' => 0, 'old' => 0);
845         foreach ($slots as $slot) {
846             if ($slot->page !== $pagenumbers['old']) {
847                 $pagenumbers['old'] = $slot->page;
848                 ++$pagenumbers['new'];
849             }
851             if ($pagenumbers['new'] == $slot->page) {
852                 continue;
853             }
854             $slot->page = $pagenumbers['new'];
855         }
857         return $slots;
858     }
860     /**
861      * Refresh page numbering of quiz slots and save to the database.
862      * @param \stdClass $quiz the quiz object.
863      * @return \stdClass[] array of slot objects.
864      */
865     public function refresh_page_numbers_and_update_db() {
866         global $DB;
867         $this->check_can_be_edited();
869         $slots = $this->refresh_page_numbers();
871         // Record new page order.
872         foreach ($slots as $slot) {
873             $DB->set_field('quiz_slots', 'page', $slot->page,
874                     array('id' => $slot->id));
875         }
877         return $slots;
878     }
880     /**
881      * Remove a slot from a quiz
882      * @param int $slotnumber The number of the slot to be deleted.
883      */
884     public function remove_slot($slotnumber) {
885         global $DB;
887         $this->check_can_be_edited();
889         if ($this->is_only_slot_in_section($slotnumber) && $this->get_section_count() > 1) {
890             throw new \coding_exception('You cannot remove the last slot in a section.');
891         }
893         $slot = $DB->get_record('quiz_slots', array('quizid' => $this->get_quizid(), 'slot' => $slotnumber));
894         if (!$slot) {
895             return;
896         }
897         $maxslot = $DB->get_field_sql('SELECT MAX(slot) FROM {quiz_slots} WHERE quizid = ?', array($this->get_quizid()));
899         $trans = $DB->start_delegated_transaction();
900         $DB->delete_records('quiz_slots', array('id' => $slot->id));
901         for ($i = $slot->slot + 1; $i <= $maxslot; $i++) {
902             $DB->set_field('quiz_slots', 'slot', $i - 1,
903                     array('quizid' => $this->get_quizid(), 'slot' => $i));
904         }
906         $qtype = $DB->get_field('question', 'qtype', array('id' => $slot->questionid));
907         if ($qtype === 'random') {
908             // This function automatically checks if the question is in use, and won't delete if it is.
909             question_delete_question($slot->questionid);
910         }
912         quiz_update_section_firstslots($this->get_quizid(), -1, $slotnumber);
913         unset($this->questions[$slot->questionid]);
915         $this->refresh_page_numbers_and_update_db();
917         $trans->allow_commit();
918     }
920     /**
921      * Change the max mark for a slot.
922      *
923      * Saves changes to the question grades in the quiz_slots table and any
924      * corresponding question_attempts.
925      * It does not update 'sumgrades' in the quiz table.
926      *
927      * @param \stdClass $slot row from the quiz_slots table.
928      * @param float $maxmark the new maxmark.
929      * @return bool true if the new grade is different from the old one.
930      */
931     public function update_slot_maxmark($slot, $maxmark) {
932         global $DB;
934         if (abs($maxmark - $slot->maxmark) < 1e-7) {
935             // Grade has not changed. Nothing to do.
936             return false;
937         }
939         $trans = $DB->start_delegated_transaction();
940         $slot->maxmark = $maxmark;
941         $DB->update_record('quiz_slots', $slot);
942         \question_engine::set_max_mark_in_attempts(new \qubaids_for_quiz($slot->quizid),
943                 $slot->slot, $maxmark);
944         $trans->allow_commit();
946         return true;
947     }
949     /**
950      * Set whether the question in a particular slot requires the previous one.
951      * @param int $slotid id of slot.
952      * @param bool $requireprevious if true, set this question to require the previous one.
953      */
954     public function update_question_dependency($slotid, $requireprevious) {
955         global $DB;
956         $DB->set_field('quiz_slots', 'requireprevious', $requireprevious, array('id' => $slotid));
957     }
959     /**
960      * Add/Remove a pagebreak.
961      *
962      * Saves changes to the slot page relationship in the quiz_slots table and reorders the paging
963      * for subsequent slots.
964      *
965      * @param int $slotid id of slot.
966      * @param int $type repaginate::LINK or repaginate::UNLINK.
967      * @return \stdClass[] array of slot objects.
968      */
969     public function update_page_break($slotid, $type) {
970         global $DB;
972         $this->check_can_be_edited();
974         $quizslots = $DB->get_records('quiz_slots', array('quizid' => $this->get_quizid()), 'slot');
975         $repaginate = new \mod_quiz\repaginate($this->get_quizid(), $quizslots);
976         $repaginate->repaginate_slots($quizslots[$slotid]->slot, $type);
977         $slots = $this->refresh_page_numbers_and_update_db();
979         return $slots;
980     }
982     /**
983      * Add a section heading on a given page and return the sectionid
984      * @param int $pagenumber the number of the page where the section heading begins.
985      * @param string|null $heading the heading to add. If not given, a default is used.
986      */
987     public function add_section_heading($pagenumber, $heading = null) {
988         global $DB;
989         $section = new \stdClass();
990         if ($heading !== null) {
991             $section->heading = $heading;
992         } else {
993             $section->heading = get_string('newsectionheading', 'quiz');
994         }
995         $section->quizid = $this->get_quizid();
996         $slotsonpage = $DB->get_records('quiz_slots', array('quizid' => $this->get_quizid(), 'page' => $pagenumber), 'slot DESC');
997         $section->firstslot = end($slotsonpage)->slot;
998         $section->shufflequestions = 0;
999         return $DB->insert_record('quiz_sections', $section);
1000     }
1002     /**
1003      * Change the heading for a section.
1004      * @param int $id the id of the section to change.
1005      * @param string $newheading the new heading for this section.
1006      */
1007     public function set_section_heading($id, $newheading) {
1008         global $DB;
1009         $section = $DB->get_record('quiz_sections', array('id' => $id), '*', MUST_EXIST);
1010         $section->heading = $newheading;
1011         $DB->update_record('quiz_sections', $section);
1012     }
1014     /**
1015      * Change the shuffle setting for a section.
1016      * @param int $id the id of the section to change.
1017      * @param bool $shuffle whether this section should be shuffled.
1018      */
1019     public function set_section_shuffle($id, $shuffle) {
1020         global $DB;
1021         $section = $DB->get_record('quiz_sections', array('id' => $id), '*', MUST_EXIST);
1022         $section->shufflequestions = $shuffle;
1023         $DB->update_record('quiz_sections', $section);
1024     }
1026     /**
1027      * Remove the section heading with the given id
1028      * @param int $sectionid the section to remove.
1029      */
1030     public function remove_section_heading($sectionid) {
1031         global $DB;
1032         $section = $DB->get_record('quiz_sections', array('id' => $sectionid), '*', MUST_EXIST);
1033         if ($section->firstslot == 1) {
1034             throw new \coding_exception('Cannot remove the first section in a quiz.');
1035         }
1036         $DB->delete_records('quiz_sections', array('id' => $sectionid));
1037     }