MDL-52455 quiz: doesn't include all user fields required by messaging
[moodle.git] / mod / quiz / locallib.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  * Library of functions used by the quiz module.
19  *
20  * This contains functions that are called from within the quiz module only
21  * Functions that are also called by core Moodle are in {@link lib.php}
22  * This script also loads the code in {@link questionlib.php} which holds
23  * the module-indpendent code for handling questions and which in turn
24  * initialises all the questiontype classes.
25  *
26  * @package    mod_quiz
27  * @copyright  1999 onwards Martin Dougiamas and others {@link http://moodle.com}
28  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
29  */
32 defined('MOODLE_INTERNAL') || die();
34 require_once($CFG->dirroot . '/mod/quiz/lib.php');
35 require_once($CFG->dirroot . '/mod/quiz/accessmanager.php');
36 require_once($CFG->dirroot . '/mod/quiz/accessmanager_form.php');
37 require_once($CFG->dirroot . '/mod/quiz/renderer.php');
38 require_once($CFG->dirroot . '/mod/quiz/attemptlib.php');
39 require_once($CFG->libdir  . '/eventslib.php');
40 require_once($CFG->libdir . '/filelib.php');
41 require_once($CFG->libdir . '/questionlib.php');
44 /**
45  * @var int We show the countdown timer if there is less than this amount of time left before the
46  * the quiz close date. (1 hour)
47  */
48 define('QUIZ_SHOW_TIME_BEFORE_DEADLINE', '3600');
50 /**
51  * @var int If there are fewer than this many seconds left when the student submits
52  * a page of the quiz, then do not take them to the next page of the quiz. Instead
53  * close the quiz immediately.
54  */
55 define('QUIZ_MIN_TIME_TO_CONTINUE', '2');
57 /**
58  * @var int We show no image when user selects No image from dropdown menu in quiz settings.
59  */
60 define('QUIZ_SHOWIMAGE_NONE', 0);
62 /**
63  * @var int We show small image when user selects small image from dropdown menu in quiz settings.
64  */
65 define('QUIZ_SHOWIMAGE_SMALL', 1);
67 /**
68  * @var int We show Large image when user selects Large image from dropdown menu in quiz settings.
69  */
70 define('QUIZ_SHOWIMAGE_LARGE', 2);
73 // Functions related to attempts ///////////////////////////////////////////////
75 /**
76  * Creates an object to represent a new attempt at a quiz
77  *
78  * Creates an attempt object to represent an attempt at the quiz by the current
79  * user starting at the current time. The ->id field is not set. The object is
80  * NOT written to the database.
81  *
82  * @param object $quizobj the quiz object to create an attempt for.
83  * @param int $attemptnumber the sequence number for the attempt.
84  * @param object $lastattempt the previous attempt by this user, if any. Only needed
85  *         if $attemptnumber > 1 and $quiz->attemptonlast is true.
86  * @param int $timenow the time the attempt was started at.
87  * @param bool $ispreview whether this new attempt is a preview.
88  * @param int $userid  the id of the user attempting this quiz.
89  *
90  * @return object the newly created attempt object.
91  */
92 function quiz_create_attempt(quiz $quizobj, $attemptnumber, $lastattempt, $timenow, $ispreview = false, $userid = null) {
93     global $USER;
95     if ($userid === null) {
96         $userid = $USER->id;
97     }
99     $quiz = $quizobj->get_quiz();
100     if ($quiz->sumgrades < 0.000005 && $quiz->grade > 0.000005) {
101         throw new moodle_exception('cannotstartgradesmismatch', 'quiz',
102                 new moodle_url('/mod/quiz/view.php', array('q' => $quiz->id)),
103                     array('grade' => quiz_format_grade($quiz, $quiz->grade)));
104     }
106     if ($attemptnumber == 1 || !$quiz->attemptonlast) {
107         // We are not building on last attempt so create a new attempt.
108         $attempt = new stdClass();
109         $attempt->quiz = $quiz->id;
110         $attempt->userid = $userid;
111         $attempt->preview = 0;
112         $attempt->layout = '';
113     } else {
114         // Build on last attempt.
115         if (empty($lastattempt)) {
116             print_error('cannotfindprevattempt', 'quiz');
117         }
118         $attempt = $lastattempt;
119     }
121     $attempt->attempt = $attemptnumber;
122     $attempt->timestart = $timenow;
123     $attempt->timefinish = 0;
124     $attempt->timemodified = $timenow;
125     $attempt->state = quiz_attempt::IN_PROGRESS;
126     $attempt->currentpage = 0;
127     $attempt->sumgrades = null;
129     // If this is a preview, mark it as such.
130     if ($ispreview) {
131         $attempt->preview = 1;
132     }
134     $timeclose = $quizobj->get_access_manager($timenow)->get_end_time($attempt);
135     if ($timeclose === false || $ispreview) {
136         $attempt->timecheckstate = null;
137     } else {
138         $attempt->timecheckstate = $timeclose;
139     }
141     return $attempt;
143 /**
144  * Start a normal, new, quiz attempt.
145  *
146  * @param quiz      $quizobj            the quiz object to start an attempt for.
147  * @param question_usage_by_activity $quba
148  * @param object    $attempt
149  * @param integer   $attemptnumber      starting from 1
150  * @param integer   $timenow            the attempt start time
151  * @param array     $questionids        slot number => question id. Used for random questions, to force the choice
152  *                                        of a particular actual question. Intended for testing purposes only.
153  * @param array     $forcedvariantsbyslot slot number => variant. Used for questions with variants,
154  *                                          to force the choice of a particular variant. Intended for testing
155  *                                          purposes only.
156  * @throws moodle_exception
157  * @return object   modified attempt object
158  */
159 function quiz_start_new_attempt($quizobj, $quba, $attempt, $attemptnumber, $timenow,
160                                 $questionids = array(), $forcedvariantsbyslot = array()) {
162     // Usages for this user's previous quiz attempts.
163     $qubaids = new \mod_quiz\question\qubaids_for_users_attempts(
164             $quizobj->get_quizid(), $attempt->userid);
166     // Fully load all the questions in this quiz.
167     $quizobj->preload_questions();
168     $quizobj->load_questions();
170     // First load all the non-random questions.
171     $randomfound = false;
172     $slot = 0;
173     $questions = array();
174     $maxmark = array();
175     $page = array();
176     foreach ($quizobj->get_questions() as $questiondata) {
177         $slot += 1;
178         $maxmark[$slot] = $questiondata->maxmark;
179         $page[$slot] = $questiondata->page;
180         if ($questiondata->qtype == 'random') {
181             $randomfound = true;
182             continue;
183         }
184         if (!$quizobj->get_quiz()->shuffleanswers) {
185             $questiondata->options->shuffleanswers = false;
186         }
187         $questions[$slot] = question_bank::make_question($questiondata);
188     }
190     // Then find a question to go in place of each random question.
191     if ($randomfound) {
192         $slot = 0;
193         $usedquestionids = array();
194         foreach ($questions as $question) {
195             if (isset($usedquestions[$question->id])) {
196                 $usedquestionids[$question->id] += 1;
197             } else {
198                 $usedquestionids[$question->id] = 1;
199             }
200         }
201         $randomloader = new \core_question\bank\random_question_loader($qubaids, $usedquestionids);
203         foreach ($quizobj->get_questions() as $questiondata) {
204             $slot += 1;
205             if ($questiondata->qtype != 'random') {
206                 continue;
207             }
209             // Deal with fixed random choices for testing.
210             if (isset($questionids[$quba->next_slot_number()])) {
211                 if ($randomloader->is_question_available($questiondata->category,
212                         (bool) $questiondata->questiontext, $questionids[$quba->next_slot_number()])) {
213                     $questions[$slot] = question_bank::load_question(
214                             $questionids[$quba->next_slot_number()], $quizobj->get_quiz()->shuffleanswers);
215                     continue;
216                 } else {
217                     throw new coding_exception('Forced question id not available.');
218                 }
219             }
221             // Normal case, pick one at random.
222             $questionid = $randomloader->get_next_question_id($questiondata->category,
223                         (bool) $questiondata->questiontext);
224             if ($questionid === null) {
225                 throw new moodle_exception('notenoughrandomquestions', 'quiz',
226                                            $quizobj->view_url(), $questiondata);
227             }
229             $questions[$slot] = question_bank::load_question($questionid,
230                     $quizobj->get_quiz()->shuffleanswers);
231         }
232     }
234     // Finally add them all to the usage.
235     ksort($questions);
236     foreach ($questions as $slot => $question) {
237         $newslot = $quba->add_question($question, $maxmark[$slot]);
238         if ($newslot != $slot) {
239             throw new coding_exception('Slot numbers have got confused.');
240         }
241     }
243     // Start all the questions.
244     $variantstrategy = new core_question\engine\variants\least_used_strategy($quba, $qubaids);
246     if (!empty($forcedvariantsbyslot)) {
247         $forcedvariantsbyseed = question_variant_forced_choices_selection_strategy::prepare_forced_choices_array(
248             $forcedvariantsbyslot, $quba);
249         $variantstrategy = new question_variant_forced_choices_selection_strategy(
250             $forcedvariantsbyseed, $variantstrategy);
251     }
253     $quba->start_all_questions($variantstrategy, $timenow);
255     // Work out the attempt layout.
256     $sections = $quizobj->get_sections();
257     foreach ($sections as $i => $section) {
258         if (isset($sections[$i + 1])) {
259             $sections[$i]->lastslot = $sections[$i + 1]->firstslot - 1;
260         } else {
261             $sections[$i]->lastslot = count($questions);
262         }
263     }
265     $layout = array();
266     foreach ($sections as $section) {
267         if ($section->shufflequestions) {
268             $questionsinthissection = array();
269             for ($slot = $section->firstslot; $slot <= $section->lastslot; $slot += 1) {
270                 $questionsinthissection[] = $slot;
271             }
272             shuffle($questionsinthissection);
273             $questionsonthispage = 0;
274             foreach ($questionsinthissection as $slot) {
275                 if ($questionsonthispage && $questionsonthispage == $quizobj->get_quiz()->questionsperpage) {
276                     $layout[] = 0;
277                     $questionsonthispage = 0;
278                 }
279                 $layout[] = $slot;
280                 $questionsonthispage += 1;
281             }
283         } else {
284             $currentpage = $page[$section->firstslot];
285             for ($slot = $section->firstslot; $slot <= $section->lastslot; $slot += 1) {
286                 if ($currentpage !== null && $page[$slot] != $currentpage) {
287                     $layout[] = 0;
288                 }
289                 $layout[] = $slot;
290                 $currentpage = $page[$slot];
291             }
292         }
294         // Each section ends with a page break.
295         $layout[] = 0;
296     }
297     $attempt->layout = implode(',', $layout);
299     return $attempt;
302 /**
303  * Start a subsequent new attempt, in each attempt builds on last mode.
304  *
305  * @param question_usage_by_activity    $quba         this question usage
306  * @param object                        $attempt      this attempt
307  * @param object                        $lastattempt  last attempt
308  * @return object                       modified attempt object
309  *
310  */
311 function quiz_start_attempt_built_on_last($quba, $attempt, $lastattempt) {
312     $oldquba = question_engine::load_questions_usage_by_activity($lastattempt->uniqueid);
314     $oldnumberstonew = array();
315     foreach ($oldquba->get_attempt_iterator() as $oldslot => $oldqa) {
316         $newslot = $quba->add_question($oldqa->get_question(), $oldqa->get_max_mark());
318         $quba->start_question_based_on($newslot, $oldqa);
320         $oldnumberstonew[$oldslot] = $newslot;
321     }
323     // Update attempt layout.
324     $newlayout = array();
325     foreach (explode(',', $lastattempt->layout) as $oldslot) {
326         if ($oldslot != 0) {
327             $newlayout[] = $oldnumberstonew[$oldslot];
328         } else {
329             $newlayout[] = 0;
330         }
331     }
332     $attempt->layout = implode(',', $newlayout);
333     return $attempt;
336 /**
337  * The save started question usage and quiz attempt in db and log the started attempt.
338  *
339  * @param quiz                       $quizobj
340  * @param question_usage_by_activity $quba
341  * @param object                     $attempt
342  * @return object                    attempt object with uniqueid and id set.
343  */
344 function quiz_attempt_save_started($quizobj, $quba, $attempt) {
345     global $DB;
346     // Save the attempt in the database.
347     question_engine::save_questions_usage_by_activity($quba);
348     $attempt->uniqueid = $quba->get_id();
349     $attempt->id = $DB->insert_record('quiz_attempts', $attempt);
351     // Params used by the events below.
352     $params = array(
353         'objectid' => $attempt->id,
354         'relateduserid' => $attempt->userid,
355         'courseid' => $quizobj->get_courseid(),
356         'context' => $quizobj->get_context()
357     );
358     // Decide which event we are using.
359     if ($attempt->preview) {
360         $params['other'] = array(
361             'quizid' => $quizobj->get_quizid()
362         );
363         $event = \mod_quiz\event\attempt_preview_started::create($params);
364     } else {
365         $event = \mod_quiz\event\attempt_started::create($params);
367     }
369     // Trigger the event.
370     $event->add_record_snapshot('quiz', $quizobj->get_quiz());
371     $event->add_record_snapshot('quiz_attempts', $attempt);
372     $event->trigger();
374     return $attempt;
377 /**
378  * Returns an unfinished attempt (if there is one) for the given
379  * user on the given quiz. This function does not return preview attempts.
380  *
381  * @param int $quizid the id of the quiz.
382  * @param int $userid the id of the user.
383  *
384  * @return mixed the unfinished attempt if there is one, false if not.
385  */
386 function quiz_get_user_attempt_unfinished($quizid, $userid) {
387     $attempts = quiz_get_user_attempts($quizid, $userid, 'unfinished', true);
388     if ($attempts) {
389         return array_shift($attempts);
390     } else {
391         return false;
392     }
395 /**
396  * Delete a quiz attempt.
397  * @param mixed $attempt an integer attempt id or an attempt object
398  *      (row of the quiz_attempts table).
399  * @param object $quiz the quiz object.
400  */
401 function quiz_delete_attempt($attempt, $quiz) {
402     global $DB;
403     if (is_numeric($attempt)) {
404         if (!$attempt = $DB->get_record('quiz_attempts', array('id' => $attempt))) {
405             return;
406         }
407     }
409     if ($attempt->quiz != $quiz->id) {
410         debugging("Trying to delete attempt $attempt->id which belongs to quiz $attempt->quiz " .
411                 "but was passed quiz $quiz->id.");
412         return;
413     }
415     if (!isset($quiz->cmid)) {
416         $cm = get_coursemodule_from_instance('quiz', $quiz->id, $quiz->course);
417         $quiz->cmid = $cm->id;
418     }
420     question_engine::delete_questions_usage_by_activity($attempt->uniqueid);
421     $DB->delete_records('quiz_attempts', array('id' => $attempt->id));
423     // Log the deletion of the attempt if not a preview.
424     if (!$attempt->preview) {
425         $params = array(
426             'objectid' => $attempt->id,
427             'relateduserid' => $attempt->userid,
428             'context' => context_module::instance($quiz->cmid),
429             'other' => array(
430                 'quizid' => $quiz->id
431             )
432         );
433         $event = \mod_quiz\event\attempt_deleted::create($params);
434         $event->add_record_snapshot('quiz_attempts', $attempt);
435         $event->trigger();
436     }
438     // Search quiz_attempts for other instances by this user.
439     // If none, then delete record for this quiz, this user from quiz_grades
440     // else recalculate best grade.
441     $userid = $attempt->userid;
442     if (!$DB->record_exists('quiz_attempts', array('userid' => $userid, 'quiz' => $quiz->id))) {
443         $DB->delete_records('quiz_grades', array('userid' => $userid, 'quiz' => $quiz->id));
444     } else {
445         quiz_save_best_grade($quiz, $userid);
446     }
448     quiz_update_grades($quiz, $userid);
451 /**
452  * Delete all the preview attempts at a quiz, or possibly all the attempts belonging
453  * to one user.
454  * @param object $quiz the quiz object.
455  * @param int $userid (optional) if given, only delete the previews belonging to this user.
456  */
457 function quiz_delete_previews($quiz, $userid = null) {
458     global $DB;
459     $conditions = array('quiz' => $quiz->id, 'preview' => 1);
460     if (!empty($userid)) {
461         $conditions['userid'] = $userid;
462     }
463     $previewattempts = $DB->get_records('quiz_attempts', $conditions);
464     foreach ($previewattempts as $attempt) {
465         quiz_delete_attempt($attempt, $quiz);
466     }
469 /**
470  * @param int $quizid The quiz id.
471  * @return bool whether this quiz has any (non-preview) attempts.
472  */
473 function quiz_has_attempts($quizid) {
474     global $DB;
475     return $DB->record_exists('quiz_attempts', array('quiz' => $quizid, 'preview' => 0));
478 // Functions to do with quiz layout and pages //////////////////////////////////
480 /**
481  * Repaginate the questions in a quiz
482  * @param int $quizid the id of the quiz to repaginate.
483  * @param int $slotsperpage number of items to put on each page. 0 means unlimited.
484  */
485 function quiz_repaginate_questions($quizid, $slotsperpage) {
486     global $DB;
487     $trans = $DB->start_delegated_transaction();
489     $sections = $DB->get_records('quiz_sections', array('quizid' => $quizid), 'firstslot ASC');
490     $firstslots = array();
491     foreach ($sections as $section) {
492         if ((int)$section->firstslot === 1) {
493             continue;
494         }
495         $firstslots[] = $section->firstslot;
496     }
498     $slots = $DB->get_records('quiz_slots', array('quizid' => $quizid),
499             'slot');
500     $currentpage = 1;
501     $slotsonthispage = 0;
502     foreach ($slots as $slot) {
503         if (($firstslots && in_array($slot->slot, $firstslots)) ||
504             ($slotsonthispage && $slotsonthispage == $slotsperpage)) {
505             $currentpage += 1;
506             $slotsonthispage = 0;
507         }
508         if ($slot->page != $currentpage) {
509             $DB->set_field('quiz_slots', 'page', $currentpage, array('id' => $slot->id));
510         }
511         $slotsonthispage += 1;
512     }
514     $trans->allow_commit();
517 // Functions to do with quiz grades ////////////////////////////////////////////
519 /**
520  * Convert the raw grade stored in $attempt into a grade out of the maximum
521  * grade for this quiz.
522  *
523  * @param float $rawgrade the unadjusted grade, fof example $attempt->sumgrades
524  * @param object $quiz the quiz object. Only the fields grade, sumgrades and decimalpoints are used.
525  * @param bool|string $format whether to format the results for display
526  *      or 'question' to format a question grade (different number of decimal places.
527  * @return float|string the rescaled grade, or null/the lang string 'notyetgraded'
528  *      if the $grade is null.
529  */
530 function quiz_rescale_grade($rawgrade, $quiz, $format = true) {
531     if (is_null($rawgrade)) {
532         $grade = null;
533     } else if ($quiz->sumgrades >= 0.000005) {
534         $grade = $rawgrade * $quiz->grade / $quiz->sumgrades;
535     } else {
536         $grade = 0;
537     }
538     if ($format === 'question') {
539         $grade = quiz_format_question_grade($quiz, $grade);
540     } else if ($format) {
541         $grade = quiz_format_grade($quiz, $grade);
542     }
543     return $grade;
546 /**
547  * Get the feedback text that should be show to a student who
548  * got this grade on this quiz. The feedback is processed ready for diplay.
549  *
550  * @param float $grade a grade on this quiz.
551  * @param object $quiz the quiz settings.
552  * @param object $context the quiz context.
553  * @return string the comment that corresponds to this grade (empty string if there is not one.
554  */
555 function quiz_feedback_for_grade($grade, $quiz, $context) {
556     global $DB;
558     if (is_null($grade)) {
559         return '';
560     }
562     // With CBM etc, it is possible to get -ve grades, which would then not match
563     // any feedback. Therefore, we replace -ve grades with 0.
564     $grade = max($grade, 0);
566     $feedback = $DB->get_record_select('quiz_feedback',
567             'quizid = ? AND mingrade <= ? AND ? < maxgrade', array($quiz->id, $grade, $grade));
569     if (empty($feedback->feedbacktext)) {
570         return '';
571     }
573     // Clean the text, ready for display.
574     $formatoptions = new stdClass();
575     $formatoptions->noclean = true;
576     $feedbacktext = file_rewrite_pluginfile_urls($feedback->feedbacktext, 'pluginfile.php',
577             $context->id, 'mod_quiz', 'feedback', $feedback->id);
578     $feedbacktext = format_text($feedbacktext, $feedback->feedbacktextformat, $formatoptions);
580     return $feedbacktext;
583 /**
584  * @param object $quiz the quiz database row.
585  * @return bool Whether this quiz has any non-blank feedback text.
586  */
587 function quiz_has_feedback($quiz) {
588     global $DB;
589     static $cache = array();
590     if (!array_key_exists($quiz->id, $cache)) {
591         $cache[$quiz->id] = quiz_has_grades($quiz) &&
592                 $DB->record_exists_select('quiz_feedback', "quizid = ? AND " .
593                     $DB->sql_isnotempty('quiz_feedback', 'feedbacktext', false, true),
594                 array($quiz->id));
595     }
596     return $cache[$quiz->id];
599 /**
600  * Update the sumgrades field of the quiz. This needs to be called whenever
601  * the grading structure of the quiz is changed. For example if a question is
602  * added or removed, or a question weight is changed.
603  *
604  * You should call {@link quiz_delete_previews()} before you call this function.
605  *
606  * @param object $quiz a quiz.
607  */
608 function quiz_update_sumgrades($quiz) {
609     global $DB;
611     $sql = 'UPDATE {quiz}
612             SET sumgrades = COALESCE((
613                 SELECT SUM(maxmark)
614                 FROM {quiz_slots}
615                 WHERE quizid = {quiz}.id
616             ), 0)
617             WHERE id = ?';
618     $DB->execute($sql, array($quiz->id));
619     $quiz->sumgrades = $DB->get_field('quiz', 'sumgrades', array('id' => $quiz->id));
621     if ($quiz->sumgrades < 0.000005 && quiz_has_attempts($quiz->id)) {
622         // If the quiz has been attempted, and the sumgrades has been
623         // set to 0, then we must also set the maximum possible grade to 0, or
624         // we will get a divide by zero error.
625         quiz_set_grade(0, $quiz);
626     }
629 /**
630  * Update the sumgrades field of the attempts at a quiz.
631  *
632  * @param object $quiz a quiz.
633  */
634 function quiz_update_all_attempt_sumgrades($quiz) {
635     global $DB;
636     $dm = new question_engine_data_mapper();
637     $timenow = time();
639     $sql = "UPDATE {quiz_attempts}
640             SET
641                 timemodified = :timenow,
642                 sumgrades = (
643                     {$dm->sum_usage_marks_subquery('uniqueid')}
644                 )
645             WHERE quiz = :quizid AND state = :finishedstate";
646     $DB->execute($sql, array('timenow' => $timenow, 'quizid' => $quiz->id,
647             'finishedstate' => quiz_attempt::FINISHED));
650 /**
651  * The quiz grade is the maximum that student's results are marked out of. When it
652  * changes, the corresponding data in quiz_grades and quiz_feedback needs to be
653  * rescaled. After calling this function, you probably need to call
654  * quiz_update_all_attempt_sumgrades, quiz_update_all_final_grades and
655  * quiz_update_grades.
656  *
657  * @param float $newgrade the new maximum grade for the quiz.
658  * @param object $quiz the quiz we are updating. Passed by reference so its
659  *      grade field can be updated too.
660  * @return bool indicating success or failure.
661  */
662 function quiz_set_grade($newgrade, $quiz) {
663     global $DB;
664     // This is potentially expensive, so only do it if necessary.
665     if (abs($quiz->grade - $newgrade) < 1e-7) {
666         // Nothing to do.
667         return true;
668     }
670     $oldgrade = $quiz->grade;
671     $quiz->grade = $newgrade;
673     // Use a transaction, so that on those databases that support it, this is safer.
674     $transaction = $DB->start_delegated_transaction();
676     // Update the quiz table.
677     $DB->set_field('quiz', 'grade', $newgrade, array('id' => $quiz->instance));
679     if ($oldgrade < 1) {
680         // If the old grade was zero, we cannot rescale, we have to recompute.
681         // We also recompute if the old grade was too small to avoid underflow problems.
682         quiz_update_all_final_grades($quiz);
684     } else {
685         // We can rescale the grades efficiently.
686         $timemodified = time();
687         $DB->execute("
688                 UPDATE {quiz_grades}
689                 SET grade = ? * grade, timemodified = ?
690                 WHERE quiz = ?
691         ", array($newgrade/$oldgrade, $timemodified, $quiz->id));
692     }
694     if ($oldgrade > 1e-7) {
695         // Update the quiz_feedback table.
696         $factor = $newgrade/$oldgrade;
697         $DB->execute("
698                 UPDATE {quiz_feedback}
699                 SET mingrade = ? * mingrade, maxgrade = ? * maxgrade
700                 WHERE quizid = ?
701         ", array($factor, $factor, $quiz->id));
702     }
704     // Update grade item and send all grades to gradebook.
705     quiz_grade_item_update($quiz);
706     quiz_update_grades($quiz);
708     $transaction->allow_commit();
709     return true;
712 /**
713  * Save the overall grade for a user at a quiz in the quiz_grades table
714  *
715  * @param object $quiz The quiz for which the best grade is to be calculated and then saved.
716  * @param int $userid The userid to calculate the grade for. Defaults to the current user.
717  * @param array $attempts The attempts of this user. Useful if you are
718  * looping through many users. Attempts can be fetched in one master query to
719  * avoid repeated querying.
720  * @return bool Indicates success or failure.
721  */
722 function quiz_save_best_grade($quiz, $userid = null, $attempts = array()) {
723     global $DB, $OUTPUT, $USER;
725     if (empty($userid)) {
726         $userid = $USER->id;
727     }
729     if (!$attempts) {
730         // Get all the attempts made by the user.
731         $attempts = quiz_get_user_attempts($quiz->id, $userid);
732     }
734     // Calculate the best grade.
735     $bestgrade = quiz_calculate_best_grade($quiz, $attempts);
736     $bestgrade = quiz_rescale_grade($bestgrade, $quiz, false);
738     // Save the best grade in the database.
739     if (is_null($bestgrade)) {
740         $DB->delete_records('quiz_grades', array('quiz' => $quiz->id, 'userid' => $userid));
742     } else if ($grade = $DB->get_record('quiz_grades',
743             array('quiz' => $quiz->id, 'userid' => $userid))) {
744         $grade->grade = $bestgrade;
745         $grade->timemodified = time();
746         $DB->update_record('quiz_grades', $grade);
748     } else {
749         $grade = new stdClass();
750         $grade->quiz = $quiz->id;
751         $grade->userid = $userid;
752         $grade->grade = $bestgrade;
753         $grade->timemodified = time();
754         $DB->insert_record('quiz_grades', $grade);
755     }
757     quiz_update_grades($quiz, $userid);
760 /**
761  * Calculate the overall grade for a quiz given a number of attempts by a particular user.
762  *
763  * @param object $quiz    the quiz settings object.
764  * @param array $attempts an array of all the user's attempts at this quiz in order.
765  * @return float          the overall grade
766  */
767 function quiz_calculate_best_grade($quiz, $attempts) {
769     switch ($quiz->grademethod) {
771         case QUIZ_ATTEMPTFIRST:
772             $firstattempt = reset($attempts);
773             return $firstattempt->sumgrades;
775         case QUIZ_ATTEMPTLAST:
776             $lastattempt = end($attempts);
777             return $lastattempt->sumgrades;
779         case QUIZ_GRADEAVERAGE:
780             $sum = 0;
781             $count = 0;
782             foreach ($attempts as $attempt) {
783                 if (!is_null($attempt->sumgrades)) {
784                     $sum += $attempt->sumgrades;
785                     $count++;
786                 }
787             }
788             if ($count == 0) {
789                 return null;
790             }
791             return $sum / $count;
793         case QUIZ_GRADEHIGHEST:
794         default:
795             $max = null;
796             foreach ($attempts as $attempt) {
797                 if ($attempt->sumgrades > $max) {
798                     $max = $attempt->sumgrades;
799                 }
800             }
801             return $max;
802     }
805 /**
806  * Update the final grade at this quiz for all students.
807  *
808  * This function is equivalent to calling quiz_save_best_grade for all
809  * users, but much more efficient.
810  *
811  * @param object $quiz the quiz settings.
812  */
813 function quiz_update_all_final_grades($quiz) {
814     global $DB;
816     if (!$quiz->sumgrades) {
817         return;
818     }
820     $param = array('iquizid' => $quiz->id, 'istatefinished' => quiz_attempt::FINISHED);
821     $firstlastattemptjoin = "JOIN (
822             SELECT
823                 iquiza.userid,
824                 MIN(attempt) AS firstattempt,
825                 MAX(attempt) AS lastattempt
827             FROM {quiz_attempts} iquiza
829             WHERE
830                 iquiza.state = :istatefinished AND
831                 iquiza.preview = 0 AND
832                 iquiza.quiz = :iquizid
834             GROUP BY iquiza.userid
835         ) first_last_attempts ON first_last_attempts.userid = quiza.userid";
837     switch ($quiz->grademethod) {
838         case QUIZ_ATTEMPTFIRST:
839             // Because of the where clause, there will only be one row, but we
840             // must still use an aggregate function.
841             $select = 'MAX(quiza.sumgrades)';
842             $join = $firstlastattemptjoin;
843             $where = 'quiza.attempt = first_last_attempts.firstattempt AND';
844             break;
846         case QUIZ_ATTEMPTLAST:
847             // Because of the where clause, there will only be one row, but we
848             // must still use an aggregate function.
849             $select = 'MAX(quiza.sumgrades)';
850             $join = $firstlastattemptjoin;
851             $where = 'quiza.attempt = first_last_attempts.lastattempt AND';
852             break;
854         case QUIZ_GRADEAVERAGE:
855             $select = 'AVG(quiza.sumgrades)';
856             $join = '';
857             $where = '';
858             break;
860         default:
861         case QUIZ_GRADEHIGHEST:
862             $select = 'MAX(quiza.sumgrades)';
863             $join = '';
864             $where = '';
865             break;
866     }
868     if ($quiz->sumgrades >= 0.000005) {
869         $finalgrade = $select . ' * ' . ($quiz->grade / $quiz->sumgrades);
870     } else {
871         $finalgrade = '0';
872     }
873     $param['quizid'] = $quiz->id;
874     $param['quizid2'] = $quiz->id;
875     $param['quizid3'] = $quiz->id;
876     $param['quizid4'] = $quiz->id;
877     $param['statefinished'] = quiz_attempt::FINISHED;
878     $param['statefinished2'] = quiz_attempt::FINISHED;
879     $finalgradesubquery = "
880             SELECT quiza.userid, $finalgrade AS newgrade
881             FROM {quiz_attempts} quiza
882             $join
883             WHERE
884                 $where
885                 quiza.state = :statefinished AND
886                 quiza.preview = 0 AND
887                 quiza.quiz = :quizid3
888             GROUP BY quiza.userid";
890     $changedgrades = $DB->get_records_sql("
891             SELECT users.userid, qg.id, qg.grade, newgrades.newgrade
893             FROM (
894                 SELECT userid
895                 FROM {quiz_grades} qg
896                 WHERE quiz = :quizid
897             UNION
898                 SELECT DISTINCT userid
899                 FROM {quiz_attempts} quiza2
900                 WHERE
901                     quiza2.state = :statefinished2 AND
902                     quiza2.preview = 0 AND
903                     quiza2.quiz = :quizid2
904             ) users
906             LEFT JOIN {quiz_grades} qg ON qg.userid = users.userid AND qg.quiz = :quizid4
908             LEFT JOIN (
909                 $finalgradesubquery
910             ) newgrades ON newgrades.userid = users.userid
912             WHERE
913                 ABS(newgrades.newgrade - qg.grade) > 0.000005 OR
914                 ((newgrades.newgrade IS NULL OR qg.grade IS NULL) AND NOT
915                           (newgrades.newgrade IS NULL AND qg.grade IS NULL))",
916                 // The mess on the previous line is detecting where the value is
917                 // NULL in one column, and NOT NULL in the other, but SQL does
918                 // not have an XOR operator, and MS SQL server can't cope with
919                 // (newgrades.newgrade IS NULL) <> (qg.grade IS NULL).
920             $param);
922     $timenow = time();
923     $todelete = array();
924     foreach ($changedgrades as $changedgrade) {
926         if (is_null($changedgrade->newgrade)) {
927             $todelete[] = $changedgrade->userid;
929         } else if (is_null($changedgrade->grade)) {
930             $toinsert = new stdClass();
931             $toinsert->quiz = $quiz->id;
932             $toinsert->userid = $changedgrade->userid;
933             $toinsert->timemodified = $timenow;
934             $toinsert->grade = $changedgrade->newgrade;
935             $DB->insert_record('quiz_grades', $toinsert);
937         } else {
938             $toupdate = new stdClass();
939             $toupdate->id = $changedgrade->id;
940             $toupdate->grade = $changedgrade->newgrade;
941             $toupdate->timemodified = $timenow;
942             $DB->update_record('quiz_grades', $toupdate);
943         }
944     }
946     if (!empty($todelete)) {
947         list($test, $params) = $DB->get_in_or_equal($todelete);
948         $DB->delete_records_select('quiz_grades', 'quiz = ? AND userid ' . $test,
949                 array_merge(array($quiz->id), $params));
950     }
953 /**
954  * Efficiently update check state time on all open attempts
955  *
956  * @param array $conditions optional restrictions on which attempts to update
957  *                    Allowed conditions:
958  *                      courseid => (array|int) attempts in given course(s)
959  *                      userid   => (array|int) attempts for given user(s)
960  *                      quizid   => (array|int) attempts in given quiz(s)
961  *                      groupid  => (array|int) quizzes with some override for given group(s)
962  *
963  */
964 function quiz_update_open_attempts(array $conditions) {
965     global $DB;
967     foreach ($conditions as &$value) {
968         if (!is_array($value)) {
969             $value = array($value);
970         }
971     }
973     $params = array();
974     $wheres = array("quiza.state IN ('inprogress', 'overdue')");
975     $iwheres = array("iquiza.state IN ('inprogress', 'overdue')");
977     if (isset($conditions['courseid'])) {
978         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['courseid'], SQL_PARAMS_NAMED, 'cid');
979         $params = array_merge($params, $inparams);
980         $wheres[] = "quiza.quiz IN (SELECT q.id FROM {quiz} q WHERE q.course $incond)";
981         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['courseid'], SQL_PARAMS_NAMED, 'icid');
982         $params = array_merge($params, $inparams);
983         $iwheres[] = "iquiza.quiz IN (SELECT q.id FROM {quiz} q WHERE q.course $incond)";
984     }
986     if (isset($conditions['userid'])) {
987         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['userid'], SQL_PARAMS_NAMED, 'uid');
988         $params = array_merge($params, $inparams);
989         $wheres[] = "quiza.userid $incond";
990         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['userid'], SQL_PARAMS_NAMED, 'iuid');
991         $params = array_merge($params, $inparams);
992         $iwheres[] = "iquiza.userid $incond";
993     }
995     if (isset($conditions['quizid'])) {
996         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['quizid'], SQL_PARAMS_NAMED, 'qid');
997         $params = array_merge($params, $inparams);
998         $wheres[] = "quiza.quiz $incond";
999         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['quizid'], SQL_PARAMS_NAMED, 'iqid');
1000         $params = array_merge($params, $inparams);
1001         $iwheres[] = "iquiza.quiz $incond";
1002     }
1004     if (isset($conditions['groupid'])) {
1005         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['groupid'], SQL_PARAMS_NAMED, 'gid');
1006         $params = array_merge($params, $inparams);
1007         $wheres[] = "quiza.quiz IN (SELECT qo.quiz FROM {quiz_overrides} qo WHERE qo.groupid $incond)";
1008         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['groupid'], SQL_PARAMS_NAMED, 'igid');
1009         $params = array_merge($params, $inparams);
1010         $iwheres[] = "iquiza.quiz IN (SELECT qo.quiz FROM {quiz_overrides} qo WHERE qo.groupid $incond)";
1011     }
1013     // SQL to compute timeclose and timelimit for each attempt:
1014     $quizausersql = quiz_get_attempt_usertime_sql(
1015             implode("\n                AND ", $iwheres));
1017     // SQL to compute the new timecheckstate
1018     $timecheckstatesql = "
1019           CASE WHEN quizauser.usertimelimit = 0 AND quizauser.usertimeclose = 0 THEN NULL
1020                WHEN quizauser.usertimelimit = 0 THEN quizauser.usertimeclose
1021                WHEN quizauser.usertimeclose = 0 THEN quiza.timestart + quizauser.usertimelimit
1022                WHEN quiza.timestart + quizauser.usertimelimit < quizauser.usertimeclose THEN quiza.timestart + quizauser.usertimelimit
1023                ELSE quizauser.usertimeclose END +
1024           CASE WHEN quiza.state = 'overdue' THEN quiz.graceperiod ELSE 0 END";
1026     // SQL to select which attempts to process
1027     $attemptselect = implode("\n                         AND ", $wheres);
1029    /*
1030     * Each database handles updates with inner joins differently:
1031     *  - mysql does not allow a FROM clause
1032     *  - postgres and mssql allow FROM but handle table aliases differently
1033     *  - oracle requires a subquery
1034     *
1035     * Different code for each database.
1036     */
1038     $dbfamily = $DB->get_dbfamily();
1039     if ($dbfamily == 'mysql') {
1040         $updatesql = "UPDATE {quiz_attempts} quiza
1041                         JOIN {quiz} quiz ON quiz.id = quiza.quiz
1042                         JOIN ( $quizausersql ) quizauser ON quizauser.id = quiza.id
1043                          SET quiza.timecheckstate = $timecheckstatesql
1044                        WHERE $attemptselect";
1045     } else if ($dbfamily == 'postgres') {
1046         $updatesql = "UPDATE {quiz_attempts} quiza
1047                          SET timecheckstate = $timecheckstatesql
1048                         FROM {quiz} quiz, ( $quizausersql ) quizauser
1049                        WHERE quiz.id = quiza.quiz
1050                          AND quizauser.id = quiza.id
1051                          AND $attemptselect";
1052     } else if ($dbfamily == 'mssql') {
1053         $updatesql = "UPDATE quiza
1054                          SET timecheckstate = $timecheckstatesql
1055                         FROM {quiz_attempts} quiza
1056                         JOIN {quiz} quiz ON quiz.id = quiza.quiz
1057                         JOIN ( $quizausersql ) quizauser ON quizauser.id = quiza.id
1058                        WHERE $attemptselect";
1059     } else {
1060         // oracle, sqlite and others
1061         $updatesql = "UPDATE {quiz_attempts} quiza
1062                          SET timecheckstate = (
1063                            SELECT $timecheckstatesql
1064                              FROM {quiz} quiz, ( $quizausersql ) quizauser
1065                             WHERE quiz.id = quiza.quiz
1066                               AND quizauser.id = quiza.id
1067                          )
1068                          WHERE $attemptselect";
1069     }
1071     $DB->execute($updatesql, $params);
1074 /**
1075  * Returns SQL to compute timeclose and timelimit for every attempt, taking into account user and group overrides.
1076  *
1077  * @param string $redundantwhereclauses extra where clauses to add to the subquery
1078  *      for performance. These can use the table alias iquiza for the quiz attempts table.
1079  * @return string SQL select with columns attempt.id, usertimeclose, usertimelimit.
1080  */
1081 function quiz_get_attempt_usertime_sql($redundantwhereclauses = '') {
1082     if ($redundantwhereclauses) {
1083         $redundantwhereclauses = 'WHERE ' . $redundantwhereclauses;
1084     }
1085     // The multiple qgo JOINS are necessary because we want timeclose/timelimit = 0 (unlimited) to supercede
1086     // any other group override
1087     $quizausersql = "
1088           SELECT iquiza.id,
1089            COALESCE(MAX(quo.timeclose), MAX(qgo1.timeclose), MAX(qgo2.timeclose), iquiz.timeclose) AS usertimeclose,
1090            COALESCE(MAX(quo.timelimit), MAX(qgo3.timelimit), MAX(qgo4.timelimit), iquiz.timelimit) AS usertimelimit
1092            FROM {quiz_attempts} iquiza
1093            JOIN {quiz} iquiz ON iquiz.id = iquiza.quiz
1094       LEFT JOIN {quiz_overrides} quo ON quo.quiz = iquiza.quiz AND quo.userid = iquiza.userid
1095       LEFT JOIN {groups_members} gm ON gm.userid = iquiza.userid
1096       LEFT JOIN {quiz_overrides} qgo1 ON qgo1.quiz = iquiza.quiz AND qgo1.groupid = gm.groupid AND qgo1.timeclose = 0
1097       LEFT JOIN {quiz_overrides} qgo2 ON qgo2.quiz = iquiza.quiz AND qgo2.groupid = gm.groupid AND qgo2.timeclose > 0
1098       LEFT JOIN {quiz_overrides} qgo3 ON qgo3.quiz = iquiza.quiz AND qgo3.groupid = gm.groupid AND qgo3.timelimit = 0
1099       LEFT JOIN {quiz_overrides} qgo4 ON qgo4.quiz = iquiza.quiz AND qgo4.groupid = gm.groupid AND qgo4.timelimit > 0
1100           $redundantwhereclauses
1101        GROUP BY iquiza.id, iquiz.id, iquiz.timeclose, iquiz.timelimit";
1102     return $quizausersql;
1105 /**
1106  * Return the attempt with the best grade for a quiz
1107  *
1108  * Which attempt is the best depends on $quiz->grademethod. If the grade
1109  * method is GRADEAVERAGE then this function simply returns the last attempt.
1110  * @return object         The attempt with the best grade
1111  * @param object $quiz    The quiz for which the best grade is to be calculated
1112  * @param array $attempts An array of all the attempts of the user at the quiz
1113  */
1114 function quiz_calculate_best_attempt($quiz, $attempts) {
1116     switch ($quiz->grademethod) {
1118         case QUIZ_ATTEMPTFIRST:
1119             foreach ($attempts as $attempt) {
1120                 return $attempt;
1121             }
1122             break;
1124         case QUIZ_GRADEAVERAGE: // We need to do something with it.
1125         case QUIZ_ATTEMPTLAST:
1126             foreach ($attempts as $attempt) {
1127                 $final = $attempt;
1128             }
1129             return $final;
1131         default:
1132         case QUIZ_GRADEHIGHEST:
1133             $max = -1;
1134             foreach ($attempts as $attempt) {
1135                 if ($attempt->sumgrades > $max) {
1136                     $max = $attempt->sumgrades;
1137                     $maxattempt = $attempt;
1138                 }
1139             }
1140             return $maxattempt;
1141     }
1144 /**
1145  * @return array int => lang string the options for calculating the quiz grade
1146  *      from the individual attempt grades.
1147  */
1148 function quiz_get_grading_options() {
1149     return array(
1150         QUIZ_GRADEHIGHEST => get_string('gradehighest', 'quiz'),
1151         QUIZ_GRADEAVERAGE => get_string('gradeaverage', 'quiz'),
1152         QUIZ_ATTEMPTFIRST => get_string('attemptfirst', 'quiz'),
1153         QUIZ_ATTEMPTLAST  => get_string('attemptlast', 'quiz')
1154     );
1157 /**
1158  * @param int $option one of the values QUIZ_GRADEHIGHEST, QUIZ_GRADEAVERAGE,
1159  *      QUIZ_ATTEMPTFIRST or QUIZ_ATTEMPTLAST.
1160  * @return the lang string for that option.
1161  */
1162 function quiz_get_grading_option_name($option) {
1163     $strings = quiz_get_grading_options();
1164     return $strings[$option];
1167 /**
1168  * @return array string => lang string the options for handling overdue quiz
1169  *      attempts.
1170  */
1171 function quiz_get_overdue_handling_options() {
1172     return array(
1173         'autosubmit'  => get_string('overduehandlingautosubmit', 'quiz'),
1174         'graceperiod' => get_string('overduehandlinggraceperiod', 'quiz'),
1175         'autoabandon' => get_string('overduehandlingautoabandon', 'quiz'),
1176     );
1179 /**
1180  * Get the choices for what size user picture to show.
1181  * @return array string => lang string the options for whether to display the user's picture.
1182  */
1183 function quiz_get_user_image_options() {
1184     return array(
1185         QUIZ_SHOWIMAGE_NONE  => get_string('shownoimage', 'quiz'),
1186         QUIZ_SHOWIMAGE_SMALL => get_string('showsmallimage', 'quiz'),
1187         QUIZ_SHOWIMAGE_LARGE => get_string('showlargeimage', 'quiz'),
1188     );
1191 /**
1192  * Get the choices to offer for the 'Questions per page' option.
1193  * @return array int => string.
1194  */
1195 function quiz_questions_per_page_options() {
1196     $pageoptions = array();
1197     $pageoptions[0] = get_string('neverallononepage', 'quiz');
1198     $pageoptions[1] = get_string('everyquestion', 'quiz');
1199     for ($i = 2; $i <= QUIZ_MAX_QPP_OPTION; ++$i) {
1200         $pageoptions[$i] = get_string('everynquestions', 'quiz', $i);
1201     }
1202     return $pageoptions;
1205 /**
1206  * Get the human-readable name for a quiz attempt state.
1207  * @param string $state one of the state constants like {@link quiz_attempt::IN_PROGRESS}.
1208  * @return string The lang string to describe that state.
1209  */
1210 function quiz_attempt_state_name($state) {
1211     switch ($state) {
1212         case quiz_attempt::IN_PROGRESS:
1213             return get_string('stateinprogress', 'quiz');
1214         case quiz_attempt::OVERDUE:
1215             return get_string('stateoverdue', 'quiz');
1216         case quiz_attempt::FINISHED:
1217             return get_string('statefinished', 'quiz');
1218         case quiz_attempt::ABANDONED:
1219             return get_string('stateabandoned', 'quiz');
1220         default:
1221             throw new coding_exception('Unknown quiz attempt state.');
1222     }
1225 // Other quiz functions ////////////////////////////////////////////////////////
1227 /**
1228  * @param object $quiz the quiz.
1229  * @param int $cmid the course_module object for this quiz.
1230  * @param object $question the question.
1231  * @param string $returnurl url to return to after action is done.
1232  * @return string html for a number of icons linked to action pages for a
1233  * question - preview and edit / view icons depending on user capabilities.
1234  */
1235 function quiz_question_action_icons($quiz, $cmid, $question, $returnurl) {
1236     $html = quiz_question_preview_button($quiz, $question) . ' ' .
1237             quiz_question_edit_button($cmid, $question, $returnurl);
1238     return $html;
1241 /**
1242  * @param int $cmid the course_module.id for this quiz.
1243  * @param object $question the question.
1244  * @param string $returnurl url to return to after action is done.
1245  * @param string $contentbeforeicon some HTML content to be added inside the link, before the icon.
1246  * @return the HTML for an edit icon, view icon, or nothing for a question
1247  *      (depending on permissions).
1248  */
1249 function quiz_question_edit_button($cmid, $question, $returnurl, $contentaftericon = '') {
1250     global $CFG, $OUTPUT;
1252     // Minor efficiency saving. Only get strings once, even if there are a lot of icons on one page.
1253     static $stredit = null;
1254     static $strview = null;
1255     if ($stredit === null) {
1256         $stredit = get_string('edit');
1257         $strview = get_string('view');
1258     }
1260     // What sort of icon should we show?
1261     $action = '';
1262     if (!empty($question->id) &&
1263             (question_has_capability_on($question, 'edit', $question->category) ||
1264                     question_has_capability_on($question, 'move', $question->category))) {
1265         $action = $stredit;
1266         $icon = '/t/edit';
1267     } else if (!empty($question->id) &&
1268             question_has_capability_on($question, 'view', $question->category)) {
1269         $action = $strview;
1270         $icon = '/i/info';
1271     }
1273     // Build the icon.
1274     if ($action) {
1275         if ($returnurl instanceof moodle_url) {
1276             $returnurl = $returnurl->out_as_local_url(false);
1277         }
1278         $questionparams = array('returnurl' => $returnurl, 'cmid' => $cmid, 'id' => $question->id);
1279         $questionurl = new moodle_url("$CFG->wwwroot/question/question.php", $questionparams);
1280         return '<a title="' . $action . '" href="' . $questionurl->out() . '" class="questioneditbutton"><img src="' .
1281                 $OUTPUT->pix_url($icon) . '" alt="' . $action . '" />' . $contentaftericon .
1282                 '</a>';
1283     } else if ($contentaftericon) {
1284         return '<span class="questioneditbutton">' . $contentaftericon . '</span>';
1285     } else {
1286         return '';
1287     }
1290 /**
1291  * @param object $quiz the quiz settings
1292  * @param object $question the question
1293  * @return moodle_url to preview this question with the options from this quiz.
1294  */
1295 function quiz_question_preview_url($quiz, $question) {
1296     // Get the appropriate display options.
1297     $displayoptions = mod_quiz_display_options::make_from_quiz($quiz,
1298             mod_quiz_display_options::DURING);
1300     $maxmark = null;
1301     if (isset($question->maxmark)) {
1302         $maxmark = $question->maxmark;
1303     }
1305     // Work out the correcte preview URL.
1306     return question_preview_url($question->id, $quiz->preferredbehaviour,
1307             $maxmark, $displayoptions);
1310 /**
1311  * @param object $quiz the quiz settings
1312  * @param object $question the question
1313  * @param bool $label if true, show the preview question label after the icon
1314  * @return the HTML for a preview question icon.
1315  */
1316 function quiz_question_preview_button($quiz, $question, $label = false) {
1317     global $PAGE;
1318     if (!question_has_capability_on($question, 'use', $question->category)) {
1319         return '';
1320     }
1322     return $PAGE->get_renderer('mod_quiz', 'edit')->question_preview_icon($quiz, $question, $label);
1325 /**
1326  * @param object $attempt the attempt.
1327  * @param object $context the quiz context.
1328  * @return int whether flags should be shown/editable to the current user for this attempt.
1329  */
1330 function quiz_get_flag_option($attempt, $context) {
1331     global $USER;
1332     if (!has_capability('moodle/question:flag', $context)) {
1333         return question_display_options::HIDDEN;
1334     } else if ($attempt->userid == $USER->id) {
1335         return question_display_options::EDITABLE;
1336     } else {
1337         return question_display_options::VISIBLE;
1338     }
1341 /**
1342  * Work out what state this quiz attempt is in - in the sense used by
1343  * quiz_get_review_options, not in the sense of $attempt->state.
1344  * @param object $quiz the quiz settings
1345  * @param object $attempt the quiz_attempt database row.
1346  * @return int one of the mod_quiz_display_options::DURING,
1347  *      IMMEDIATELY_AFTER, LATER_WHILE_OPEN or AFTER_CLOSE constants.
1348  */
1349 function quiz_attempt_state($quiz, $attempt) {
1350     if ($attempt->state == quiz_attempt::IN_PROGRESS) {
1351         return mod_quiz_display_options::DURING;
1352     } else if (time() < $attempt->timefinish + 120) {
1353         return mod_quiz_display_options::IMMEDIATELY_AFTER;
1354     } else if (!$quiz->timeclose || time() < $quiz->timeclose) {
1355         return mod_quiz_display_options::LATER_WHILE_OPEN;
1356     } else {
1357         return mod_quiz_display_options::AFTER_CLOSE;
1358     }
1361 /**
1362  * The the appropraite mod_quiz_display_options object for this attempt at this
1363  * quiz right now.
1364  *
1365  * @param object $quiz the quiz instance.
1366  * @param object $attempt the attempt in question.
1367  * @param $context the quiz context.
1368  *
1369  * @return mod_quiz_display_options
1370  */
1371 function quiz_get_review_options($quiz, $attempt, $context) {
1372     $options = mod_quiz_display_options::make_from_quiz($quiz, quiz_attempt_state($quiz, $attempt));
1374     $options->readonly = true;
1375     $options->flags = quiz_get_flag_option($attempt, $context);
1376     if (!empty($attempt->id)) {
1377         $options->questionreviewlink = new moodle_url('/mod/quiz/reviewquestion.php',
1378                 array('attempt' => $attempt->id));
1379     }
1381     // Show a link to the comment box only for closed attempts.
1382     if (!empty($attempt->id) && $attempt->state == quiz_attempt::FINISHED && !$attempt->preview &&
1383             !is_null($context) && has_capability('mod/quiz:grade', $context)) {
1384         $options->manualcomment = question_display_options::VISIBLE;
1385         $options->manualcommentlink = new moodle_url('/mod/quiz/comment.php',
1386                 array('attempt' => $attempt->id));
1387     }
1389     if (!is_null($context) && !$attempt->preview &&
1390             has_capability('mod/quiz:viewreports', $context) &&
1391             has_capability('moodle/grade:viewhidden', $context)) {
1392         // People who can see reports and hidden grades should be shown everything,
1393         // except during preview when teachers want to see what students see.
1394         $options->attempt = question_display_options::VISIBLE;
1395         $options->correctness = question_display_options::VISIBLE;
1396         $options->marks = question_display_options::MARK_AND_MAX;
1397         $options->feedback = question_display_options::VISIBLE;
1398         $options->numpartscorrect = question_display_options::VISIBLE;
1399         $options->manualcomment = question_display_options::VISIBLE;
1400         $options->generalfeedback = question_display_options::VISIBLE;
1401         $options->rightanswer = question_display_options::VISIBLE;
1402         $options->overallfeedback = question_display_options::VISIBLE;
1403         $options->history = question_display_options::VISIBLE;
1405     }
1407     return $options;
1410 /**
1411  * Combines the review options from a number of different quiz attempts.
1412  * Returns an array of two ojects, so the suggested way of calling this
1413  * funciton is:
1414  * list($someoptions, $alloptions) = quiz_get_combined_reviewoptions(...)
1415  *
1416  * @param object $quiz the quiz instance.
1417  * @param array $attempts an array of attempt objects.
1418  * @param $context the roles and permissions context,
1419  *          normally the context for the quiz module instance.
1420  *
1421  * @return array of two options objects, one showing which options are true for
1422  *          at least one of the attempts, the other showing which options are true
1423  *          for all attempts.
1424  */
1425 function quiz_get_combined_reviewoptions($quiz, $attempts) {
1426     $fields = array('feedback', 'generalfeedback', 'rightanswer', 'overallfeedback');
1427     $someoptions = new stdClass();
1428     $alloptions = new stdClass();
1429     foreach ($fields as $field) {
1430         $someoptions->$field = false;
1431         $alloptions->$field = true;
1432     }
1433     $someoptions->marks = question_display_options::HIDDEN;
1434     $alloptions->marks = question_display_options::MARK_AND_MAX;
1436     foreach ($attempts as $attempt) {
1437         $attemptoptions = mod_quiz_display_options::make_from_quiz($quiz,
1438                 quiz_attempt_state($quiz, $attempt));
1439         foreach ($fields as $field) {
1440             $someoptions->$field = $someoptions->$field || $attemptoptions->$field;
1441             $alloptions->$field = $alloptions->$field && $attemptoptions->$field;
1442         }
1443         $someoptions->marks = max($someoptions->marks, $attemptoptions->marks);
1444         $alloptions->marks = min($alloptions->marks, $attemptoptions->marks);
1445     }
1446     return array($someoptions, $alloptions);
1449 // Functions for sending notification messages /////////////////////////////////
1451 /**
1452  * Sends a confirmation message to the student confirming that the attempt was processed.
1453  *
1454  * @param object $a lots of useful information that can be used in the message
1455  *      subject and body.
1456  *
1457  * @return int|false as for {@link message_send()}.
1458  */
1459 function quiz_send_confirmation($recipient, $a) {
1461     // Add information about the recipient to $a.
1462     // Don't do idnumber. we want idnumber to be the submitter's idnumber.
1463     $a->username     = fullname($recipient);
1464     $a->userusername = $recipient->username;
1466     // Prepare the message.
1467     $eventdata = new stdClass();
1468     $eventdata->component         = 'mod_quiz';
1469     $eventdata->name              = 'confirmation';
1470     $eventdata->notification      = 1;
1472     $eventdata->userfrom          = core_user::get_noreply_user();
1473     $eventdata->userto            = $recipient;
1474     $eventdata->subject           = get_string('emailconfirmsubject', 'quiz', $a);
1475     $eventdata->fullmessage       = get_string('emailconfirmbody', 'quiz', $a);
1476     $eventdata->fullmessageformat = FORMAT_PLAIN;
1477     $eventdata->fullmessagehtml   = '';
1479     $eventdata->smallmessage      = get_string('emailconfirmsmall', 'quiz', $a);
1480     $eventdata->contexturl        = $a->quizurl;
1481     $eventdata->contexturlname    = $a->quizname;
1483     // ... and send it.
1484     return message_send($eventdata);
1487 /**
1488  * Sends notification messages to the interested parties that assign the role capability
1489  *
1490  * @param object $recipient user object of the intended recipient
1491  * @param object $a associative array of replaceable fields for the templates
1492  *
1493  * @return int|false as for {@link message_send()}.
1494  */
1495 function quiz_send_notification($recipient, $submitter, $a) {
1497     // Recipient info for template.
1498     $a->useridnumber = $recipient->idnumber;
1499     $a->username     = fullname($recipient);
1500     $a->userusername = $recipient->username;
1502     // Prepare the message.
1503     $eventdata = new stdClass();
1504     $eventdata->component         = 'mod_quiz';
1505     $eventdata->name              = 'submission';
1506     $eventdata->notification      = 1;
1508     $eventdata->userfrom          = $submitter;
1509     $eventdata->userto            = $recipient;
1510     $eventdata->subject           = get_string('emailnotifysubject', 'quiz', $a);
1511     $eventdata->fullmessage       = get_string('emailnotifybody', 'quiz', $a);
1512     $eventdata->fullmessageformat = FORMAT_PLAIN;
1513     $eventdata->fullmessagehtml   = '';
1515     $eventdata->smallmessage      = get_string('emailnotifysmall', 'quiz', $a);
1516     $eventdata->contexturl        = $a->quizreviewurl;
1517     $eventdata->contexturlname    = $a->quizname;
1519     // ... and send it.
1520     return message_send($eventdata);
1523 /**
1524  * Send all the requried messages when a quiz attempt is submitted.
1525  *
1526  * @param object $course the course
1527  * @param object $quiz the quiz
1528  * @param object $attempt this attempt just finished
1529  * @param object $context the quiz context
1530  * @param object $cm the coursemodule for this quiz
1531  *
1532  * @return bool true if all necessary messages were sent successfully, else false.
1533  */
1534 function quiz_send_notification_messages($course, $quiz, $attempt, $context, $cm) {
1535     global $CFG, $DB;
1537     // Do nothing if required objects not present.
1538     if (empty($course) or empty($quiz) or empty($attempt) or empty($context)) {
1539         throw new coding_exception('$course, $quiz, $attempt, $context and $cm must all be set.');
1540     }
1542     $submitter = $DB->get_record('user', array('id' => $attempt->userid), '*', MUST_EXIST);
1544     // Check for confirmation required.
1545     $sendconfirm = false;
1546     $notifyexcludeusers = '';
1547     if (has_capability('mod/quiz:emailconfirmsubmission', $context, $submitter, false)) {
1548         $notifyexcludeusers = $submitter->id;
1549         $sendconfirm = true;
1550     }
1552     // Check for notifications required.
1553     $notifyfields = 'u.id, u.username, u.idnumber, u.email, u.emailstop, u.lang,
1554             u.timezone, u.mailformat, u.maildisplay, u.auth, u.suspended, u.deleted, ';
1555     $notifyfields .= get_all_user_name_fields(true, 'u');
1556     $groups = groups_get_all_groups($course->id, $submitter->id, $cm->groupingid);
1557     if (is_array($groups) && count($groups) > 0) {
1558         $groups = array_keys($groups);
1559     } else if (groups_get_activity_groupmode($cm, $course) != NOGROUPS) {
1560         // If the user is not in a group, and the quiz is set to group mode,
1561         // then set $groups to a non-existant id so that only users with
1562         // 'moodle/site:accessallgroups' get notified.
1563         $groups = -1;
1564     } else {
1565         $groups = '';
1566     }
1567     $userstonotify = get_users_by_capability($context, 'mod/quiz:emailnotifysubmission',
1568             $notifyfields, '', '', '', $groups, $notifyexcludeusers, false, false, true);
1570     if (empty($userstonotify) && !$sendconfirm) {
1571         return true; // Nothing to do.
1572     }
1574     $a = new stdClass();
1575     // Course info.
1576     $a->coursename      = $course->fullname;
1577     $a->courseshortname = $course->shortname;
1578     // Quiz info.
1579     $a->quizname        = $quiz->name;
1580     $a->quizreporturl   = $CFG->wwwroot . '/mod/quiz/report.php?id=' . $cm->id;
1581     $a->quizreportlink  = '<a href="' . $a->quizreporturl . '">' .
1582             format_string($quiz->name) . ' report</a>';
1583     $a->quizurl         = $CFG->wwwroot . '/mod/quiz/view.php?id=' . $cm->id;
1584     $a->quizlink        = '<a href="' . $a->quizurl . '">' . format_string($quiz->name) . '</a>';
1585     // Attempt info.
1586     $a->submissiontime  = userdate($attempt->timefinish);
1587     $a->timetaken       = format_time($attempt->timefinish - $attempt->timestart);
1588     $a->quizreviewurl   = $CFG->wwwroot . '/mod/quiz/review.php?attempt=' . $attempt->id;
1589     $a->quizreviewlink  = '<a href="' . $a->quizreviewurl . '">' .
1590             format_string($quiz->name) . ' review</a>';
1591     // Student who sat the quiz info.
1592     $a->studentidnumber = $submitter->idnumber;
1593     $a->studentname     = fullname($submitter);
1594     $a->studentusername = $submitter->username;
1596     $allok = true;
1598     // Send notifications if required.
1599     if (!empty($userstonotify)) {
1600         foreach ($userstonotify as $recipient) {
1601             $allok = $allok && quiz_send_notification($recipient, $submitter, $a);
1602         }
1603     }
1605     // Send confirmation if required. We send the student confirmation last, so
1606     // that if message sending is being intermittently buggy, which means we send
1607     // some but not all messages, and then try again later, then teachers may get
1608     // duplicate messages, but the student will always get exactly one.
1609     if ($sendconfirm) {
1610         $allok = $allok && quiz_send_confirmation($submitter, $a);
1611     }
1613     return $allok;
1616 /**
1617  * Send the notification message when a quiz attempt becomes overdue.
1618  *
1619  * @param quiz_attempt $attemptobj all the data about the quiz attempt.
1620  */
1621 function quiz_send_overdue_message($attemptobj) {
1622     global $CFG, $DB;
1624     $submitter = $DB->get_record('user', array('id' => $attemptobj->get_userid()), '*', MUST_EXIST);
1626     if (!$attemptobj->has_capability('mod/quiz:emailwarnoverdue', $submitter->id, false)) {
1627         return; // Message not required.
1628     }
1630     if (!$attemptobj->has_response_to_at_least_one_graded_question()) {
1631         return; // Message not required.
1632     }
1634     // Prepare lots of useful information that admins might want to include in
1635     // the email message.
1636     $quizname = format_string($attemptobj->get_quiz_name());
1638     $deadlines = array();
1639     if ($attemptobj->get_quiz()->timelimit) {
1640         $deadlines[] = $attemptobj->get_attempt()->timestart + $attemptobj->get_quiz()->timelimit;
1641     }
1642     if ($attemptobj->get_quiz()->timeclose) {
1643         $deadlines[] = $attemptobj->get_quiz()->timeclose;
1644     }
1645     $duedate = min($deadlines);
1646     $graceend = $duedate + $attemptobj->get_quiz()->graceperiod;
1648     $a = new stdClass();
1649     // Course info.
1650     $a->coursename         = format_string($attemptobj->get_course()->fullname);
1651     $a->courseshortname    = format_string($attemptobj->get_course()->shortname);
1652     // Quiz info.
1653     $a->quizname           = $quizname;
1654     $a->quizurl            = $attemptobj->view_url();
1655     $a->quizlink           = '<a href="' . $a->quizurl . '">' . $quizname . '</a>';
1656     // Attempt info.
1657     $a->attemptduedate     = userdate($duedate);
1658     $a->attemptgraceend    = userdate($graceend);
1659     $a->attemptsummaryurl  = $attemptobj->summary_url()->out(false);
1660     $a->attemptsummarylink = '<a href="' . $a->attemptsummaryurl . '">' . $quizname . ' review</a>';
1661     // Student's info.
1662     $a->studentidnumber    = $submitter->idnumber;
1663     $a->studentname        = fullname($submitter);
1664     $a->studentusername    = $submitter->username;
1666     // Prepare the message.
1667     $eventdata = new stdClass();
1668     $eventdata->component         = 'mod_quiz';
1669     $eventdata->name              = 'attempt_overdue';
1670     $eventdata->notification      = 1;
1672     $eventdata->userfrom          = core_user::get_noreply_user();
1673     $eventdata->userto            = $submitter;
1674     $eventdata->subject           = get_string('emailoverduesubject', 'quiz', $a);
1675     $eventdata->fullmessage       = get_string('emailoverduebody', 'quiz', $a);
1676     $eventdata->fullmessageformat = FORMAT_PLAIN;
1677     $eventdata->fullmessagehtml   = '';
1679     $eventdata->smallmessage      = get_string('emailoverduesmall', 'quiz', $a);
1680     $eventdata->contexturl        = $a->quizurl;
1681     $eventdata->contexturlname    = $a->quizname;
1683     // Send the message.
1684     return message_send($eventdata);
1687 /**
1688  * Handle the quiz_attempt_submitted event.
1689  *
1690  * This sends the confirmation and notification messages, if required.
1691  *
1692  * @param object $event the event object.
1693  */
1694 function quiz_attempt_submitted_handler($event) {
1695     global $DB;
1697     $course  = $DB->get_record('course', array('id' => $event->courseid));
1698     $attempt = $event->get_record_snapshot('quiz_attempts', $event->objectid);
1699     $quiz    = $event->get_record_snapshot('quiz', $attempt->quiz);
1700     $cm      = get_coursemodule_from_id('quiz', $event->get_context()->instanceid, $event->courseid);
1702     if (!($course && $quiz && $cm && $attempt)) {
1703         // Something has been deleted since the event was raised. Therefore, the
1704         // event is no longer relevant.
1705         return true;
1706     }
1708     // Update completion state.
1709     $completion = new completion_info($course);
1710     if ($completion->is_enabled($cm) && ($quiz->completionattemptsexhausted || $quiz->completionpass)) {
1711         $completion->update_state($cm, COMPLETION_COMPLETE, $event->userid);
1712     }
1713     return quiz_send_notification_messages($course, $quiz, $attempt,
1714             context_module::instance($cm->id), $cm);
1717 /**
1718  * Handle groups_member_added event
1719  *
1720  * @param object $event the event object.
1721  * @deprecated since 2.6, see {@link \mod_quiz\group_observers::group_member_added()}.
1722  */
1723 function quiz_groups_member_added_handler($event) {
1724     debugging('quiz_groups_member_added_handler() is deprecated, please use ' .
1725         '\mod_quiz\group_observers::group_member_added() instead.', DEBUG_DEVELOPER);
1726     quiz_update_open_attempts(array('userid'=>$event->userid, 'groupid'=>$event->groupid));
1729 /**
1730  * Handle groups_member_removed event
1731  *
1732  * @param object $event the event object.
1733  * @deprecated since 2.6, see {@link \mod_quiz\group_observers::group_member_removed()}.
1734  */
1735 function quiz_groups_member_removed_handler($event) {
1736     debugging('quiz_groups_member_removed_handler() is deprecated, please use ' .
1737         '\mod_quiz\group_observers::group_member_removed() instead.', DEBUG_DEVELOPER);
1738     quiz_update_open_attempts(array('userid'=>$event->userid, 'groupid'=>$event->groupid));
1741 /**
1742  * Handle groups_group_deleted event
1743  *
1744  * @param object $event the event object.
1745  * @deprecated since 2.6, see {@link \mod_quiz\group_observers::group_deleted()}.
1746  */
1747 function quiz_groups_group_deleted_handler($event) {
1748     global $DB;
1749     debugging('quiz_groups_group_deleted_handler() is deprecated, please use ' .
1750         '\mod_quiz\group_observers::group_deleted() instead.', DEBUG_DEVELOPER);
1751     quiz_process_group_deleted_in_course($event->courseid);
1754 /**
1755  * Logic to happen when a/some group(s) has/have been deleted in a course.
1756  *
1757  * @param int $courseid The course ID.
1758  * @return void
1759  */
1760 function quiz_process_group_deleted_in_course($courseid) {
1761     global $DB;
1763     // It would be nice if we got the groupid that was deleted.
1764     // Instead, we just update all quizzes with orphaned group overrides.
1765     $sql = "SELECT o.id, o.quiz
1766               FROM {quiz_overrides} o
1767               JOIN {quiz} quiz ON quiz.id = o.quiz
1768          LEFT JOIN {groups} grp ON grp.id = o.groupid
1769              WHERE quiz.course = :courseid
1770                AND o.groupid IS NOT NULL
1771                AND grp.id IS NULL";
1772     $params = array('courseid' => $courseid);
1773     $records = $DB->get_records_sql_menu($sql, $params);
1774     if (!$records) {
1775         return; // Nothing to do.
1776     }
1777     $DB->delete_records_list('quiz_overrides', 'id', array_keys($records));
1778     quiz_update_open_attempts(array('quizid' => array_unique(array_values($records))));
1781 /**
1782  * Handle groups_members_removed event
1783  *
1784  * @param object $event the event object.
1785  * @deprecated since 2.6, see {@link \mod_quiz\group_observers::group_member_removed()}.
1786  */
1787 function quiz_groups_members_removed_handler($event) {
1788     debugging('quiz_groups_members_removed_handler() is deprecated, please use ' .
1789         '\mod_quiz\group_observers::group_member_removed() instead.', DEBUG_DEVELOPER);
1790     if ($event->userid == 0) {
1791         quiz_update_open_attempts(array('courseid'=>$event->courseid));
1792     } else {
1793         quiz_update_open_attempts(array('courseid'=>$event->courseid, 'userid'=>$event->userid));
1794     }
1797 /**
1798  * Get the information about the standard quiz JavaScript module.
1799  * @return array a standard jsmodule structure.
1800  */
1801 function quiz_get_js_module() {
1802     global $PAGE;
1804     return array(
1805         'name' => 'mod_quiz',
1806         'fullpath' => '/mod/quiz/module.js',
1807         'requires' => array('base', 'dom', 'event-delegate', 'event-key',
1808                 'core_question_engine', 'moodle-core-formchangechecker'),
1809         'strings' => array(
1810             array('cancel', 'moodle'),
1811             array('flagged', 'question'),
1812             array('functiondisabledbysecuremode', 'quiz'),
1813             array('startattempt', 'quiz'),
1814             array('timesup', 'quiz'),
1815             array('changesmadereallygoaway', 'moodle'),
1816         ),
1817     );
1821 /**
1822  * An extension of question_display_options that includes the extra options used
1823  * by the quiz.
1824  *
1825  * @copyright  2010 The Open University
1826  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1827  */
1828 class mod_quiz_display_options extends question_display_options {
1829     /**#@+
1830      * @var integer bits used to indicate various times in relation to a
1831      * quiz attempt.
1832      */
1833     const DURING =            0x10000;
1834     const IMMEDIATELY_AFTER = 0x01000;
1835     const LATER_WHILE_OPEN =  0x00100;
1836     const AFTER_CLOSE =       0x00010;
1837     /**#@-*/
1839     /**
1840      * @var boolean if this is false, then the student is not allowed to review
1841      * anything about the attempt.
1842      */
1843     public $attempt = true;
1845     /**
1846      * @var boolean if this is false, then the student is not allowed to review
1847      * anything about the attempt.
1848      */
1849     public $overallfeedback = self::VISIBLE;
1851     /**
1852      * Set up the various options from the quiz settings, and a time constant.
1853      * @param object $quiz the quiz settings.
1854      * @param int $one of the {@link DURING}, {@link IMMEDIATELY_AFTER},
1855      * {@link LATER_WHILE_OPEN} or {@link AFTER_CLOSE} constants.
1856      * @return mod_quiz_display_options set up appropriately.
1857      */
1858     public static function make_from_quiz($quiz, $when) {
1859         $options = new self();
1861         $options->attempt = self::extract($quiz->reviewattempt, $when, true, false);
1862         $options->correctness = self::extract($quiz->reviewcorrectness, $when);
1863         $options->marks = self::extract($quiz->reviewmarks, $when,
1864                 self::MARK_AND_MAX, self::MAX_ONLY);
1865         $options->feedback = self::extract($quiz->reviewspecificfeedback, $when);
1866         $options->generalfeedback = self::extract($quiz->reviewgeneralfeedback, $when);
1867         $options->rightanswer = self::extract($quiz->reviewrightanswer, $when);
1868         $options->overallfeedback = self::extract($quiz->reviewoverallfeedback, $when);
1870         $options->numpartscorrect = $options->feedback;
1871         $options->manualcomment = $options->feedback;
1873         if ($quiz->questiondecimalpoints != -1) {
1874             $options->markdp = $quiz->questiondecimalpoints;
1875         } else {
1876             $options->markdp = $quiz->decimalpoints;
1877         }
1879         return $options;
1880     }
1882     protected static function extract($bitmask, $bit,
1883             $whenset = self::VISIBLE, $whennotset = self::HIDDEN) {
1884         if ($bitmask & $bit) {
1885             return $whenset;
1886         } else {
1887             return $whennotset;
1888         }
1889     }
1893 /**
1894  * A {@link qubaid_condition} for finding all the question usages belonging to
1895  * a particular quiz.
1896  *
1897  * @copyright  2010 The Open University
1898  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1899  */
1900 class qubaids_for_quiz extends qubaid_join {
1901     public function __construct($quizid, $includepreviews = true, $onlyfinished = false) {
1902         $where = 'quiza.quiz = :quizaquiz';
1903         $params = array('quizaquiz' => $quizid);
1905         if (!$includepreviews) {
1906             $where .= ' AND preview = 0';
1907         }
1909         if ($onlyfinished) {
1910             $where .= ' AND state == :statefinished';
1911             $params['statefinished'] = quiz_attempt::FINISHED;
1912         }
1914         parent::__construct('{quiz_attempts} quiza', 'quiza.uniqueid', $where, $params);
1915     }
1918 /**
1919  * Creates a textual representation of a question for display.
1920  *
1921  * @param object $question A question object from the database questions table
1922  * @param bool $showicon If true, show the question's icon with the question. False by default.
1923  * @param bool $showquestiontext If true (default), show question text after question name.
1924  *       If false, show only question name.
1925  * @return string
1926  */
1927 function quiz_question_tostring($question, $showicon = false, $showquestiontext = true) {
1928     $result = '';
1930     $name = shorten_text(format_string($question->name), 200);
1931     if ($showicon) {
1932         $name .= print_question_icon($question) . ' ' . $name;
1933     }
1934     $result .= html_writer::span($name, 'questionname');
1936     if ($showquestiontext) {
1937         $questiontext = question_utils::to_plain_text($question->questiontext,
1938                 $question->questiontextformat, array('noclean' => true, 'para' => false));
1939         $questiontext = shorten_text($questiontext, 200);
1940         if ($questiontext) {
1941             $result .= ' ' . html_writer::span(s($questiontext), 'questiontext');
1942         }
1943     }
1945     return $result;
1948 /**
1949  * Verify that the question exists, and the user has permission to use it.
1950  * Does not return. Throws an exception if the question cannot be used.
1951  * @param int $questionid The id of the question.
1952  */
1953 function quiz_require_question_use($questionid) {
1954     global $DB;
1955     $question = $DB->get_record('question', array('id' => $questionid), '*', MUST_EXIST);
1956     question_require_capability_on($question, 'use');
1959 /**
1960  * Verify that the question exists, and the user has permission to use it.
1961  * @param object $quiz the quiz settings.
1962  * @param int $slot which question in the quiz to test.
1963  * @return bool whether the user can use this question.
1964  */
1965 function quiz_has_question_use($quiz, $slot) {
1966     global $DB;
1967     $question = $DB->get_record_sql("
1968             SELECT q.*
1969               FROM {quiz_slots} slot
1970               JOIN {question} q ON q.id = slot.questionid
1971              WHERE slot.quizid = ? AND slot.slot = ?", array($quiz->id, $slot));
1972     if (!$question) {
1973         return false;
1974     }
1975     return question_has_capability_on($question, 'use');
1978 /**
1979  * Add a question to a quiz
1980  *
1981  * Adds a question to a quiz by updating $quiz as well as the
1982  * quiz and quiz_slots tables. It also adds a page break if required.
1983  * @param int $questionid The id of the question to be added
1984  * @param object $quiz The extended quiz object as used by edit.php
1985  *      This is updated by this function
1986  * @param int $page Which page in quiz to add the question on. If 0 (default),
1987  *      add at the end
1988  * @param float $maxmark The maximum mark to set for this question. (Optional,
1989  *      defaults to question.defaultmark.
1990  * @return bool false if the question was already in the quiz
1991  */
1992 function quiz_add_quiz_question($questionid, $quiz, $page = 0, $maxmark = null) {
1993     global $DB;
1994     $slots = $DB->get_records('quiz_slots', array('quizid' => $quiz->id),
1995             'slot', 'questionid, slot, page, id');
1996     if (array_key_exists($questionid, $slots)) {
1997         return false;
1998     }
2000     $trans = $DB->start_delegated_transaction();
2002     $maxpage = 1;
2003     $numonlastpage = 0;
2004     foreach ($slots as $slot) {
2005         if ($slot->page > $maxpage) {
2006             $maxpage = $slot->page;
2007             $numonlastpage = 1;
2008         } else {
2009             $numonlastpage += 1;
2010         }
2011     }
2013     // Add the new question instance.
2014     $slot = new stdClass();
2015     $slot->quizid = $quiz->id;
2016     $slot->questionid = $questionid;
2018     if ($maxmark !== null) {
2019         $slot->maxmark = $maxmark;
2020     } else {
2021         $slot->maxmark = $DB->get_field('question', 'defaultmark', array('id' => $questionid));
2022     }
2024     if (is_int($page) && $page >= 1) {
2025         // Adding on a given page.
2026         $lastslotbefore = 0;
2027         foreach (array_reverse($slots) as $otherslot) {
2028             if ($otherslot->page > $page) {
2029                 $DB->set_field('quiz_slots', 'slot', $otherslot->slot + 1, array('id' => $otherslot->id));
2030             } else {
2031                 $lastslotbefore = $otherslot->slot;
2032                 break;
2033             }
2034         }
2035         $slot->slot = $lastslotbefore + 1;
2036         $slot->page = min($page, $maxpage + 1);
2038         $DB->execute("
2039                 UPDATE {quiz_sections}
2040                    SET firstslot = firstslot + 1
2041                  WHERE quizid = ?
2042                    AND firstslot > ?
2043                 ", array($quiz->id, max($lastslotbefore, 1)));
2045     } else {
2046         $lastslot = end($slots);
2047         if ($lastslot) {
2048             $slot->slot = $lastslot->slot + 1;
2049         } else {
2050             $slot->slot = 1;
2051         }
2052         if ($quiz->questionsperpage && $numonlastpage >= $quiz->questionsperpage) {
2053             $slot->page = $maxpage + 1;
2054         } else {
2055             $slot->page = $maxpage;
2056         }
2057     }
2059     $DB->insert_record('quiz_slots', $slot);
2060     $trans->allow_commit();
2063 /**
2064  * Add a random question to the quiz at a given point.
2065  * @param object $quiz the quiz settings.
2066  * @param int $addonpage the page on which to add the question.
2067  * @param int $categoryid the question category to add the question from.
2068  * @param int $number the number of random questions to add.
2069  * @param bool $includesubcategories whether to include questoins from subcategories.
2070  */
2071 function quiz_add_random_questions($quiz, $addonpage, $categoryid, $number,
2072         $includesubcategories) {
2073     global $DB;
2075     $category = $DB->get_record('question_categories', array('id' => $categoryid));
2076     if (!$category) {
2077         print_error('invalidcategoryid', 'error');
2078     }
2080     $catcontext = context::instance_by_id($category->contextid);
2081     require_capability('moodle/question:useall', $catcontext);
2083     // Find existing random questions in this category that are
2084     // not used by any quiz.
2085     if ($existingquestions = $DB->get_records_sql(
2086             "SELECT q.id, q.qtype FROM {question} q
2087             WHERE qtype = 'random'
2088                 AND category = ?
2089                 AND " . $DB->sql_compare_text('questiontext') . " = ?
2090                 AND NOT EXISTS (
2091                         SELECT *
2092                           FROM {quiz_slots}
2093                          WHERE questionid = q.id)
2094             ORDER BY id", array($category->id, ($includesubcategories ? '1' : '0')))) {
2095             // Take as many of these as needed.
2096         while (($existingquestion = array_shift($existingquestions)) && $number > 0) {
2097             quiz_add_quiz_question($existingquestion->id, $quiz, $addonpage);
2098             $number -= 1;
2099         }
2100     }
2102     if ($number <= 0) {
2103         return;
2104     }
2106     // More random questions are needed, create them.
2107     for ($i = 0; $i < $number; $i += 1) {
2108         $form = new stdClass();
2109         $form->questiontext = array('text' => ($includesubcategories ? '1' : '0'), 'format' => 0);
2110         $form->category = $category->id . ',' . $category->contextid;
2111         $form->defaultmark = 1;
2112         $form->hidden = 1;
2113         $form->stamp = make_unique_id_code(); // Set the unique code (not to be changed).
2114         $question = new stdClass();
2115         $question->qtype = 'random';
2116         $question = question_bank::get_qtype('random')->save_question($question, $form);
2117         if (!isset($question->id)) {
2118             print_error('cannotinsertrandomquestion', 'quiz');
2119         }
2120         quiz_add_quiz_question($question->id, $quiz, $addonpage);
2121     }