MDL-40541 need to be able to select random q
[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
27  * @subpackage quiz
28  * @copyright  1999 onwards Martin Dougiamas and others {@link http://moodle.com}
29  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
30  */
33 defined('MOODLE_INTERNAL') || die();
35 require_once($CFG->dirroot . '/mod/quiz/lib.php');
36 require_once($CFG->dirroot . '/mod/quiz/accessmanager.php');
37 require_once($CFG->dirroot . '/mod/quiz/accessmanager_form.php');
38 require_once($CFG->dirroot . '/mod/quiz/renderer.php');
39 require_once($CFG->dirroot . '/mod/quiz/attemptlib.php');
40 require_once($CFG->dirroot . '/question/editlib.php');
41 require_once($CFG->libdir  . '/eventslib.php');
42 require_once($CFG->libdir . '/filelib.php');
45 /**
46  * @var int We show the countdown timer if there is less than this amount of time left before the
47  * the quiz close date. (1 hour)
48  */
49 define('QUIZ_SHOW_TIME_BEFORE_DEADLINE', '3600');
51 /**
52  * @var int If there are fewer than this many seconds left when the student submits
53  * a page of the quiz, then do not take them to the next page of the quiz. Instead
54  * close the quiz immediately.
55  */
56 define('QUIZ_MIN_TIME_TO_CONTINUE', '2');
58 /**
59  * @var int We show no image when user selects No image from dropdown menu in quiz settings.
60  */
61 define('QUIZ_SHOWIMAGE_NONE', 0);
63 /**
64  * @var int We show small image when user selects small image from dropdown menu in quiz settings.
65  */
66 define('QUIZ_SHOWIMAGE_SMALL', 1);
68 /**
69  * @var int We show Large image when user selects Large image from dropdown menu in quiz settings.
70  */
71 define('QUIZ_SHOWIMAGE_LARGE', 2);
74 // Functions related to attempts ///////////////////////////////////////////////
76 /**
77  * Creates an object to represent a new attempt at a quiz
78  *
79  * Creates an attempt object to represent an attempt at the quiz by the current
80  * user starting at the current time. The ->id field is not set. The object is
81  * NOT written to the database.
82  *
83  * @param object $quizobj the quiz object to create an attempt for.
84  * @param int $attemptnumber the sequence number for the attempt.
85  * @param object $lastattempt the previous attempt by this user, if any. Only needed
86  *         if $attemptnumber > 1 and $quiz->attemptonlast is true.
87  * @param int $timenow the time the attempt was started at.
88  * @param bool $ispreview whether this new attempt is a preview.
89  *
90  * @return object the newly created attempt object.
91  */
92 function quiz_create_attempt(quiz $quizobj, $attemptnumber, $lastattempt, $timenow, $ispreview = false) {
93     global $USER;
95     $quiz = $quizobj->get_quiz();
96     if ($quiz->sumgrades < 0.000005 && $quiz->grade > 0.000005) {
97         throw new moodle_exception('cannotstartgradesmismatch', 'quiz',
98                 new moodle_url('/mod/quiz/view.php', array('q' => $quiz->id)),
99                     array('grade' => quiz_format_grade($quiz, $quiz->grade)));
100     }
102     if ($attemptnumber == 1 || !$quiz->attemptonlast) {
103         // We are not building on last attempt so create a new attempt.
104         $attempt = new stdClass();
105         $attempt->quiz = $quiz->id;
106         $attempt->userid = $USER->id;
107         $attempt->preview = 0;
108         $attempt->layout = quiz_clean_layout($quiz->questions, true);
109         if ($quiz->shufflequestions) {
110             $attempt->layout = quiz_repaginate($attempt->layout, $quiz->questionsperpage, true);
111         }
112     } else {
113         // Build on last attempt.
114         if (empty($lastattempt)) {
115             print_error('cannotfindprevattempt', 'quiz');
116         }
117         $attempt = $lastattempt;
118     }
120     $attempt->attempt = $attemptnumber;
121     $attempt->timestart = $timenow;
122     $attempt->timefinish = 0;
123     $attempt->timemodified = $timenow;
124     $attempt->state = quiz_attempt::IN_PROGRESS;
126     // If this is a preview, mark it as such.
127     if ($ispreview) {
128         $attempt->preview = 1;
129     }
131     $timeclose = $quizobj->get_access_manager($timenow)->get_end_time($attempt);
132     if ($timeclose === false || $ispreview) {
133         $attempt->timecheckstate = null;
134     } else {
135         $attempt->timecheckstate = $timeclose;
136     }
138     return $attempt;
140 /**
141  * Start a normal, new, quiz attempt.
142  *
143  * @param quiz                          $quizobj            the quiz object to start an attempt for.
144  * @param question_usage_by_activity    $quba
145  * @param object                        $attempt
146  * @param integer                       $attemptnumber      starting from 1
147  * @param integer                       $timenow            the attempt start time
148  * @param array   $questionids slot number => question id. Used for random questions, to force the choice of a particular actual
149  *                              question. Intended for testing purposes only.
150  * @throws moodle_exception
151  * @return object                       modified attempt object
152  */
153 function quiz_start_new_attempt($quizobj, $quba, $attempt, $attemptnumber, $timenow, $questionids = array()) {
154     // Fully load all the questions in this quiz.
155     $quizobj->preload_questions();
156     $quizobj->load_questions();
158     // Add them all to the $quba.
159     $idstoslots = array();
160     $questionsinuse = array_keys($quizobj->get_questions());
161     foreach ($quizobj->get_questions() as $i => $questiondata) {
162         if ($questiondata->qtype != 'random') {
163             if (!$quizobj->get_quiz()->shuffleanswers) {
164                 $questiondata->options->shuffleanswers = false;
165             }
166             $question = question_bank::make_question($questiondata);
168         } else {
169             if (!isset($questionids[$quba->next_slot_number()])) {
170                 $forcequestionid = null;
171             } else {
172                 $forcequestionid = $questionids[$quba->next_slot_number()];
173             }
175             $question = question_bank::get_qtype('random')->choose_other_question(
176                 $questiondata, $questionsinuse, $quizobj->get_quiz()->shuffleanswers, $forcequestionid);
177             if (is_null($question)) {
178                 throw new moodle_exception('notenoughrandomquestions', 'quiz',
179                                            $quizobj->view_url(), $questiondata);
180             }
181         }
183         $idstoslots[$i] = $quba->add_question($question, $questiondata->maxmark);
184         $questionsinuse[] = $question->id;
185     }
187     // Start all the questions.
188     if ($attempt->preview) {
189         $variantoffset = rand(1, 100);
190     } else {
191         $variantoffset = $attemptnumber;
192     }
193     $quba->start_all_questions(
194         new question_variant_pseudorandom_no_repeats_strategy($variantoffset), $timenow);
196     // Update attempt layout.
197     $newlayout = array();
198     foreach (explode(',', $attempt->layout) as $qid) {
199         if ($qid != 0) {
200             $newlayout[] = $idstoslots[$qid];
201         } else {
202             $newlayout[] = 0;
203         }
204     }
205     $attempt->layout = implode(',', $newlayout);
206     return $attempt;
209 /**
210  * Start a subsequent new attempt, in each attempt builds on last mode.
211  *
212  * @param question_usage_by_activity    $quba         this question usage
213  * @param object                        $attempt      this attempt
214  * @param object                        $lastattempt  last attempt
215  * @return object                       modified attempt object
216  *
217  */
218 function quiz_start_attempt_built_on_last($quba, $attempt, $lastattempt) {
219     $oldquba = question_engine::load_questions_usage_by_activity($lastattempt->uniqueid);
221     $oldnumberstonew = array();
222     foreach ($oldquba->get_attempt_iterator() as $oldslot => $oldqa) {
223         $newslot = $quba->add_question($oldqa->get_question(), $oldqa->get_max_mark());
225         $quba->start_question_based_on($newslot, $oldqa);
227         $oldnumberstonew[$oldslot] = $newslot;
228     }
230     // Update attempt layout.
231     $newlayout = array();
232     foreach (explode(',', $lastattempt->layout) as $oldslot) {
233         if ($oldslot != 0) {
234             $newlayout[] = $oldnumberstonew[$oldslot];
235         } else {
236             $newlayout[] = 0;
237         }
238     }
239     $attempt->layout = implode(',', $newlayout);
240     return $attempt;
243 /**
244  * The save started question usage and quiz attempt in db and log the started attempt.
245  *
246  * @param quiz                       $quizobj
247  * @param question_usage_by_activity $quba
248  * @param object                     $attempt
249  * @return object                    attempt object with uniqueid and id set.
250  */
251 function quiz_attempt_save_started($quizobj, $quba, $attempt) {
252     global $DB;
253     // Save the attempt in the database.
254     question_engine::save_questions_usage_by_activity($quba);
255     $attempt->uniqueid = $quba->get_id();
256     $attempt->id = $DB->insert_record('quiz_attempts', $attempt);
257     // Log the new attempt.
258     if ($attempt->preview) {
259         add_to_log($quizobj->get_courseid(), 'quiz', 'preview', 'view.php?id='.$quizobj->get_cmid(),
260                    $quizobj->get_quizid(), $quizobj->get_cmid());
261     } else {
262         add_to_log($quizobj->get_courseid(), 'quiz', 'attempt', 'review.php?attempt='.$attempt->id,
263                    $quizobj->get_quizid(), $quizobj->get_cmid());
264     }
265     return $attempt;
268 /**
269  * Fire an event to tell the rest of Moodle a quiz attempt has started.
270  *
271  * @param object $attempt
272  * @param quiz   $quizobj
273  */
274 function quiz_fire_attempt_started_event($attempt, $quizobj) {
275     // Trigger event.
276     $eventdata = new stdClass();
277     $eventdata->component = 'mod_quiz';
278     $eventdata->attemptid = $attempt->id;
279     $eventdata->timestart = $attempt->timestart;
280     $eventdata->timestamp = $attempt->timestart;
281     $eventdata->userid = $attempt->userid;
282     $eventdata->quizid = $quizobj->get_quizid();
283     $eventdata->cmid = $quizobj->get_cmid();
284     $eventdata->courseid = $quizobj->get_courseid();
285     events_trigger('quiz_attempt_started', $eventdata);
288 /**
289  * Returns an unfinished attempt (if there is one) for the given
290  * user on the given quiz. This function does not return preview attempts.
291  *
292  * @param int $quizid the id of the quiz.
293  * @param int $userid the id of the user.
294  *
295  * @return mixed the unfinished attempt if there is one, false if not.
296  */
297 function quiz_get_user_attempt_unfinished($quizid, $userid) {
298     $attempts = quiz_get_user_attempts($quizid, $userid, 'unfinished', true);
299     if ($attempts) {
300         return array_shift($attempts);
301     } else {
302         return false;
303     }
306 /**
307  * Delete a quiz attempt.
308  * @param mixed $attempt an integer attempt id or an attempt object
309  *      (row of the quiz_attempts table).
310  * @param object $quiz the quiz object.
311  */
312 function quiz_delete_attempt($attempt, $quiz) {
313     global $DB;
314     if (is_numeric($attempt)) {
315         if (!$attempt = $DB->get_record('quiz_attempts', array('id' => $attempt))) {
316             return;
317         }
318     }
320     if ($attempt->quiz != $quiz->id) {
321         debugging("Trying to delete attempt $attempt->id which belongs to quiz $attempt->quiz " .
322                 "but was passed quiz $quiz->id.");
323         return;
324     }
326     question_engine::delete_questions_usage_by_activity($attempt->uniqueid);
327     $DB->delete_records('quiz_attempts', array('id' => $attempt->id));
329     // Search quiz_attempts for other instances by this user.
330     // If none, then delete record for this quiz, this user from quiz_grades
331     // else recalculate best grade.
332     $userid = $attempt->userid;
333     if (!$DB->record_exists('quiz_attempts', array('userid' => $userid, 'quiz' => $quiz->id))) {
334         $DB->delete_records('quiz_grades', array('userid' => $userid, 'quiz' => $quiz->id));
335     } else {
336         quiz_save_best_grade($quiz, $userid);
337     }
339     quiz_update_grades($quiz, $userid);
342 /**
343  * Delete all the preview attempts at a quiz, or possibly all the attempts belonging
344  * to one user.
345  * @param object $quiz the quiz object.
346  * @param int $userid (optional) if given, only delete the previews belonging to this user.
347  */
348 function quiz_delete_previews($quiz, $userid = null) {
349     global $DB;
350     $conditions = array('quiz' => $quiz->id, 'preview' => 1);
351     if (!empty($userid)) {
352         $conditions['userid'] = $userid;
353     }
354     $previewattempts = $DB->get_records('quiz_attempts', $conditions);
355     foreach ($previewattempts as $attempt) {
356         quiz_delete_attempt($attempt, $quiz);
357     }
360 /**
361  * @param int $quizid The quiz id.
362  * @return bool whether this quiz has any (non-preview) attempts.
363  */
364 function quiz_has_attempts($quizid) {
365     global $DB;
366     return $DB->record_exists('quiz_attempts', array('quiz' => $quizid, 'preview' => 0));
369 // Functions to do with quiz layout and pages //////////////////////////////////
371 /**
372  * Returns a comma separated list of question ids for the quiz
373  *
374  * @param string $layout The string representing the quiz layout. Each page is
375  *      represented as a comma separated list of question ids and 0 indicating
376  *      page breaks. So 5,2,0,3,0 means questions 5 and 2 on page 1 and question
377  *      3 on page 2
378  * @return string comma separated list of question ids, without page breaks.
379  */
380 function quiz_questions_in_quiz($layout) {
381     $questions = str_replace(',0', '', quiz_clean_layout($layout, true));
382     if ($questions === '0') {
383         return '';
384     } else {
385         return $questions;
386     }
389 /**
390  * Returns the number of pages in a quiz layout
391  *
392  * @param string $layout The string representing the quiz layout. Always ends in ,0
393  * @return int The number of pages in the quiz.
394  */
395 function quiz_number_of_pages($layout) {
396     return substr_count(',' . $layout, ',0');
399 /**
400  * Returns the number of questions in the quiz layout
401  *
402  * @param string $layout the string representing the quiz layout.
403  * @return int The number of questions in the quiz.
404  */
405 function quiz_number_of_questions_in_quiz($layout) {
406     $layout = quiz_questions_in_quiz(quiz_clean_layout($layout));
407     $count = substr_count($layout, ',');
408     if ($layout !== '') {
409         $count++;
410     }
411     return $count;
414 /**
415  * Re-paginates the quiz layout
416  *
417  * @param string $layout  The string representing the quiz layout. If there is
418  *      if there is any doubt about the quality of the input data, call
419  *      quiz_clean_layout before you call this function.
420  * @param int $perpage The number of questions per page
421  * @param bool $shuffle Should the questions be reordered randomly?
422  * @return string the new layout string
423  */
424 function quiz_repaginate($layout, $perpage, $shuffle = false) {
425     $questions = quiz_questions_in_quiz($layout);
426     if (!$questions) {
427         return '0';
428     }
430     $questions = explode(',', quiz_questions_in_quiz($layout));
431     if ($shuffle) {
432         shuffle($questions);
433     }
435     $onthispage = 0;
436     $layout = array();
437     foreach ($questions as $question) {
438         if ($perpage and $onthispage >= $perpage) {
439             $layout[] = 0;
440             $onthispage = 0;
441         }
442         $layout[] = $question;
443         $onthispage += 1;
444     }
446     $layout[] = 0;
447     return implode(',', $layout);
450 // Functions to do with quiz grades ////////////////////////////////////////////
452 /**
453  * Creates an array of maximum grades for a quiz
454  *
455  * The grades are extracted from the quiz_question_instances table.
456  * @param object $quiz The quiz settings.
457  * @return array of grades indexed by question id. These are the maximum
458  *      possible grades that students can achieve for each of the questions.
459  */
460 function quiz_get_all_question_grades($quiz) {
461     global $CFG, $DB;
463     $questionlist = quiz_questions_in_quiz($quiz->questions);
464     if (empty($questionlist)) {
465         return array();
466     }
468     $params = array($quiz->id);
469     $wheresql = '';
470     if (!is_null($questionlist)) {
471         list($usql, $question_params) = $DB->get_in_or_equal(explode(',', $questionlist));
472         $wheresql = " AND question $usql ";
473         $params = array_merge($params, $question_params);
474     }
476     $instances = $DB->get_records_sql("SELECT question, grade, id
477                                     FROM {quiz_question_instances}
478                                     WHERE quiz = ? $wheresql", $params);
480     $list = explode(",", $questionlist);
481     $grades = array();
483     foreach ($list as $qid) {
484         if (isset($instances[$qid])) {
485             $grades[$qid] = $instances[$qid]->grade;
486         } else {
487             $grades[$qid] = 1;
488         }
489     }
490     return $grades;
493 /**
494  * Convert the raw grade stored in $attempt into a grade out of the maximum
495  * grade for this quiz.
496  *
497  * @param float $rawgrade the unadjusted grade, fof example $attempt->sumgrades
498  * @param object $quiz the quiz object. Only the fields grade, sumgrades and decimalpoints are used.
499  * @param bool|string $format whether to format the results for display
500  *      or 'question' to format a question grade (different number of decimal places.
501  * @return float|string the rescaled grade, or null/the lang string 'notyetgraded'
502  *      if the $grade is null.
503  */
504 function quiz_rescale_grade($rawgrade, $quiz, $format = true) {
505     if (is_null($rawgrade)) {
506         $grade = null;
507     } else if ($quiz->sumgrades >= 0.000005) {
508         $grade = $rawgrade * $quiz->grade / $quiz->sumgrades;
509     } else {
510         $grade = 0;
511     }
512     if ($format === 'question') {
513         $grade = quiz_format_question_grade($quiz, $grade);
514     } else if ($format) {
515         $grade = quiz_format_grade($quiz, $grade);
516     }
517     return $grade;
520 /**
521  * Get the feedback text that should be show to a student who
522  * got this grade on this quiz. The feedback is processed ready for diplay.
523  *
524  * @param float $grade a grade on this quiz.
525  * @param object $quiz the quiz settings.
526  * @param object $context the quiz context.
527  * @return string the comment that corresponds to this grade (empty string if there is not one.
528  */
529 function quiz_feedback_for_grade($grade, $quiz, $context) {
530     global $DB;
532     if (is_null($grade)) {
533         return '';
534     }
536     // With CBM etc, it is possible to get -ve grades, which would then not match
537     // any feedback. Therefore, we replace -ve grades with 0.
538     $grade = max($grade, 0);
540     $feedback = $DB->get_record_select('quiz_feedback',
541             'quizid = ? AND mingrade <= ? AND ? < maxgrade', array($quiz->id, $grade, $grade));
543     if (empty($feedback->feedbacktext)) {
544         return '';
545     }
547     // Clean the text, ready for display.
548     $formatoptions = new stdClass();
549     $formatoptions->noclean = true;
550     $feedbacktext = file_rewrite_pluginfile_urls($feedback->feedbacktext, 'pluginfile.php',
551             $context->id, 'mod_quiz', 'feedback', $feedback->id);
552     $feedbacktext = format_text($feedbacktext, $feedback->feedbacktextformat, $formatoptions);
554     return $feedbacktext;
557 /**
558  * @param object $quiz the quiz database row.
559  * @return bool Whether this quiz has any non-blank feedback text.
560  */
561 function quiz_has_feedback($quiz) {
562     global $DB;
563     static $cache = array();
564     if (!array_key_exists($quiz->id, $cache)) {
565         $cache[$quiz->id] = quiz_has_grades($quiz) &&
566                 $DB->record_exists_select('quiz_feedback', "quizid = ? AND " .
567                     $DB->sql_isnotempty('quiz_feedback', 'feedbacktext', false, true),
568                 array($quiz->id));
569     }
570     return $cache[$quiz->id];
573 /**
574  * Update the sumgrades field of the quiz. This needs to be called whenever
575  * the grading structure of the quiz is changed. For example if a question is
576  * added or removed, or a question weight is changed.
577  *
578  * You should call {@link quiz_delete_previews()} before you call this function.
579  *
580  * @param object $quiz a quiz.
581  */
582 function quiz_update_sumgrades($quiz) {
583     global $DB;
585     $sql = 'UPDATE {quiz}
586             SET sumgrades = COALESCE((
587                 SELECT SUM(grade)
588                 FROM {quiz_question_instances}
589                 WHERE quiz = {quiz}.id
590             ), 0)
591             WHERE id = ?';
592     $DB->execute($sql, array($quiz->id));
593     $quiz->sumgrades = $DB->get_field('quiz', 'sumgrades', array('id' => $quiz->id));
595     if ($quiz->sumgrades < 0.000005 && quiz_has_attempts($quiz->id)) {
596         // If the quiz has been attempted, and the sumgrades has been
597         // set to 0, then we must also set the maximum possible grade to 0, or
598         // we will get a divide by zero error.
599         quiz_set_grade(0, $quiz);
600     }
603 /**
604  * Update the sumgrades field of the attempts at a quiz.
605  *
606  * @param object $quiz a quiz.
607  */
608 function quiz_update_all_attempt_sumgrades($quiz) {
609     global $DB;
610     $dm = new question_engine_data_mapper();
611     $timenow = time();
613     $sql = "UPDATE {quiz_attempts}
614             SET
615                 timemodified = :timenow,
616                 sumgrades = (
617                     {$dm->sum_usage_marks_subquery('uniqueid')}
618                 )
619             WHERE quiz = :quizid AND state = :finishedstate";
620     $DB->execute($sql, array('timenow' => $timenow, 'quizid' => $quiz->id,
621             'finishedstate' => quiz_attempt::FINISHED));
624 /**
625  * The quiz grade is the maximum that student's results are marked out of. When it
626  * changes, the corresponding data in quiz_grades and quiz_feedback needs to be
627  * rescaled. After calling this function, you probably need to call
628  * quiz_update_all_attempt_sumgrades, quiz_update_all_final_grades and
629  * quiz_update_grades.
630  *
631  * @param float $newgrade the new maximum grade for the quiz.
632  * @param object $quiz the quiz we are updating. Passed by reference so its
633  *      grade field can be updated too.
634  * @return bool indicating success or failure.
635  */
636 function quiz_set_grade($newgrade, $quiz) {
637     global $DB;
638     // This is potentially expensive, so only do it if necessary.
639     if (abs($quiz->grade - $newgrade) < 1e-7) {
640         // Nothing to do.
641         return true;
642     }
644     $oldgrade = $quiz->grade;
645     $quiz->grade = $newgrade;
647     // Use a transaction, so that on those databases that support it, this is safer.
648     $transaction = $DB->start_delegated_transaction();
650     // Update the quiz table.
651     $DB->set_field('quiz', 'grade', $newgrade, array('id' => $quiz->instance));
653     if ($oldgrade < 1) {
654         // If the old grade was zero, we cannot rescale, we have to recompute.
655         // We also recompute if the old grade was too small to avoid underflow problems.
656         quiz_update_all_final_grades($quiz);
658     } else {
659         // We can rescale the grades efficiently.
660         $timemodified = time();
661         $DB->execute("
662                 UPDATE {quiz_grades}
663                 SET grade = ? * grade, timemodified = ?
664                 WHERE quiz = ?
665         ", array($newgrade/$oldgrade, $timemodified, $quiz->id));
666     }
668     if ($oldgrade > 1e-7) {
669         // Update the quiz_feedback table.
670         $factor = $newgrade/$oldgrade;
671         $DB->execute("
672                 UPDATE {quiz_feedback}
673                 SET mingrade = ? * mingrade, maxgrade = ? * maxgrade
674                 WHERE quizid = ?
675         ", array($factor, $factor, $quiz->id));
676     }
678     // Update grade item and send all grades to gradebook.
679     quiz_grade_item_update($quiz);
680     quiz_update_grades($quiz);
682     $transaction->allow_commit();
683     return true;
686 /**
687  * Save the overall grade for a user at a quiz in the quiz_grades table
688  *
689  * @param object $quiz The quiz for which the best grade is to be calculated and then saved.
690  * @param int $userid The userid to calculate the grade for. Defaults to the current user.
691  * @param array $attempts The attempts of this user. Useful if you are
692  * looping through many users. Attempts can be fetched in one master query to
693  * avoid repeated querying.
694  * @return bool Indicates success or failure.
695  */
696 function quiz_save_best_grade($quiz, $userid = null, $attempts = array()) {
697     global $DB, $OUTPUT, $USER;
699     if (empty($userid)) {
700         $userid = $USER->id;
701     }
703     if (!$attempts) {
704         // Get all the attempts made by the user.
705         $attempts = quiz_get_user_attempts($quiz->id, $userid);
706     }
708     // Calculate the best grade.
709     $bestgrade = quiz_calculate_best_grade($quiz, $attempts);
710     $bestgrade = quiz_rescale_grade($bestgrade, $quiz, false);
712     // Save the best grade in the database.
713     if (is_null($bestgrade)) {
714         $DB->delete_records('quiz_grades', array('quiz' => $quiz->id, 'userid' => $userid));
716     } else if ($grade = $DB->get_record('quiz_grades',
717             array('quiz' => $quiz->id, 'userid' => $userid))) {
718         $grade->grade = $bestgrade;
719         $grade->timemodified = time();
720         $DB->update_record('quiz_grades', $grade);
722     } else {
723         $grade = new stdClass();
724         $grade->quiz = $quiz->id;
725         $grade->userid = $userid;
726         $grade->grade = $bestgrade;
727         $grade->timemodified = time();
728         $DB->insert_record('quiz_grades', $grade);
729     }
731     quiz_update_grades($quiz, $userid);
734 /**
735  * Calculate the overall grade for a quiz given a number of attempts by a particular user.
736  *
737  * @param object $quiz    the quiz settings object.
738  * @param array $attempts an array of all the user's attempts at this quiz in order.
739  * @return float          the overall grade
740  */
741 function quiz_calculate_best_grade($quiz, $attempts) {
743     switch ($quiz->grademethod) {
745         case QUIZ_ATTEMPTFIRST:
746             $firstattempt = reset($attempts);
747             return $firstattempt->sumgrades;
749         case QUIZ_ATTEMPTLAST:
750             $lastattempt = end($attempts);
751             return $lastattempt->sumgrades;
753         case QUIZ_GRADEAVERAGE:
754             $sum = 0;
755             $count = 0;
756             foreach ($attempts as $attempt) {
757                 if (!is_null($attempt->sumgrades)) {
758                     $sum += $attempt->sumgrades;
759                     $count++;
760                 }
761             }
762             if ($count == 0) {
763                 return null;
764             }
765             return $sum / $count;
767         case QUIZ_GRADEHIGHEST:
768         default:
769             $max = null;
770             foreach ($attempts as $attempt) {
771                 if ($attempt->sumgrades > $max) {
772                     $max = $attempt->sumgrades;
773                 }
774             }
775             return $max;
776     }
779 /**
780  * Update the final grade at this quiz for all students.
781  *
782  * This function is equivalent to calling quiz_save_best_grade for all
783  * users, but much more efficient.
784  *
785  * @param object $quiz the quiz settings.
786  */
787 function quiz_update_all_final_grades($quiz) {
788     global $DB;
790     if (!$quiz->sumgrades) {
791         return;
792     }
794     $param = array('iquizid' => $quiz->id, 'istatefinished' => quiz_attempt::FINISHED);
795     $firstlastattemptjoin = "JOIN (
796             SELECT
797                 iquiza.userid,
798                 MIN(attempt) AS firstattempt,
799                 MAX(attempt) AS lastattempt
801             FROM {quiz_attempts} iquiza
803             WHERE
804                 iquiza.state = :istatefinished AND
805                 iquiza.preview = 0 AND
806                 iquiza.quiz = :iquizid
808             GROUP BY iquiza.userid
809         ) first_last_attempts ON first_last_attempts.userid = quiza.userid";
811     switch ($quiz->grademethod) {
812         case QUIZ_ATTEMPTFIRST:
813             // Because of the where clause, there will only be one row, but we
814             // must still use an aggregate function.
815             $select = 'MAX(quiza.sumgrades)';
816             $join = $firstlastattemptjoin;
817             $where = 'quiza.attempt = first_last_attempts.firstattempt AND';
818             break;
820         case QUIZ_ATTEMPTLAST:
821             // Because of the where clause, there will only be one row, but we
822             // must still use an aggregate function.
823             $select = 'MAX(quiza.sumgrades)';
824             $join = $firstlastattemptjoin;
825             $where = 'quiza.attempt = first_last_attempts.lastattempt AND';
826             break;
828         case QUIZ_GRADEAVERAGE:
829             $select = 'AVG(quiza.sumgrades)';
830             $join = '';
831             $where = '';
832             break;
834         default:
835         case QUIZ_GRADEHIGHEST:
836             $select = 'MAX(quiza.sumgrades)';
837             $join = '';
838             $where = '';
839             break;
840     }
842     if ($quiz->sumgrades >= 0.000005) {
843         $finalgrade = $select . ' * ' . ($quiz->grade / $quiz->sumgrades);
844     } else {
845         $finalgrade = '0';
846     }
847     $param['quizid'] = $quiz->id;
848     $param['quizid2'] = $quiz->id;
849     $param['quizid3'] = $quiz->id;
850     $param['quizid4'] = $quiz->id;
851     $param['statefinished'] = quiz_attempt::FINISHED;
852     $param['statefinished2'] = quiz_attempt::FINISHED;
853     $finalgradesubquery = "
854             SELECT quiza.userid, $finalgrade AS newgrade
855             FROM {quiz_attempts} quiza
856             $join
857             WHERE
858                 $where
859                 quiza.state = :statefinished AND
860                 quiza.preview = 0 AND
861                 quiza.quiz = :quizid3
862             GROUP BY quiza.userid";
864     $changedgrades = $DB->get_records_sql("
865             SELECT users.userid, qg.id, qg.grade, newgrades.newgrade
867             FROM (
868                 SELECT userid
869                 FROM {quiz_grades} qg
870                 WHERE quiz = :quizid
871             UNION
872                 SELECT DISTINCT userid
873                 FROM {quiz_attempts} quiza2
874                 WHERE
875                     quiza2.state = :statefinished2 AND
876                     quiza2.preview = 0 AND
877                     quiza2.quiz = :quizid2
878             ) users
880             LEFT JOIN {quiz_grades} qg ON qg.userid = users.userid AND qg.quiz = :quizid4
882             LEFT JOIN (
883                 $finalgradesubquery
884             ) newgrades ON newgrades.userid = users.userid
886             WHERE
887                 ABS(newgrades.newgrade - qg.grade) > 0.000005 OR
888                 ((newgrades.newgrade IS NULL OR qg.grade IS NULL) AND NOT
889                           (newgrades.newgrade IS NULL AND qg.grade IS NULL))",
890                 // The mess on the previous line is detecting where the value is
891                 // NULL in one column, and NOT NULL in the other, but SQL does
892                 // not have an XOR operator, and MS SQL server can't cope with
893                 // (newgrades.newgrade IS NULL) <> (qg.grade IS NULL).
894             $param);
896     $timenow = time();
897     $todelete = array();
898     foreach ($changedgrades as $changedgrade) {
900         if (is_null($changedgrade->newgrade)) {
901             $todelete[] = $changedgrade->userid;
903         } else if (is_null($changedgrade->grade)) {
904             $toinsert = new stdClass();
905             $toinsert->quiz = $quiz->id;
906             $toinsert->userid = $changedgrade->userid;
907             $toinsert->timemodified = $timenow;
908             $toinsert->grade = $changedgrade->newgrade;
909             $DB->insert_record('quiz_grades', $toinsert);
911         } else {
912             $toupdate = new stdClass();
913             $toupdate->id = $changedgrade->id;
914             $toupdate->grade = $changedgrade->newgrade;
915             $toupdate->timemodified = $timenow;
916             $DB->update_record('quiz_grades', $toupdate);
917         }
918     }
920     if (!empty($todelete)) {
921         list($test, $params) = $DB->get_in_or_equal($todelete);
922         $DB->delete_records_select('quiz_grades', 'quiz = ? AND userid ' . $test,
923                 array_merge(array($quiz->id), $params));
924     }
927 /**
928  * Efficiently update check state time on all open attempts
929  *
930  * @param array $conditions optional restrictions on which attempts to update
931  *                    Allowed conditions:
932  *                      courseid => (array|int) attempts in given course(s)
933  *                      userid   => (array|int) attempts for given user(s)
934  *                      quizid   => (array|int) attempts in given quiz(s)
935  *                      groupid  => (array|int) quizzes with some override for given group(s)
936  *
937  */
938 function quiz_update_open_attempts(array $conditions) {
939     global $DB;
941     foreach ($conditions as &$value) {
942         if (!is_array($value)) {
943             $value = array($value);
944         }
945     }
947     $params = array();
948     $wheres = array("quiza.state IN ('inprogress', 'overdue')");
949     $iwheres = array("iquiza.state IN ('inprogress', 'overdue')");
951     if (isset($conditions['courseid'])) {
952         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['courseid'], SQL_PARAMS_NAMED, 'cid');
953         $params = array_merge($params, $inparams);
954         $wheres[] = "quiza.quiz IN (SELECT q.id FROM {quiz} q WHERE q.course $incond)";
955         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['courseid'], SQL_PARAMS_NAMED, 'icid');
956         $params = array_merge($params, $inparams);
957         $iwheres[] = "iquiza.quiz IN (SELECT q.id FROM {quiz} q WHERE q.course $incond)";
958     }
960     if (isset($conditions['userid'])) {
961         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['userid'], SQL_PARAMS_NAMED, 'uid');
962         $params = array_merge($params, $inparams);
963         $wheres[] = "quiza.userid $incond";
964         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['userid'], SQL_PARAMS_NAMED, 'iuid');
965         $params = array_merge($params, $inparams);
966         $iwheres[] = "iquiza.userid $incond";
967     }
969     if (isset($conditions['quizid'])) {
970         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['quizid'], SQL_PARAMS_NAMED, 'qid');
971         $params = array_merge($params, $inparams);
972         $wheres[] = "quiza.quiz $incond";
973         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['quizid'], SQL_PARAMS_NAMED, 'iqid');
974         $params = array_merge($params, $inparams);
975         $iwheres[] = "iquiza.quiz $incond";
976     }
978     if (isset($conditions['groupid'])) {
979         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['groupid'], SQL_PARAMS_NAMED, 'gid');
980         $params = array_merge($params, $inparams);
981         $wheres[] = "quiza.quiz IN (SELECT qo.quiz FROM {quiz_overrides} qo WHERE qo.groupid $incond)";
982         list ($incond, $inparams) = $DB->get_in_or_equal($conditions['groupid'], SQL_PARAMS_NAMED, 'igid');
983         $params = array_merge($params, $inparams);
984         $iwheres[] = "iquiza.quiz IN (SELECT qo.quiz FROM {quiz_overrides} qo WHERE qo.groupid $incond)";
985     }
987     // SQL to compute timeclose and timelimit for each attempt:
988     $quizausersql = quiz_get_attempt_usertime_sql(
989             implode("\n                AND ", $iwheres));
991     // SQL to compute the new timecheckstate
992     $timecheckstatesql = "
993           CASE WHEN quizauser.usertimelimit = 0 AND quizauser.usertimeclose = 0 THEN NULL
994                WHEN quizauser.usertimelimit = 0 THEN quizauser.usertimeclose
995                WHEN quizauser.usertimeclose = 0 THEN quiza.timestart + quizauser.usertimelimit
996                WHEN quiza.timestart + quizauser.usertimelimit < quizauser.usertimeclose THEN quiza.timestart + quizauser.usertimelimit
997                ELSE quizauser.usertimeclose END +
998           CASE WHEN quiza.state = 'overdue' THEN quiz.graceperiod ELSE 0 END";
1000     // SQL to select which attempts to process
1001     $attemptselect = implode("\n                         AND ", $wheres);
1003    /*
1004     * Each database handles updates with inner joins differently:
1005     *  - mysql does not allow a FROM clause
1006     *  - postgres and mssql allow FROM but handle table aliases differently
1007     *  - oracle requires a subquery
1008     *
1009     * Different code for each database.
1010     */
1012     $dbfamily = $DB->get_dbfamily();
1013     if ($dbfamily == 'mysql') {
1014         $updatesql = "UPDATE {quiz_attempts} quiza
1015                         JOIN {quiz} quiz ON quiz.id = quiza.quiz
1016                         JOIN ( $quizausersql ) quizauser ON quizauser.id = quiza.id
1017                          SET quiza.timecheckstate = $timecheckstatesql
1018                        WHERE $attemptselect";
1019     } else if ($dbfamily == 'postgres') {
1020         $updatesql = "UPDATE {quiz_attempts} quiza
1021                          SET timecheckstate = $timecheckstatesql
1022                         FROM {quiz} quiz, ( $quizausersql ) quizauser
1023                        WHERE quiz.id = quiza.quiz
1024                          AND quizauser.id = quiza.id
1025                          AND $attemptselect";
1026     } else if ($dbfamily == 'mssql') {
1027         $updatesql = "UPDATE quiza
1028                          SET timecheckstate = $timecheckstatesql
1029                         FROM {quiz_attempts} quiza
1030                         JOIN {quiz} quiz ON quiz.id = quiza.quiz
1031                         JOIN ( $quizausersql ) quizauser ON quizauser.id = quiza.id
1032                        WHERE $attemptselect";
1033     } else {
1034         // oracle, sqlite and others
1035         $updatesql = "UPDATE {quiz_attempts} quiza
1036                          SET timecheckstate = (
1037                            SELECT $timecheckstatesql
1038                              FROM {quiz} quiz, ( $quizausersql ) quizauser
1039                             WHERE quiz.id = quiza.quiz
1040                               AND quizauser.id = quiza.id
1041                          )
1042                          WHERE $attemptselect";
1043     }
1045     $DB->execute($updatesql, $params);
1048 /**
1049  * Returns SQL to compute timeclose and timelimit for every attempt, taking into account user and group overrides.
1050  *
1051  * @param string $redundantwhereclauses extra where clauses to add to the subquery
1052  *      for performance. These can use the table alias iquiza for the quiz attempts table.
1053  * @return string SQL select with columns attempt.id, usertimeclose, usertimelimit.
1054  */
1055 function quiz_get_attempt_usertime_sql($redundantwhereclauses = '') {
1056     if ($redundantwhereclauses) {
1057         $redundantwhereclauses = 'WHERE ' . $redundantwhereclauses;
1058     }
1059     // The multiple qgo JOINS are necessary because we want timeclose/timelimit = 0 (unlimited) to supercede
1060     // any other group override
1061     $quizausersql = "
1062           SELECT iquiza.id,
1063            COALESCE(MAX(quo.timeclose), MAX(qgo1.timeclose), MAX(qgo2.timeclose), iquiz.timeclose) AS usertimeclose,
1064            COALESCE(MAX(quo.timelimit), MAX(qgo3.timelimit), MAX(qgo4.timelimit), iquiz.timelimit) AS usertimelimit
1066            FROM {quiz_attempts} iquiza
1067            JOIN {quiz} iquiz ON iquiz.id = iquiza.quiz
1068       LEFT JOIN {quiz_overrides} quo ON quo.quiz = iquiza.quiz AND quo.userid = iquiza.userid
1069       LEFT JOIN {groups_members} gm ON gm.userid = iquiza.userid
1070       LEFT JOIN {quiz_overrides} qgo1 ON qgo1.quiz = iquiza.quiz AND qgo1.groupid = gm.groupid AND qgo1.timeclose = 0
1071       LEFT JOIN {quiz_overrides} qgo2 ON qgo2.quiz = iquiza.quiz AND qgo2.groupid = gm.groupid AND qgo2.timeclose > 0
1072       LEFT JOIN {quiz_overrides} qgo3 ON qgo3.quiz = iquiza.quiz AND qgo3.groupid = gm.groupid AND qgo3.timelimit = 0
1073       LEFT JOIN {quiz_overrides} qgo4 ON qgo4.quiz = iquiza.quiz AND qgo4.groupid = gm.groupid AND qgo4.timelimit > 0
1074           $redundantwhereclauses
1075        GROUP BY iquiza.id, iquiz.id, iquiz.timeclose, iquiz.timelimit";
1076     return $quizausersql;
1079 /**
1080  * Return the attempt with the best grade for a quiz
1081  *
1082  * Which attempt is the best depends on $quiz->grademethod. If the grade
1083  * method is GRADEAVERAGE then this function simply returns the last attempt.
1084  * @return object         The attempt with the best grade
1085  * @param object $quiz    The quiz for which the best grade is to be calculated
1086  * @param array $attempts An array of all the attempts of the user at the quiz
1087  */
1088 function quiz_calculate_best_attempt($quiz, $attempts) {
1090     switch ($quiz->grademethod) {
1092         case QUIZ_ATTEMPTFIRST:
1093             foreach ($attempts as $attempt) {
1094                 return $attempt;
1095             }
1096             break;
1098         case QUIZ_GRADEAVERAGE: // We need to do something with it.
1099         case QUIZ_ATTEMPTLAST:
1100             foreach ($attempts as $attempt) {
1101                 $final = $attempt;
1102             }
1103             return $final;
1105         default:
1106         case QUIZ_GRADEHIGHEST:
1107             $max = -1;
1108             foreach ($attempts as $attempt) {
1109                 if ($attempt->sumgrades > $max) {
1110                     $max = $attempt->sumgrades;
1111                     $maxattempt = $attempt;
1112                 }
1113             }
1114             return $maxattempt;
1115     }
1118 /**
1119  * @return array int => lang string the options for calculating the quiz grade
1120  *      from the individual attempt grades.
1121  */
1122 function quiz_get_grading_options() {
1123     return array(
1124         QUIZ_GRADEHIGHEST => get_string('gradehighest', 'quiz'),
1125         QUIZ_GRADEAVERAGE => get_string('gradeaverage', 'quiz'),
1126         QUIZ_ATTEMPTFIRST => get_string('attemptfirst', 'quiz'),
1127         QUIZ_ATTEMPTLAST  => get_string('attemptlast', 'quiz')
1128     );
1131 /**
1132  * @param int $option one of the values QUIZ_GRADEHIGHEST, QUIZ_GRADEAVERAGE,
1133  *      QUIZ_ATTEMPTFIRST or QUIZ_ATTEMPTLAST.
1134  * @return the lang string for that option.
1135  */
1136 function quiz_get_grading_option_name($option) {
1137     $strings = quiz_get_grading_options();
1138     return $strings[$option];
1141 /**
1142  * @return array string => lang string the options for handling overdue quiz
1143  *      attempts.
1144  */
1145 function quiz_get_overdue_handling_options() {
1146     return array(
1147         'autosubmit'  => get_string('overduehandlingautosubmit', 'quiz'),
1148         'graceperiod' => get_string('overduehandlinggraceperiod', 'quiz'),
1149         'autoabandon' => get_string('overduehandlingautoabandon', 'quiz'),
1150     );
1153 /**
1154  * @param string $state one of the state constants like IN_PROGRESS.
1155  * @return string the human-readable state name.
1156  */
1157 function quiz_attempt_state_name($state) {
1158     switch ($state) {
1159         case quiz_attempt::IN_PROGRESS:
1160             return get_string('stateinprogress', 'quiz');
1161         case quiz_attempt::OVERDUE:
1162             return get_string('stateoverdue', 'quiz');
1163         case quiz_attempt::FINISHED:
1164             return get_string('statefinished', 'quiz');
1165         case quiz_attempt::ABANDONED:
1166             return get_string('stateabandoned', 'quiz');
1167         default:
1168             throw new coding_exception('Unknown quiz attempt state.');
1169     }
1172 // Other quiz functions ////////////////////////////////////////////////////////
1174 /**
1175  * @param object $quiz the quiz.
1176  * @param int $cmid the course_module object for this quiz.
1177  * @param object $question the question.
1178  * @param string $returnurl url to return to after action is done.
1179  * @return string html for a number of icons linked to action pages for a
1180  * question - preview and edit / view icons depending on user capabilities.
1181  */
1182 function quiz_question_action_icons($quiz, $cmid, $question, $returnurl) {
1183     $html = quiz_question_preview_button($quiz, $question) . ' ' .
1184             quiz_question_edit_button($cmid, $question, $returnurl);
1185     return $html;
1188 /**
1189  * @param int $cmid the course_module.id for this quiz.
1190  * @param object $question the question.
1191  * @param string $returnurl url to return to after action is done.
1192  * @param string $contentbeforeicon some HTML content to be added inside the link, before the icon.
1193  * @return the HTML for an edit icon, view icon, or nothing for a question
1194  *      (depending on permissions).
1195  */
1196 function quiz_question_edit_button($cmid, $question, $returnurl, $contentaftericon = '') {
1197     global $CFG, $OUTPUT;
1199     // Minor efficiency saving. Only get strings once, even if there are a lot of icons on one page.
1200     static $stredit = null;
1201     static $strview = null;
1202     if ($stredit === null) {
1203         $stredit = get_string('edit');
1204         $strview = get_string('view');
1205     }
1207     // What sort of icon should we show?
1208     $action = '';
1209     if (!empty($question->id) &&
1210             (question_has_capability_on($question, 'edit', $question->category) ||
1211                     question_has_capability_on($question, 'move', $question->category))) {
1212         $action = $stredit;
1213         $icon = '/t/edit';
1214     } else if (!empty($question->id) &&
1215             question_has_capability_on($question, 'view', $question->category)) {
1216         $action = $strview;
1217         $icon = '/i/info';
1218     }
1220     // Build the icon.
1221     if ($action) {
1222         if ($returnurl instanceof moodle_url) {
1223             $returnurl = $returnurl->out_as_local_url(false);
1224         }
1225         $questionparams = array('returnurl' => $returnurl, 'cmid' => $cmid, 'id' => $question->id);
1226         $questionurl = new moodle_url("$CFG->wwwroot/question/question.php", $questionparams);
1227         return '<a title="' . $action . '" href="' . $questionurl->out() . '" class="questioneditbutton"><img src="' .
1228                 $OUTPUT->pix_url($icon) . '" alt="' . $action . '" />' . $contentaftericon .
1229                 '</a>';
1230     } else if ($contentaftericon) {
1231         return '<span class="questioneditbutton">' . $contentaftericon . '</span>';
1232     } else {
1233         return '';
1234     }
1237 /**
1238  * @param object $quiz the quiz settings
1239  * @param object $question the question
1240  * @return moodle_url to preview this question with the options from this quiz.
1241  */
1242 function quiz_question_preview_url($quiz, $question) {
1243     // Get the appropriate display options.
1244     $displayoptions = mod_quiz_display_options::make_from_quiz($quiz,
1245             mod_quiz_display_options::DURING);
1247     $maxmark = null;
1248     if (isset($question->maxmark)) {
1249         $maxmark = $question->maxmark;
1250     }
1252     // Work out the correcte preview URL.
1253     return question_preview_url($question->id, $quiz->preferredbehaviour,
1254             $maxmark, $displayoptions);
1257 /**
1258  * @param object $quiz the quiz settings
1259  * @param object $question the question
1260  * @param bool $label if true, show the preview question label after the icon
1261  * @return the HTML for a preview question icon.
1262  */
1263 function quiz_question_preview_button($quiz, $question, $label = false) {
1264     global $CFG, $OUTPUT;
1265     if (!question_has_capability_on($question, 'use', $question->category)) {
1266         return '';
1267     }
1269     $url = quiz_question_preview_url($quiz, $question);
1271     // Do we want a label?
1272     $strpreviewlabel = '';
1273     if ($label) {
1274         $strpreviewlabel = get_string('preview', 'quiz');
1275     }
1277     // Build the icon.
1278     $strpreviewquestion = get_string('previewquestion', 'quiz');
1279     $image = $OUTPUT->pix_icon('t/preview', $strpreviewquestion);
1281     $action = new popup_action('click', $url, 'questionpreview',
1282             question_preview_popup_params());
1284     return $OUTPUT->action_link($url, $image, $action, array('title' => $strpreviewquestion));
1287 /**
1288  * @param object $attempt the attempt.
1289  * @param object $context the quiz context.
1290  * @return int whether flags should be shown/editable to the current user for this attempt.
1291  */
1292 function quiz_get_flag_option($attempt, $context) {
1293     global $USER;
1294     if (!has_capability('moodle/question:flag', $context)) {
1295         return question_display_options::HIDDEN;
1296     } else if ($attempt->userid == $USER->id) {
1297         return question_display_options::EDITABLE;
1298     } else {
1299         return question_display_options::VISIBLE;
1300     }
1303 /**
1304  * Work out what state this quiz attempt is in - in the sense used by
1305  * quiz_get_review_options, not in the sense of $attempt->state.
1306  * @param object $quiz the quiz settings
1307  * @param object $attempt the quiz_attempt database row.
1308  * @return int one of the mod_quiz_display_options::DURING,
1309  *      IMMEDIATELY_AFTER, LATER_WHILE_OPEN or AFTER_CLOSE constants.
1310  */
1311 function quiz_attempt_state($quiz, $attempt) {
1312     if ($attempt->state == quiz_attempt::IN_PROGRESS) {
1313         return mod_quiz_display_options::DURING;
1314     } else if (time() < $attempt->timefinish + 120) {
1315         return mod_quiz_display_options::IMMEDIATELY_AFTER;
1316     } else if (!$quiz->timeclose || time() < $quiz->timeclose) {
1317         return mod_quiz_display_options::LATER_WHILE_OPEN;
1318     } else {
1319         return mod_quiz_display_options::AFTER_CLOSE;
1320     }
1323 /**
1324  * The the appropraite mod_quiz_display_options object for this attempt at this
1325  * quiz right now.
1326  *
1327  * @param object $quiz the quiz instance.
1328  * @param object $attempt the attempt in question.
1329  * @param $context the quiz context.
1330  *
1331  * @return mod_quiz_display_options
1332  */
1333 function quiz_get_review_options($quiz, $attempt, $context) {
1334     $options = mod_quiz_display_options::make_from_quiz($quiz, quiz_attempt_state($quiz, $attempt));
1336     $options->readonly = true;
1337     $options->flags = quiz_get_flag_option($attempt, $context);
1338     if (!empty($attempt->id)) {
1339         $options->questionreviewlink = new moodle_url('/mod/quiz/reviewquestion.php',
1340                 array('attempt' => $attempt->id));
1341     }
1343     // Show a link to the comment box only for closed attempts.
1344     if (!empty($attempt->id) && $attempt->state == quiz_attempt::FINISHED && !$attempt->preview &&
1345             !is_null($context) && has_capability('mod/quiz:grade', $context)) {
1346         $options->manualcomment = question_display_options::VISIBLE;
1347         $options->manualcommentlink = new moodle_url('/mod/quiz/comment.php',
1348                 array('attempt' => $attempt->id));
1349     }
1351     if (!is_null($context) && !$attempt->preview &&
1352             has_capability('mod/quiz:viewreports', $context) &&
1353             has_capability('moodle/grade:viewhidden', $context)) {
1354         // People who can see reports and hidden grades should be shown everything,
1355         // except during preview when teachers want to see what students see.
1356         $options->attempt = question_display_options::VISIBLE;
1357         $options->correctness = question_display_options::VISIBLE;
1358         $options->marks = question_display_options::MARK_AND_MAX;
1359         $options->feedback = question_display_options::VISIBLE;
1360         $options->numpartscorrect = question_display_options::VISIBLE;
1361         $options->generalfeedback = question_display_options::VISIBLE;
1362         $options->rightanswer = question_display_options::VISIBLE;
1363         $options->overallfeedback = question_display_options::VISIBLE;
1364         $options->history = question_display_options::VISIBLE;
1366     }
1368     return $options;
1371 /**
1372  * Combines the review options from a number of different quiz attempts.
1373  * Returns an array of two ojects, so the suggested way of calling this
1374  * funciton is:
1375  * list($someoptions, $alloptions) = quiz_get_combined_reviewoptions(...)
1376  *
1377  * @param object $quiz the quiz instance.
1378  * @param array $attempts an array of attempt objects.
1379  * @param $context the roles and permissions context,
1380  *          normally the context for the quiz module instance.
1381  *
1382  * @return array of two options objects, one showing which options are true for
1383  *          at least one of the attempts, the other showing which options are true
1384  *          for all attempts.
1385  */
1386 function quiz_get_combined_reviewoptions($quiz, $attempts) {
1387     $fields = array('feedback', 'generalfeedback', 'rightanswer', 'overallfeedback');
1388     $someoptions = new stdClass();
1389     $alloptions = new stdClass();
1390     foreach ($fields as $field) {
1391         $someoptions->$field = false;
1392         $alloptions->$field = true;
1393     }
1394     $someoptions->marks = question_display_options::HIDDEN;
1395     $alloptions->marks = question_display_options::MARK_AND_MAX;
1397     foreach ($attempts as $attempt) {
1398         $attemptoptions = mod_quiz_display_options::make_from_quiz($quiz,
1399                 quiz_attempt_state($quiz, $attempt));
1400         foreach ($fields as $field) {
1401             $someoptions->$field = $someoptions->$field || $attemptoptions->$field;
1402             $alloptions->$field = $alloptions->$field && $attemptoptions->$field;
1403         }
1404         $someoptions->marks = max($someoptions->marks, $attemptoptions->marks);
1405         $alloptions->marks = min($alloptions->marks, $attemptoptions->marks);
1406     }
1407     return array($someoptions, $alloptions);
1410 /**
1411  * Clean the question layout from various possible anomalies:
1412  * - Remove consecutive ","'s
1413  * - Remove duplicate question id's
1414  * - Remove extra "," from beginning and end
1415  * - Finally, add a ",0" in the end if there is none
1416  *
1417  * @param $string $layout the quiz layout to clean up, usually from $quiz->questions.
1418  * @param bool $removeemptypages If true, remove empty pages from the quiz. False by default.
1419  * @return $string the cleaned-up layout
1420  */
1421 function quiz_clean_layout($layout, $removeemptypages = false) {
1422     // Remove repeated ','s. This can happen when a restore fails to find the right
1423     // id to relink to.
1424     $layout = preg_replace('/,{2,}/', ',', trim($layout, ','));
1426     // Remove duplicate question ids.
1427     $layout = explode(',', $layout);
1428     $cleanerlayout = array();
1429     $seen = array();
1430     foreach ($layout as $item) {
1431         if ($item == 0) {
1432             $cleanerlayout[] = '0';
1433         } else if (!in_array($item, $seen)) {
1434             $cleanerlayout[] = $item;
1435             $seen[] = $item;
1436         }
1437     }
1439     if ($removeemptypages) {
1440         // Avoid duplicate page breaks.
1441         $layout = $cleanerlayout;
1442         $cleanerlayout = array();
1443         $stripfollowingbreaks = true; // Ensure breaks are stripped from the start.
1444         foreach ($layout as $item) {
1445             if ($stripfollowingbreaks && $item == 0) {
1446                 continue;
1447             }
1448             $cleanerlayout[] = $item;
1449             $stripfollowingbreaks = $item == 0;
1450         }
1451     }
1453     // Add a page break at the end if there is none.
1454     if (end($cleanerlayout) !== '0') {
1455         $cleanerlayout[] = '0';
1456     }
1458     return implode(',', $cleanerlayout);
1461 /**
1462  * Get the slot for a question with a particular id.
1463  * @param object $quiz the quiz settings.
1464  * @param int $questionid the of a question in the quiz.
1465  * @return int the corresponding slot. Null if the question is not in the quiz.
1466  */
1467 function quiz_get_slot_for_question($quiz, $questionid) {
1468     $questionids = quiz_questions_in_quiz($quiz->questions);
1469     foreach (explode(',', $questionids) as $key => $id) {
1470         if ($id == $questionid) {
1471             return $key + 1;
1472         }
1473     }
1474     return null;
1477 // Functions for sending notification messages /////////////////////////////////
1479 /**
1480  * Sends a confirmation message to the student confirming that the attempt was processed.
1481  *
1482  * @param object $a lots of useful information that can be used in the message
1483  *      subject and body.
1484  *
1485  * @return int|false as for {@link message_send()}.
1486  */
1487 function quiz_send_confirmation($recipient, $a) {
1489     // Add information about the recipient to $a.
1490     // Don't do idnumber. we want idnumber to be the submitter's idnumber.
1491     $a->username     = fullname($recipient);
1492     $a->userusername = $recipient->username;
1494     // Prepare the message.
1495     $eventdata = new stdClass();
1496     $eventdata->component         = 'mod_quiz';
1497     $eventdata->name              = 'confirmation';
1498     $eventdata->notification      = 1;
1500     $eventdata->userfrom          = get_admin();
1501     $eventdata->userto            = $recipient;
1502     $eventdata->subject           = get_string('emailconfirmsubject', 'quiz', $a);
1503     $eventdata->fullmessage       = get_string('emailconfirmbody', 'quiz', $a);
1504     $eventdata->fullmessageformat = FORMAT_PLAIN;
1505     $eventdata->fullmessagehtml   = '';
1507     $eventdata->smallmessage      = get_string('emailconfirmsmall', 'quiz', $a);
1508     $eventdata->contexturl        = $a->quizurl;
1509     $eventdata->contexturlname    = $a->quizname;
1511     // ... and send it.
1512     return message_send($eventdata);
1515 /**
1516  * Sends notification messages to the interested parties that assign the role capability
1517  *
1518  * @param object $recipient user object of the intended recipient
1519  * @param object $a associative array of replaceable fields for the templates
1520  *
1521  * @return int|false as for {@link message_send()}.
1522  */
1523 function quiz_send_notification($recipient, $submitter, $a) {
1525     // Recipient info for template.
1526     $a->useridnumber = $recipient->idnumber;
1527     $a->username     = fullname($recipient);
1528     $a->userusername = $recipient->username;
1530     // Prepare the message.
1531     $eventdata = new stdClass();
1532     $eventdata->component         = 'mod_quiz';
1533     $eventdata->name              = 'submission';
1534     $eventdata->notification      = 1;
1536     $eventdata->userfrom          = $submitter;
1537     $eventdata->userto            = $recipient;
1538     $eventdata->subject           = get_string('emailnotifysubject', 'quiz', $a);
1539     $eventdata->fullmessage       = get_string('emailnotifybody', 'quiz', $a);
1540     $eventdata->fullmessageformat = FORMAT_PLAIN;
1541     $eventdata->fullmessagehtml   = '';
1543     $eventdata->smallmessage      = get_string('emailnotifysmall', 'quiz', $a);
1544     $eventdata->contexturl        = $a->quizreviewurl;
1545     $eventdata->contexturlname    = $a->quizname;
1547     // ... and send it.
1548     return message_send($eventdata);
1551 /**
1552  * Send all the requried messages when a quiz attempt is submitted.
1553  *
1554  * @param object $course the course
1555  * @param object $quiz the quiz
1556  * @param object $attempt this attempt just finished
1557  * @param object $context the quiz context
1558  * @param object $cm the coursemodule for this quiz
1559  *
1560  * @return bool true if all necessary messages were sent successfully, else false.
1561  */
1562 function quiz_send_notification_messages($course, $quiz, $attempt, $context, $cm) {
1563     global $CFG, $DB;
1565     // Do nothing if required objects not present.
1566     if (empty($course) or empty($quiz) or empty($attempt) or empty($context)) {
1567         throw new coding_exception('$course, $quiz, $attempt, $context and $cm must all be set.');
1568     }
1570     $submitter = $DB->get_record('user', array('id' => $attempt->userid), '*', MUST_EXIST);
1572     // Check for confirmation required.
1573     $sendconfirm = false;
1574     $notifyexcludeusers = '';
1575     if (has_capability('mod/quiz:emailconfirmsubmission', $context, $submitter, false)) {
1576         $notifyexcludeusers = $submitter->id;
1577         $sendconfirm = true;
1578     }
1580     // Check for notifications required.
1581     $notifyfields = 'u.id, u.username, u.firstname, u.lastname, u.idnumber, u.email, u.emailstop, ' .
1582             'u.lang, u.timezone, u.mailformat, u.maildisplay';
1583     $groups = groups_get_all_groups($course->id, $submitter->id);
1584     if (is_array($groups) && count($groups) > 0) {
1585         $groups = array_keys($groups);
1586     } else if (groups_get_activity_groupmode($cm, $course) != NOGROUPS) {
1587         // If the user is not in a group, and the quiz is set to group mode,
1588         // then set $groups to a non-existant id so that only users with
1589         // 'moodle/site:accessallgroups' get notified.
1590         $groups = -1;
1591     } else {
1592         $groups = '';
1593     }
1594     $userstonotify = get_users_by_capability($context, 'mod/quiz:emailnotifysubmission',
1595             $notifyfields, '', '', '', $groups, $notifyexcludeusers, false, false, true);
1597     if (empty($userstonotify) && !$sendconfirm) {
1598         return true; // Nothing to do.
1599     }
1601     $a = new stdClass();
1602     // Course info.
1603     $a->coursename      = $course->fullname;
1604     $a->courseshortname = $course->shortname;
1605     // Quiz info.
1606     $a->quizname        = $quiz->name;
1607     $a->quizreporturl   = $CFG->wwwroot . '/mod/quiz/report.php?id=' . $cm->id;
1608     $a->quizreportlink  = '<a href="' . $a->quizreporturl . '">' .
1609             format_string($quiz->name) . ' report</a>';
1610     $a->quizurl         = $CFG->wwwroot . '/mod/quiz/view.php?id=' . $cm->id;
1611     $a->quizlink        = '<a href="' . $a->quizurl . '">' . format_string($quiz->name) . '</a>';
1612     // Attempt info.
1613     $a->submissiontime  = userdate($attempt->timefinish);
1614     $a->timetaken       = format_time($attempt->timefinish - $attempt->timestart);
1615     $a->quizreviewurl   = $CFG->wwwroot . '/mod/quiz/review.php?attempt=' . $attempt->id;
1616     $a->quizreviewlink  = '<a href="' . $a->quizreviewurl . '">' .
1617             format_string($quiz->name) . ' review</a>';
1618     // Student who sat the quiz info.
1619     $a->studentidnumber = $submitter->idnumber;
1620     $a->studentname     = fullname($submitter);
1621     $a->studentusername = $submitter->username;
1623     $allok = true;
1625     // Send notifications if required.
1626     if (!empty($userstonotify)) {
1627         foreach ($userstonotify as $recipient) {
1628             $allok = $allok && quiz_send_notification($recipient, $submitter, $a);
1629         }
1630     }
1632     // Send confirmation if required. We send the student confirmation last, so
1633     // that if message sending is being intermittently buggy, which means we send
1634     // some but not all messages, and then try again later, then teachers may get
1635     // duplicate messages, but the student will always get exactly one.
1636     if ($sendconfirm) {
1637         $allok = $allok && quiz_send_confirmation($submitter, $a);
1638     }
1640     return $allok;
1643 /**
1644  * Send the notification message when a quiz attempt becomes overdue.
1645  *
1646  * @param object $course the course
1647  * @param object $quiz the quiz
1648  * @param object $attempt this attempt just finished
1649  * @param object $context the quiz context
1650  * @param object $cm the coursemodule for this quiz
1651  */
1652 function quiz_send_overdue_message($course, $quiz, $attempt, $context, $cm) {
1653     global $CFG, $DB;
1655     // Do nothing if required objects not present.
1656     if (empty($course) or empty($quiz) or empty($attempt) or empty($context)) {
1657         throw new coding_exception('$course, $quiz, $attempt, $context and $cm must all be set.');
1658     }
1660     $submitter = $DB->get_record('user', array('id' => $attempt->userid), '*', MUST_EXIST);
1662     if (!has_capability('mod/quiz:emailwarnoverdue', $context, $submitter, false)) {
1663         return; // Message not required.
1664     }
1666     // Prepare lots of useful information that admins might want to include in
1667     // the email message.
1668     $quizname = format_string($quiz->name);
1670     $deadlines = array();
1671     if ($quiz->timelimit) {
1672         $deadlines[] = $attempt->timestart + $quiz->timelimit;
1673     }
1674     if ($quiz->timeclose) {
1675         $deadlines[] = $quiz->timeclose;
1676     }
1677     $duedate = min($deadlines);
1678     $graceend = $duedate + $quiz->graceperiod;
1680     $a = new stdClass();
1681     // Course info.
1682     $a->coursename         = $course->fullname;
1683     $a->courseshortname    = $course->shortname;
1684     // Quiz info.
1685     $a->quizname           = $quizname;
1686     $a->quizurl            = $CFG->wwwroot . '/mod/quiz/view.php?id=' . $cm->id;
1687     $a->quizlink           = '<a href="' . $a->quizurl . '">' . $quizname . '</a>';
1688     // Attempt info.
1689     $a->attemptduedate    = userdate($duedate);
1690     $a->attemptgraceend    = userdate($graceend);
1691     $a->attemptsummaryurl  = $CFG->wwwroot . '/mod/quiz/summary.php?attempt=' . $attempt->id;
1692     $a->attemptsummarylink = '<a href="' . $a->attemptsummaryurl . '">' . $quizname . ' review</a>';
1693     // Student's info.
1694     $a->studentidnumber    = $submitter->idnumber;
1695     $a->studentname        = fullname($submitter);
1696     $a->studentusername    = $submitter->username;
1698     // Prepare the message.
1699     $eventdata = new stdClass();
1700     $eventdata->component         = 'mod_quiz';
1701     $eventdata->name              = 'attempt_overdue';
1702     $eventdata->notification      = 1;
1704     $eventdata->userfrom          = get_admin();
1705     $eventdata->userto            = $submitter;
1706     $eventdata->subject           = get_string('emailoverduesubject', 'quiz', $a);
1707     $eventdata->fullmessage       = get_string('emailoverduebody', 'quiz', $a);
1708     $eventdata->fullmessageformat = FORMAT_PLAIN;
1709     $eventdata->fullmessagehtml   = '';
1711     $eventdata->smallmessage      = get_string('emailoverduesmall', 'quiz', $a);
1712     $eventdata->contexturl        = $a->quizurl;
1713     $eventdata->contexturlname    = $a->quizname;
1715     // Send the message.
1716     return message_send($eventdata);
1719 /**
1720  * Handle the quiz_attempt_submitted event.
1721  *
1722  * This sends the confirmation and notification messages, if required.
1723  *
1724  * @param object $event the event object.
1725  */
1726 function quiz_attempt_submitted_handler($event) {
1727     global $DB;
1729     $course  = $DB->get_record('course', array('id' => $event->courseid));
1730     $quiz    = $DB->get_record('quiz', array('id' => $event->quizid));
1731     $cm      = get_coursemodule_from_id('quiz', $event->cmid, $event->courseid);
1732     $attempt = $DB->get_record('quiz_attempts', array('id' => $event->attemptid));
1734     if (!($course && $quiz && $cm && $attempt)) {
1735         // Something has been deleted since the event was raised. Therefore, the
1736         // event is no longer relevant.
1737         return true;
1738     }
1740     return quiz_send_notification_messages($course, $quiz, $attempt,
1741             context_module::instance($cm->id), $cm);
1744 /**
1745  * Handle the quiz_attempt_overdue event.
1746  *
1747  * For quizzes with applicable settings, this sends a message to the user, reminding
1748  * them that they forgot to submit, and that they have another chance to do so.
1749  *
1750  * @param object $event the event object.
1751  */
1752 function quiz_attempt_overdue_handler($event) {
1753     global $DB;
1755     $course  = $DB->get_record('course', array('id' => $event->courseid));
1756     $quiz    = $DB->get_record('quiz', array('id' => $event->quizid));
1757     $cm      = get_coursemodule_from_id('quiz', $event->cmid, $event->courseid);
1758     $attempt = $DB->get_record('quiz_attempts', array('id' => $event->attemptid));
1760     if (!($course && $quiz && $cm && $attempt)) {
1761         // Something has been deleted since the event was raised. Therefore, the
1762         // event is no longer relevant.
1763         return true;
1764     }
1766     return quiz_send_overdue_message($course, $quiz, $attempt,
1767             context_module::instance($cm->id), $cm);
1770 /**
1771  * Handle groups_member_added event
1772  *
1773  * @param object $event the event object.
1774  */
1775 function quiz_groups_member_added_handler($event) {
1776     quiz_update_open_attempts(array('userid'=>$event->userid, 'groupid'=>$event->groupid));
1779 /**
1780  * Handle groups_member_removed event
1781  *
1782  * @param object $event the event object.
1783  */
1784 function quiz_groups_member_removed_handler($event) {
1785     quiz_update_open_attempts(array('userid'=>$event->userid, 'groupid'=>$event->groupid));
1788 /**
1789  * Handle groups_group_deleted event
1790  *
1791  * @param object $event the event object.
1792  */
1793 function quiz_groups_group_deleted_handler($event) {
1794     global $DB;
1796     // It would be nice if we got the groupid that was deleted.
1797     // Instead, we just update all quizzes with orphaned group overrides
1798     $sql = "SELECT o.id, o.quiz
1799               FROM {quiz_overrides} o
1800               JOIN {quiz} quiz ON quiz.id = o.quiz
1801          LEFT JOIN {groups} grp ON grp.id = o.groupid
1802              WHERE quiz.course = :courseid AND grp.id IS NULL";
1803     $params = array('courseid'=>$event->courseid);
1804     $records = $DB->get_records_sql_menu($sql, $params);
1805     if (!$records) {
1806         return; // Nothing to do.
1807     }
1808     $DB->delete_records_list('quiz_overrides', 'id', array_keys($records));
1809     quiz_update_open_attempts(array('quizid'=>array_unique(array_values($records))));
1812 /**
1813  * Handle groups_members_removed event
1814  *
1815  * @param object $event the event object.
1816  */
1817 function quiz_groups_members_removed_handler($event) {
1818     if ($event->userid == 0) {
1819         quiz_update_open_attempts(array('courseid'=>$event->courseid));
1820     } else {
1821         quiz_update_open_attempts(array('courseid'=>$event->courseid, 'userid'=>$event->userid));
1822     }
1825 /**
1826  * Get the information about the standard quiz JavaScript module.
1827  * @return array a standard jsmodule structure.
1828  */
1829 function quiz_get_js_module() {
1830     global $PAGE;
1832     return array(
1833         'name' => 'mod_quiz',
1834         'fullpath' => '/mod/quiz/module.js',
1835         'requires' => array('base', 'dom', 'event-delegate', 'event-key',
1836                 'core_question_engine', 'moodle-core-formchangechecker'),
1837         'strings' => array(
1838             array('cancel', 'moodle'),
1839             array('flagged', 'question'),
1840             array('functiondisabledbysecuremode', 'quiz'),
1841             array('startattempt', 'quiz'),
1842             array('timesup', 'quiz'),
1843             array('changesmadereallygoaway', 'moodle'),
1844         ),
1845     );
1849 /**
1850  * An extension of question_display_options that includes the extra options used
1851  * by the quiz.
1852  *
1853  * @copyright  2010 The Open University
1854  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1855  */
1856 class mod_quiz_display_options extends question_display_options {
1857     /**#@+
1858      * @var integer bits used to indicate various times in relation to a
1859      * quiz attempt.
1860      */
1861     const DURING =            0x10000;
1862     const IMMEDIATELY_AFTER = 0x01000;
1863     const LATER_WHILE_OPEN =  0x00100;
1864     const AFTER_CLOSE =       0x00010;
1865     /**#@-*/
1867     /**
1868      * @var boolean if this is false, then the student is not allowed to review
1869      * anything about the attempt.
1870      */
1871     public $attempt = true;
1873     /**
1874      * @var boolean if this is false, then the student is not allowed to review
1875      * anything about the attempt.
1876      */
1877     public $overallfeedback = self::VISIBLE;
1879     /**
1880      * Set up the various options from the quiz settings, and a time constant.
1881      * @param object $quiz the quiz settings.
1882      * @param int $one of the {@link DURING}, {@link IMMEDIATELY_AFTER},
1883      * {@link LATER_WHILE_OPEN} or {@link AFTER_CLOSE} constants.
1884      * @return mod_quiz_display_options set up appropriately.
1885      */
1886     public static function make_from_quiz($quiz, $when) {
1887         $options = new self();
1889         $options->attempt = self::extract($quiz->reviewattempt, $when, true, false);
1890         $options->correctness = self::extract($quiz->reviewcorrectness, $when);
1891         $options->marks = self::extract($quiz->reviewmarks, $when,
1892                 self::MARK_AND_MAX, self::MAX_ONLY);
1893         $options->feedback = self::extract($quiz->reviewspecificfeedback, $when);
1894         $options->generalfeedback = self::extract($quiz->reviewgeneralfeedback, $when);
1895         $options->rightanswer = self::extract($quiz->reviewrightanswer, $when);
1896         $options->overallfeedback = self::extract($quiz->reviewoverallfeedback, $when);
1898         $options->numpartscorrect = $options->feedback;
1900         if ($quiz->questiondecimalpoints != -1) {
1901             $options->markdp = $quiz->questiondecimalpoints;
1902         } else {
1903             $options->markdp = $quiz->decimalpoints;
1904         }
1906         return $options;
1907     }
1909     protected static function extract($bitmask, $bit,
1910             $whenset = self::VISIBLE, $whennotset = self::HIDDEN) {
1911         if ($bitmask & $bit) {
1912             return $whenset;
1913         } else {
1914             return $whennotset;
1915         }
1916     }
1920 /**
1921  * A {@link qubaid_condition} for finding all the question usages belonging to
1922  * a particular quiz.
1923  *
1924  * @copyright  2010 The Open University
1925  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1926  */
1927 class qubaids_for_quiz extends qubaid_join {
1928     public function __construct($quizid, $includepreviews = true, $onlyfinished = false) {
1929         $where = 'quiza.quiz = :quizaquiz';
1930         $params = array('quizaquiz' => $quizid);
1932         if (!$includepreviews) {
1933             $where .= ' AND preview = 0';
1934         }
1936         if ($onlyfinished) {
1937             $where .= ' AND state == :statefinished';
1938             $params['statefinished'] = quiz_attempt::FINISHED;
1939         }
1941         parent::__construct('{quiz_attempts} quiza', 'quiza.uniqueid', $where, $params);
1942     }