3 * Library of functions used by the quiz module.
5 * This contains functions that are called from within the quiz module only
6 * Functions that are also called by core Moodle are in {@link lib.php}
7 * This script also loads the code in {@link questionlib.php} which holds
8 * the module-indpendent code for handling questions and which in turn
9 * initialises all the questiontype classes.
11 * @author Martin Dougiamas and many others. This has recently been completely
12 * rewritten by Alex Smith, Julian Sedding and Gustav Delius as part of
13 * the Serving Mathematics project
14 * {@link http://maths.york.ac.uk/serving_maths}
15 * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
20 * Include those library functions that are also used by core Moodle or other modules
22 require_once($CFG->dirroot
. '/mod/quiz/lib.php');
23 require_once($CFG->dirroot
. '/question/editlib.php');
25 /// Constants ///////////////////////////////////////////////////////////////////
28 * Options determining how the grades from individual attempts are combined to give
29 * the overall grade for a user
31 define("QUIZ_GRADEHIGHEST", "1");
32 define("QUIZ_GRADEAVERAGE", "2");
33 define("QUIZ_ATTEMPTFIRST", "3");
34 define("QUIZ_ATTEMPTLAST", "4");
38 * Constants to describe the various states a quiz attempt can be in.
40 define('QUIZ_STATE_DURING', 'during');
41 define('QUIZ_STATE_IMMEDIATELY', 'immedately');
42 define('QUIZ_STATE_OPEN', 'open');
43 define('QUIZ_STATE_CLOSED', 'closed');
44 define('QUIZ_STATE_TEACHERACCESS', 'teacheraccess'); // State only relevant if you are in a studenty role.
47 /// Functions related to attempts /////////////////////////////////////////
50 * Creates an object to represent a new attempt at a quiz
52 * Creates an attempt object to represent an attempt at the quiz by the current
53 * user starting at the current time. The ->id field is not set. The object is
54 * NOT written to the database.
55 * @return object The newly created attempt object.
56 * @param object $quiz The quiz to create an attempt for.
57 * @param integer $attemptnumber The sequence number for the attempt.
59 function quiz_create_attempt($quiz, $attemptnumber) {
62 if (!$attemptnumber > 1 or !$quiz->attemptonlast
or !$attempt = get_record('quiz_attempts', 'quiz', $quiz->id
, 'userid', $USER->id
, 'attempt', $attemptnumber-1)) {
63 // we are not building on last attempt so create a new attempt
64 $attempt->quiz
= $quiz->id
;
65 $attempt->userid
= $USER->id
;
66 $attempt->preview
= 0;
67 if ($quiz->shufflequestions
) {
68 $attempt->layout
= quiz_repaginate($quiz->questions
, $quiz->questionsperpage
, true);
70 $attempt->layout
= $quiz->questions
;
75 $attempt->attempt
= $attemptnumber;
76 $attempt->sumgrades
= 0.0;
77 $attempt->timestart
= $timenow;
78 $attempt->timefinish
= 0;
79 $attempt->timemodified
= $timenow;
80 $attempt->uniqueid
= question_new_attempt_uniqueid();
86 * Returns an unfinished attempt (if there is one) for the given
87 * user on the given quiz. This function does not return preview attempts.
89 * @param integer $quizid the id of the quiz.
90 * @param integer $userid the id of the user.
92 * @return mixed the unfinished attempt if there is one, false if not.
94 function quiz_get_user_attempt_unfinished($quizid, $userid) {
95 $attempts = quiz_get_user_attempts($quizid, $userid, 'unfinished', true);
97 return array_shift($attempts);
104 * Delete a quiz attempt.
106 function quiz_delete_attempt($attempt, $quiz) {
107 if (is_numeric($attempt)) {
108 if (!$attempt = get_record('quiz_attempts', 'id', $attempt)) {
113 if ($attempt->quiz
!= $quiz->id
) {
114 debugging("Trying to delete attempt $attempt->id which belongs to quiz $attempt->quiz " .
115 "but was passed quiz $quiz->id.");
119 delete_records('quiz_attempts', 'id', $attempt->id
);
120 delete_attempt($attempt->uniqueid
);
122 // Search quiz_attempts for other instances by this user.
123 // If none, then delete record for this quiz, this user from quiz_grades
124 // else recalculate best grade
126 $userid = $attempt->userid
;
127 if (!record_exists('quiz_attempts', 'userid', $userid, 'quiz', $quiz->id
)) {
128 delete_records('quiz_grades', 'userid', $userid,'quiz', $quiz->id
);
130 quiz_save_best_grade($quiz, $userid);
133 quiz_update_grades($quiz, $userid);
136 /// Functions to do with quiz layout and pages ////////////////////////////////
139 * Returns a comma separated list of question ids for the current page
141 * @return string Comma separated list of question ids
142 * @param string $layout The string representing the quiz layout. Each page is represented as a
143 * comma separated list of question ids and 0 indicating page breaks.
144 * So 5,2,0,3,0 means questions 5 and 2 on page 1 and question 3 on page 2
145 * @param integer $page The number of the current page.
147 function quiz_questions_on_page($layout, $page) {
148 $pages = explode(',0', $layout);
149 return trim($pages[$page], ',');
153 * Returns a comma separated list of question ids for the quiz
155 * @return string Comma separated list of question ids
156 * @param string $layout The string representing the quiz layout. Each page is represented as a
157 * comma separated list of question ids and 0 indicating page breaks.
158 * So 5,2,0,3,0 means questions 5 and 2 on page 1 and question 3 on page 2
160 function quiz_questions_in_quiz($layout) {
161 return str_replace(',0', '', $layout);
165 * Returns the number of pages in the quiz layout
167 * @return integer Comma separated list of question ids
168 * @param string $layout The string representing the quiz layout.
170 function quiz_number_of_pages($layout) {
171 return substr_count($layout, ',0');
175 * Returns the first question number for the current quiz page
177 * @return integer The number of the first question
178 * @param string $quizlayout The string representing the layout for the whole quiz
179 * @param string $pagelayout The string representing the layout for the current page
181 function quiz_first_questionnumber($quizlayout, $pagelayout) {
182 // this works by finding all the questions from the quizlayout that
183 // come before the current page and then adding up their lengths.
185 $start = strpos($quizlayout, ','.$pagelayout.',')-2;
187 $prevlist = substr($quizlayout, 0, $start);
188 return get_field_sql("SELECT sum(length)+1 FROM {$CFG->prefix}question
189 WHERE id IN ($prevlist)");
196 * Re-paginates the quiz layout
198 * @return string The new layout string
199 * @param string $layout The string representing the quiz layout.
200 * @param integer $perpage The number of questions per page
201 * @param boolean $shuffle Should the questions be reordered randomly?
203 function quiz_repaginate($layout, $perpage, $shuffle=false) {
204 $layout = str_replace(',0', '', $layout); // remove existing page breaks
205 $questions = explode(',', $layout);
207 srand((float)microtime() * 1000000); // for php < 4.2
212 foreach ($questions as $question) {
213 if ($perpage and $i > $perpage) {
217 $layout .= $question.',';
224 * Print navigation panel for quiz attempt and review pages
226 * @param integer $page The number of the current page (counting from 0).
227 * @param integer $pages The total number of pages.
229 function quiz_print_navigation_panel($page, $pages) {
231 echo '<div class="pagingbar">';
232 echo '<span class="title">' . get_string('page') . ':</span>';
234 // Print previous link
235 $strprev = get_string('previous');
236 echo '<a href="javascript:navigate(' . ($page - 1) . ');" title="'
237 . $strprev . '">(' . $strprev . ')</a>';
239 for ($i = 0; $i < $pages; $i++
) {
241 echo '<span class="thispage">'.($i+
1).'</span>';
243 echo '<a href="javascript:navigate(' . ($i) . ');">'.($i+
1).'</a>';
247 if ($page < $pages - 1) {
249 $strnext = get_string('next');
250 echo '<a href="javascript:navigate(' . ($page +
1) . ');" title="'
251 . $strnext . '">(' . $strnext . ')</a>';
256 /// Functions to do with quiz grades //////////////////////////////////////////
259 * Creates an array of maximum grades for a quiz
261 * The grades are extracted from the quiz_question_instances table.
262 * @return array Array of grades indexed by question id
263 * These are the maximum possible grades that
264 * students can achieve for each of the questions
265 * @param integer $quiz The quiz object
267 function quiz_get_all_question_grades($quiz) {
270 $questionlist = quiz_questions_in_quiz($quiz->questions
);
271 if (empty($questionlist)) {
275 $instances = get_records_sql("SELECT question,grade,id
276 FROM {$CFG->prefix}quiz_question_instances
277 WHERE quiz = '$quiz->id'" .
278 (is_null($questionlist) ?
'' :
279 "AND question IN ($questionlist)"));
281 $list = explode(",", $questionlist);
284 foreach ($list as $qid) {
285 if (isset($instances[$qid])) {
286 $grades[$qid] = $instances[$qid]->grade
;
295 * Get the best current grade for a particular user in a quiz.
297 * @param object $quiz the quiz object.
298 * @param integer $userid the id of the user.
299 * @return float the user's current grade for this quiz.
301 function quiz_get_best_grade($quiz, $userid) {
302 $grade = get_field('quiz_grades', 'grade', 'quiz', $quiz->id
, 'userid', $userid);
304 // Need to detect errors/no result, without catching 0 scores.
305 if (is_numeric($grade)) {
306 return round($grade,$quiz->decimalpoints
);
313 * Convert the raw grade stored in $attempt into a grade out of the maximum
314 * grade for this quiz.
316 * @param float $rawgrade the unadjusted grade, fof example $attempt->sumgrades
317 * @param object $quiz the quiz object. Only the fields grade, sumgrades and decimalpoints are used.
318 * @return float the rescaled grade.
320 function quiz_rescale_grade($rawgrade, $quiz) {
321 if ($quiz->sumgrades
) {
322 return round($rawgrade*$quiz->grade
/$quiz->sumgrades
, $quiz->decimalpoints
);
329 * Get the feedback text that should be show to a student who
330 * got this grade on this quiz. The feedback is processed ready for diplay.
332 * @param float $grade a grade on this quiz.
333 * @param integer $quizid the id of the quiz object.
334 * @return string the comment that corresponds to this grade (empty string if there is not one.
336 function quiz_feedback_for_grade($grade, $quizid) {
337 $feedback = get_field_select('quiz_feedback', 'feedbacktext',
338 "quizid = $quizid AND mingrade <= $grade AND $grade < maxgrade");
340 if (empty($feedback)) {
344 // Clean the text, ready for display.
345 $formatoptions = new stdClass
;
346 $formatoptions->noclean
= true;
347 $feedback = format_text($feedback, FORMAT_MOODLE
, $formatoptions);
353 * @param integer $quizid the id of the quiz object.
354 * @return boolean Whether this quiz has any non-blank feedback text.
356 function quiz_has_feedback($quizid) {
357 static $cache = array();
358 if (!array_key_exists($quizid, $cache)) {
359 $cache[$quizid] = record_exists_select('quiz_feedback',
360 "quizid = $quizid AND feedbacktext <> ''");
362 return $cache[$quizid];
366 * The quiz grade is the score that student's results are marked out of. When it
367 * changes, the corresponding data in quiz_grades and quiz_feedback needs to be
370 * @param float $newgrade the new maximum grade for the quiz.
371 * @param object $quiz the quiz we are updating. Passed by reference so its grade field can be updated too.
372 * @return boolean indicating success or failure.
374 function quiz_set_grade($newgrade, &$quiz) {
375 // This is potentially expensive, so only do it if necessary.
376 if (abs($quiz->grade
- $newgrade) < 1e-7) {
381 // Use a transaction, so that on those databases that support it, this is safer.
384 // Update the quiz table.
385 $success = set_field('quiz', 'grade', $newgrade, 'id', $quiz->instance
);
387 // Rescaling the other data is only possible if the old grade was non-zero.
388 if ($quiz->grade
> 1e-7) {
391 $factor = $newgrade/$quiz->grade
;
392 $quiz->grade
= $newgrade;
394 // Update the quiz_grades table.
395 $timemodified = time();
396 $success = $success && execute_sql("
397 UPDATE {$CFG->prefix}quiz_grades
398 SET grade = $factor * grade, timemodified = $timemodified
399 WHERE quiz = $quiz->id
402 // Update the quiz_grades table.
403 $success = $success && execute_sql("
404 UPDATE {$CFG->prefix}quiz_feedback
405 SET mingrade = $factor * mingrade, maxgrade = $factor * maxgrade
406 WHERE quizid = $quiz->id
410 // update grade item and send all grades to gradebook
411 quiz_grade_item_update($quiz);
412 quiz_update_grades($quiz);
423 * Save the overall grade for a user at a quiz in the quiz_grades table
425 * @param object $quiz The quiz for which the best grade is to be calculated and then saved.
426 * @param integer $userid The userid to calculate the grade for. Defaults to the current user.
427 * @return boolean Indicates success or failure.
429 function quiz_save_best_grade($quiz, $userid = null) {
432 if (empty($userid)) {
436 // Get all the attempts made by the user
437 if (!$attempts = quiz_get_user_attempts($quiz->id
, $userid)) {
438 notify('Could not find any user attempts');
442 // Calculate the best grade
443 $bestgrade = quiz_calculate_best_grade($quiz, $attempts);
444 $bestgrade = quiz_rescale_grade($bestgrade, $quiz);
446 // Save the best grade in the database
447 if ($grade = get_record('quiz_grades', 'quiz', $quiz->id
, 'userid', $userid)) {
448 $grade->grade
= $bestgrade;
449 $grade->timemodified
= time();
450 if (!update_record('quiz_grades', $grade)) {
451 notify('Could not update best grade');
455 $grade->quiz
= $quiz->id
;
456 $grade->userid
= $userid;
457 $grade->grade
= $bestgrade;
458 $grade->timemodified
= time();
459 if (!insert_record('quiz_grades', $grade)) {
460 notify('Could not insert new best grade');
465 quiz_update_grades($quiz, $userid);
470 * Calculate the overall grade for a quiz given a number of attempts by a particular user.
472 * @return float The overall grade
473 * @param object $quiz The quiz for which the best grade is to be calculated
474 * @param array $attempts An array of all the attempts of the user at the quiz
476 function quiz_calculate_best_grade($quiz, $attempts) {
478 switch ($quiz->grademethod
) {
480 case QUIZ_ATTEMPTFIRST
:
481 foreach ($attempts as $attempt) {
482 return $attempt->sumgrades
;
486 case QUIZ_ATTEMPTLAST
:
487 foreach ($attempts as $attempt) {
488 $final = $attempt->sumgrades
;
492 case QUIZ_GRADEAVERAGE
:
495 foreach ($attempts as $attempt) {
496 $sum +
= $attempt->sumgrades
;
499 return (float)$sum/$count;
502 case QUIZ_GRADEHIGHEST
:
504 foreach ($attempts as $attempt) {
505 if ($attempt->sumgrades
> $max) {
506 $max = $attempt->sumgrades
;
514 * Return the attempt with the best grade for a quiz
516 * Which attempt is the best depends on $quiz->grademethod. If the grade
517 * method is GRADEAVERAGE then this function simply returns the last attempt.
518 * @return object The attempt with the best grade
519 * @param object $quiz The quiz for which the best grade is to be calculated
520 * @param array $attempts An array of all the attempts of the user at the quiz
522 function quiz_calculate_best_attempt($quiz, $attempts) {
524 switch ($quiz->grademethod
) {
526 case QUIZ_ATTEMPTFIRST
:
527 foreach ($attempts as $attempt) {
532 case QUIZ_GRADEAVERAGE
: // need to do something with it :-)
533 case QUIZ_ATTEMPTLAST
:
534 foreach ($attempts as $attempt) {
540 case QUIZ_GRADEHIGHEST
:
542 foreach ($attempts as $attempt) {
543 if ($attempt->sumgrades
> $max) {
544 $max = $attempt->sumgrades
;
545 $maxattempt = $attempt;
553 * @return the options for calculating the quiz grade from the individual attempt grades.
555 function quiz_get_grading_options() {
557 QUIZ_GRADEHIGHEST
=> get_string('gradehighest', 'quiz'),
558 QUIZ_GRADEAVERAGE
=> get_string('gradeaverage', 'quiz'),
559 QUIZ_ATTEMPTFIRST
=> get_string('attemptfirst', 'quiz'),
560 QUIZ_ATTEMPTLAST
=> get_string('attemptlast', 'quiz'));
564 * @param int $option one of the values QUIZ_GRADEHIGHEST, QUIZ_GRADEAVERAGE, QUIZ_ATTEMPTFIRST or QUIZ_ATTEMPTLAST.
565 * @return the lang string for that option.
567 function quiz_get_grading_option_name($option) {
568 $strings = quiz_get_grading_options();
569 return $strings[$option];
572 /// Other quiz functions ////////////////////////////////////////////////////
575 * Print a box with quiz start and due dates
577 * @param object $quiz
579 function quiz_view_dates($quiz) {
580 if (!$quiz->timeopen
&& !$quiz->timeclose
) {
584 print_simple_box_start('center', '', '', '', 'generalbox', 'dates');
586 if ($quiz->timeopen
) {
587 echo '<tr><td class="c0">'.get_string("quizopen", "quiz").':</td>';
588 echo ' <td class="c1">'.userdate($quiz->timeopen
).'</td></tr>';
590 if ($quiz->timeclose
) {
591 echo '<tr><td class="c0">'.get_string("quizclose", "quiz").':</td>';
592 echo ' <td class="c1">'.userdate($quiz->timeclose
).'</td></tr>';
595 print_simple_box_end();
599 * Parse field names used for the replace options on question edit forms
601 function quiz_parse_fieldname($name, $nameprefix='question') {
603 if (preg_match("/$nameprefix(\\d+)(\w+)/", $name, $reg)) {
604 return array('mode' => $reg[2], 'id' => (int)$reg[1]);
611 * Upgrade states for an attempt to Moodle 1.5 model
613 * Any state that does not yet have its timestamp set to nonzero has not yet been upgraded from Moodle 1.4
614 * The reason these are still around is that for large sites it would have taken too long to
615 * upgrade all states at once. This function sets the timestamp field and creates an entry in the
616 * question_sessions table.
617 * @param object $attempt The attempt whose states need upgrading
619 function quiz_upgrade_states($attempt) {
621 // The old quiz model only allowed a single response per quiz attempt so that there will be
622 // only one state record per question for this attempt.
624 // We set the timestamp of all states to the timemodified field of the attempt.
625 execute_sql("UPDATE {$CFG->prefix}question_states SET timestamp = '$attempt->timemodified' WHERE attempt = '$attempt->uniqueid'", false);
627 // For each state we create an entry in the question_sessions table, with both newest and
628 // newgraded pointing to this state.
629 // Actually we only do this for states whose question is actually listed in $attempt->layout.
630 // We do not do it for states associated to wrapped questions like for example the questions
631 // used by a RANDOM question
632 $session = new stdClass
;
633 $session->attemptid
= $attempt->uniqueid
;
634 $questionlist = quiz_questions_in_quiz($attempt->layout
);
635 if ($questionlist and $states = get_records_select('question_states', "attempt = '$attempt->uniqueid' AND question IN ($questionlist)")) {
636 foreach ($states as $state) {
637 $session->newgraded
= $state->id
;
638 $session->newest
= $state->id
;
639 $session->questionid
= $state->question
;
640 insert_record('question_sessions', $session, false);
646 * @param object $quiz the quiz
647 * @param object $question the question
648 * @return the HTML for a preview question icon.
650 function quiz_question_preview_button($quiz, $question) {
651 global $CFG, $COURSE;
652 if (!question_has_capability_on($question, 'use', $question->category
)){
655 $strpreview = get_string('previewquestion', 'quiz');
656 $quizorcourseid = $quiz->id?
('&quizid=' . $quiz->id
):('&courseid=' .$COURSE->id
);
657 return link_to_popup_window('/question/preview.php?id=' . $question->id
. $quizorcourseid, 'questionpreview',
658 "<img src=\"$CFG->pixpath/t/preview.gif\" class=\"iconsmall\" alt=\"$strpreview\" />",
659 0, 0, $strpreview, QUESTION_PREVIEW_POPUP_OPTIONS
, true);
663 * Determine render options
665 * @param int $reviewoptions
666 * @param object $state
668 function quiz_get_renderoptions($reviewoptions, $state) {
669 $options = new stdClass
;
671 // Show the question in readonly (review) mode if the question is in
673 $options->readonly
= question_state_is_closed($state);
675 // Show feedback once the question has been graded (if allowed by the quiz)
676 $options->feedback
= question_state_is_graded($state) && ($reviewoptions & QUIZ_REVIEW_FEEDBACK
& QUIZ_REVIEW_IMMEDIATELY
);
678 // Show validation only after a validation event
679 $options->validation
= QUESTION_EVENTVALIDATE
=== $state->event
;
681 // Show correct responses in readonly mode if the quiz allows it
682 $options->correct_responses
= $options->readonly
&& ($reviewoptions & QUIZ_REVIEW_ANSWERS
& QUIZ_REVIEW_IMMEDIATELY
);
684 // Show general feedback if the question has been graded and the quiz allows it.
685 $options->generalfeedback
= question_state_is_graded($state) && ($reviewoptions & QUIZ_REVIEW_GENERALFEEDBACK
& QUIZ_REVIEW_IMMEDIATELY
);
687 // Show overallfeedback once the attempt is over.
688 $options->overallfeedback
= false;
690 // Always show responses and scores
691 $options->responses
= true;
692 $options->scores
= true;
693 $options->quizstate
= QUIZ_STATE_DURING
;
699 * Determine review options
701 * @param object $quiz the quiz instance.
702 * @param object $attempt the attempt in question.
703 * @param $context the roles and permissions context,
704 * normally the context for the quiz module instance.
706 * @return object an object with boolean fields responses, scores, feedback,
707 * correct_responses, solutions and general feedback
709 function quiz_get_reviewoptions($quiz, $attempt, $context=null) {
711 $options = new stdClass
;
712 $options->readonly
= true;
713 // Provide the links to the question review and comment script
714 $options->questionreviewlink
= '/mod/quiz/reviewquestion.php';
716 if ($context && has_capability('mod/quiz:viewreports', $context) and !$attempt->preview
) {
717 // The teacher should be shown everything except during preview when the teachers
718 // wants to see just what the students see
719 $options->responses
= true;
720 $options->scores
= true;
721 $options->feedback
= true;
722 $options->correct_responses
= true;
723 $options->solutions
= false;
724 $options->generalfeedback
= true;
725 $options->overallfeedback
= true;
726 $options->quizstate
= QUIZ_STATE_TEACHERACCESS
;
728 // Show a link to the comment box only for closed attempts
729 if ($attempt->timefinish
) {
730 $options->questioncommentlink
= '/mod/quiz/comment.php';
733 if (((time() - $attempt->timefinish
) < 120) ||
$attempt->timefinish
==0) {
734 $quiz_state_mask = QUIZ_REVIEW_IMMEDIATELY
;
735 $options->quizstate
= QUIZ_STATE_IMMEDIATELY
;
736 } else if (!$quiz->timeclose
or time() < $quiz->timeclose
) {
737 $quiz_state_mask = QUIZ_REVIEW_OPEN
;
738 $options->quizstate
= QUIZ_STATE_OPEN
;
740 $quiz_state_mask = QUIZ_REVIEW_CLOSED
;
741 $options->quizstate
= QUIZ_STATE_CLOSED
;
743 $options->responses
= ($quiz->review
& $quiz_state_mask & QUIZ_REVIEW_RESPONSES
) ?
1 : 0;
744 $options->scores
= ($quiz->review
& $quiz_state_mask & QUIZ_REVIEW_SCORES
) ?
1 : 0;
745 $options->feedback
= ($quiz->review
& $quiz_state_mask & QUIZ_REVIEW_FEEDBACK
) ?
1 : 0;
746 $options->correct_responses
= ($quiz->review
& $quiz_state_mask & QUIZ_REVIEW_ANSWERS
) ?
1 : 0;
747 $options->solutions
= ($quiz->review
& $quiz_state_mask & QUIZ_REVIEW_SOLUTIONS
) ?
1 : 0;
748 $options->generalfeedback
= ($quiz->review
& $quiz_state_mask & QUIZ_REVIEW_GENERALFEEDBACK
) ?
1 : 0;
749 $options->overallfeedback
= $attempt->timefinish
&& ($quiz->review
& $quiz_state_mask & QUIZ_REVIEW_OVERALLFEEDBACK
);
756 * Combines the review options from a number of different quiz attempts.
757 * Returns an array of two ojects, so he suggested way of calling this
759 * list($someoptions, $alloptions) = quiz_get_combined_reviewoptions(...)
761 * @param object $quiz the quiz instance.
762 * @param array $attempts an array of attempt objects.
763 * @param $context the roles and permissions context,
764 * normally the context for the quiz module instance.
766 * @return array of two options objects, one showing which options are true for
767 * at least one of the attempts, the other showing which options are true
770 function quiz_get_combined_reviewoptions($quiz, $attempts, $context=null) {
771 $fields = array('readonly', 'scores', 'feedback', 'correct_responses', 'solutions', 'generalfeedback', 'overallfeedback');
772 $someoptions = new stdClass
;
773 $alloptions = new stdClass
;
774 foreach ($fields as $field) {
775 $someoptions->$field = false;
776 $alloptions->$field = true;
778 foreach ($attempts as $attempt) {
779 $attemptoptions = quiz_get_reviewoptions($quiz, $attempt, $context);
780 foreach ($fields as $field) {
781 $someoptions->$field = $someoptions->$field ||
$attemptoptions->$field;
782 $alloptions->$field = $alloptions->$field && $attemptoptions->$field;
785 return array($someoptions, $alloptions);
788 /// FUNCTIONS FOR SENDING NOTIFICATION EMAILS ///////////////////////////////
791 * Sends confirmation email to the student taking the course
793 * @param stdClass $a associative array of replaceable fields for the templates
795 * @return bool|string result of email_to_user()
797 function quiz_send_confirmation($a) {
802 $a->useridnumber
= $USER->idnumber
;
803 $a->username
= fullname($USER);
804 $a->userusername
= $USER->username
;
806 // fetch the subject and body from strings
807 $subject = get_string('emailconfirmsubject', 'quiz', $a);
808 $body = get_string('emailconfirmbody', 'quiz', $a);
810 // send email and analyse result
811 return email_to_user($USER, get_admin(), $subject, $body);
815 * Sends notification email to the interested parties that assign the role capability
817 * @param object $recipient user object of the intended recipient
818 * @param stdClass $a associative array of replaceable fields for the templates
820 * @return bool|string result of email_to_user()
822 function quiz_send_notification($recipient, $a) {
826 // recipient info for template
827 $a->username
= fullname($recipient);
828 $a->userusername
= $recipient->username
;
829 $a->userusername
= $recipient->username
;
831 // fetch the subject and body from strings
832 $subject = get_string('emailnotifysubject', 'quiz', $a);
833 $body = get_string('emailnotifybody', 'quiz', $a);
835 // send email and analyse result
836 return email_to_user($recipient, $USER, $subject, $body);
840 * Takes a bunch of information to format into an email and send
841 * to the specified recipient.
843 * @param object $course the course
844 * @param object $quiz the quiz
845 * @param object $attempt this attempt just finished
846 * @param object $context the quiz context
847 * @param object $cm the coursemodule for this quiz
849 * @return int number of emails sent
851 function quiz_send_notification_emails($course, $quiz, $attempt, $context, $cm) {
853 // we will count goods and bads for error logging
854 $emailresult = array('good' => 0, 'block' => 0, 'fail' => 0);
856 // do nothing if required objects not present
857 if (empty($course) or empty($quiz) or empty($attempt) or empty($context)) {
858 debugging('quiz_send_notification_emails: Email(s) not sent due to program error.',
860 return $emailresult['fail'];
863 // check for confirmation required
864 $sendconfirm = false;
865 $notifyexcludeusers = '';
866 if (has_capability('mod/quiz:emailconfirmsubmission', $context, NULL, false)) {
867 // exclude from notify emails later
868 $notifyexcludeusers = $USER->id
;
873 // check for notifications required
874 $notifyfields = 'u.id, u.username, u.firstname, u.lastname, u.email, u.emailstop, u.lang, u.timezone, u.mailformat, u.maildisplay';
875 $userstonotify = get_users_by_capability($context, 'mod/quiz:emailnotifysubmission',
876 $notifyfields, '', '', '', array_keys(groups_get_all_groups($course->id
, $USER->id
)),
877 $notifyexcludeusers, false, false, true);
879 // if something to send, then build $a
880 if (! empty($userstonotify) or $sendconfirm) {
883 $a->coursename
= $course->fullname
;
884 $a->courseshortname
= $course->shortname
;
886 $a->quizname
= $quiz->name
;
887 $a->quizreportlink
= '<a href="report.php?q=' . $quiz->id
. '">' . format_string($quiz->name
) . ' report</a>';
888 $a->quizreporturl
= $CFG->wwwroot
. '/mod/quiz/report.php?q=' . $quiz->id
;
889 $a->quizreviewlink
= '<a href="review.php?attempt=' . $attempt->id
. '">' . format_string($quiz->name
) . ' review</a>';
890 $a->quizreviewurl
= $CFG->wwwroot
. '/mod/quiz/review.php?attempt=' . $attempt->id
;
891 $a->quizlink
= '<a href="view.php?q=' . $quiz->id
. '">' . format_string($quiz->name
) . '</a>';
892 $a->quizurl
= $CFG->wwwroot
. '/mod/quiz/view.php?q=' . $quiz->id
;
894 $a->submissiontime
= userdate($attempt->timefinish
);
895 $a->timetaken
= format_time($attempt->timefinish
- $attempt->timestart
);
896 // student who sat the quiz info
897 $a->studentidnumber
= $USER->idnumber
;
898 $a->studentname
= fullname($USER);
899 $a->studentusername
= $USER->username
;
902 // send confirmation if required
904 // send the email and update stats
905 switch (quiz_send_confirmation($a)) {
907 $emailresult['good']++
;
910 $emailresult['fail']++
;
913 $emailresult['block']++
;
918 // send notifications if required
919 if (!empty($userstonotify)) {
920 // loop through recipients and send an email to each and update stats
921 foreach ($userstonotify as $recipient) {
922 switch (quiz_send_notification($recipient, $a)) {
924 $emailresult['good']++
;
927 $emailresult['fail']++
;
930 $emailresult['block']++
;
936 // log errors sending emails if any
937 if (! empty($emailresult['fail'])) {
938 debugging('quiz_send_notification_emails:: '.$emailresult['fail'].' email(s) failed to be sent.', DEBUG_DEVELOPER
);
940 if (! empty($emailresult['block'])) {
941 debugging('quiz_send_notification_emails:: '.$emailresult['block'].' email(s) were blocked by the user.', DEBUG_DEVELOPER
);
944 // return the number of successfully sent emails
945 return $emailresult['good'];