MDL-10107 Fixed the definition of message providers ... it now works through files...
[moodle.git] / mod / quiz / lib.php
1 <?php  // $Id$
2 /**
3 * Library of functions for the quiz module.
4 *
5 * This contains functions that are called also from outside the quiz module
6 * Functions that are only called by the quiz module itself are in {@link locallib.php}
7 * @author Martin Dougiamas and many others.
8 * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
9 * @package quiz
10 */
12 require_once($CFG->libdir.'/pagelib.php');
13 require_once($CFG->libdir.'/questionlib.php');
14 require_once($CFG->libdir.'/eventslib.php');
16 /// CONSTANTS ///////////////////////////////////////////////////////////////////
18 /**#@+
19  * The different review options are stored in the bits of $quiz->review
20  * These constants help to extract the options
21  *
22  * This is more of a mess than you might think necessary, because originally
23  * it was though that 3x6 bits were enough, but then they ran out. PHP integers
24  * are only reliably 32 bits signed, so the simplest solution was then to
25  * add 4x3 more bits.
26  */
27 /**
28  * The first 6 + 4 bits refer to the time immediately after the attempt
29  */
30 define('QUIZ_REVIEW_IMMEDIATELY', 0x3c003f);
31 /**
32  * the next 6 + 4 bits refer to the time after the attempt but while the quiz is open
33  */
34 define('QUIZ_REVIEW_OPEN',       0x3c00fc0);
35 /**
36  * the final 6 + 4 bits refer to the time after the quiz closes
37  */
38 define('QUIZ_REVIEW_CLOSED',    0x3c03f000);
40 // within each group of 6 bits we determine what should be shown
41 define('QUIZ_REVIEW_RESPONSES',       1*0x1041); // Show responses
42 define('QUIZ_REVIEW_SCORES',          2*0x1041); // Show scores
43 define('QUIZ_REVIEW_FEEDBACK',        4*0x1041); // Show question feedback
44 define('QUIZ_REVIEW_ANSWERS',         8*0x1041); // Show correct answers
45 // Some handling of worked solutions is already in the code but not yet fully supported
46 // and not switched on in the user interface.
47 define('QUIZ_REVIEW_SOLUTIONS',      16*0x1041); // Show solutions
48 define('QUIZ_REVIEW_GENERALFEEDBACK',32*0x1041); // Show question general feedback
49 define('QUIZ_REVIEW_OVERALLFEEDBACK', 1*0x4440000); // Show quiz overall feedback
50 // Multipliers 2*0x4440000, 4*0x4440000 and 8*0x4440000 are still available
51 /**#@-*/
53 /**
54  * If start and end date for the quiz are more than this many seconds apart
55  * they will be represented by two separate events in the calendar
56  */
57 define("QUIZ_MAX_EVENT_LENGTH", 5*24*60*60);   // 5 days maximum
59 /// FUNCTIONS ///////////////////////////////////////////////////////////////////
61 /**
62  * Code to be executed when a module is installed
63  */ 
64 function quiz_install() {
65     return true; 
66 }
68 /**
69  * Given an object containing all the necessary data,
70  * (defined by the form in mod_form.php) this function
71  * will create a new instance and return the id number
72  * of the new instance.
73  *
74  * @param object $quiz the data that came from the form.
75  * @return mixed the id of the new instance on success,
76  *          false or a string error message on failure.
77  */
78 function quiz_add_instance($quiz) {
79     global $DB;
81     // Process the options from the form.
82     $quiz->created = time();
83     $quiz->questions = '';
84     $result = quiz_process_options($quiz);
85     if ($result && is_string($result)) {
86         return $result;
87     }
89     // Try to store it in the database.
90     if (!$quiz->id = $DB->insert_record("quiz", $quiz)) {
91         return false;
92     }
94     // Do the processing required after an add or an update.
95     quiz_after_add_or_update($quiz);
97     return $quiz->id;
98 }
100 /**
101  * Given an object containing all the necessary data,
102  * (defined by the form in mod_form.php) this function
103  * will update an existing instance with new data.
104  *
105  * @param object $quiz the data that came from the form.
106  * @return mixed true on success, false or a string error message on failure.
107  */
108 function quiz_update_instance($quiz) {
109     global $DB;
111     // Process the options from the form.
112     $result = quiz_process_options($quiz);
113     if ($result && is_string($result)) {
114         return $result;
115     }
117     // Update the database.
118     $quiz->id = $quiz->instance;
119     if (!$DB->update_record("quiz", $quiz)) {
120         return false;  // some error occurred
121     }
123     // Do the processing required after an add or an update.
124     quiz_after_add_or_update($quiz);
126     // Delete any previous preview attempts
127     $DB->delete_records('quiz_attempts', array('preview' => '1', 'quiz'=>$quiz->id));
129     return true;
133 function quiz_delete_instance($id) {
134     global $DB;
135 /// Given an ID of an instance of this module,
136 /// this function will permanently delete the instance
137 /// and any data that depends on it.
139     if (! $quiz = $DB->get_record("quiz", array("id"=>$id))) {
140         return false;
141     }
143     $result = true;
145     if ($attempts = $DB->get_records("quiz_attempts", array("quiz"=>$quiz->id))) {
146         foreach ($attempts as $attempt) {
147             // TODO: this should use the delete_attempt($attempt->uniqueid) function in questionlib.php
148             if (! $DB->delete_records("question_states", array("attempt"=>$attempt->uniqueid))) {
149                 $result = false;
150             }
151             if (! $DB->delete_records("question_sessions", array("attemptid"=>$attempt->uniqueid))) {
152                 $result = false;
153             }
154         }
155     }
157     $tables_to_purge = array(
158         'quiz_attempts' => 'quiz',
159         'quiz_grades' => 'quiz',
160         'quiz_question_instances' => 'quiz',
161         'quiz_grades' => 'quiz',
162         'quiz_feedback' => 'quizid',
163         'quiz' => 'id'
164     );
165     foreach ($tables_to_purge as $table => $keyfield) {
166         if (!$DB->delete_records($table, array($keyfield=>$quiz->id))) {
167             $result = false;
168         }
169     }
171     $pagetypes = page_import_types('mod/quiz/');
172     foreach($pagetypes as $pagetype) {
173         if (!$DB->delete_records('block_instance', array('pageid'=>$quiz->id, 'pagetype'=>$pagetype))) {
174             $result = false;
175         }
176     }
178     if ($events = $DB->get_records('event', array("modulename"=>'quiz', "instance"=>$quiz->id))) {
179         foreach($events as $event) {
180             delete_event($event->id);
181         }
182     }
184     quiz_grade_item_delete($quiz);
186     return $result;
190 function quiz_user_outline($course, $user, $mod, $quiz) {
191     global $DB;
192 /// Return a small object with summary information about what a
193 /// user has done with a given particular instance of this module
194 /// Used for user activity reports.
195 /// $return->time = the time they did it
196 /// $return->info = a short text description
197     if ($grade = $DB->get_record('quiz_grades', array('userid' => $user->id, 'quiz' => $quiz->id))) {
199         $result = new stdClass;
200         if ((float)$grade->grade) {
201             $result->info = get_string('grade').':&nbsp;'.round($grade->grade, $quiz->decimalpoints);
202         }
203         $result->time = $grade->timemodified;
204         return $result;
205     }
206     return NULL;
211 function quiz_user_complete($course, $user, $mod, $quiz) {
212     global $DB;
213 /// Print a detailed representation of what a  user has done with
214 /// a given particular instance of this module, for user activity reports.
216     if ($attempts = $DB->get_records_select('quiz_attempts', "userid=? AND quiz=?", 'attempt ASC', array($user->id, $quiz->id))) {
217         if ($quiz->grade  and $quiz->sumgrades && $grade = $DB->get_record('quiz_grades', array('userid' => $user->id, 'quiz' => $quiz->id))) {
218             echo get_string('grade').': '.round($grade->grade, $quiz->decimalpoints).'/'.$quiz->grade.'<br />';
219         }
220         foreach ($attempts as $attempt) {
221             echo get_string('attempt', 'quiz').' '.$attempt->attempt.': ';
222             if ($attempt->timefinish == 0) {
223                 print_string('unfinished');
224             } else {
225                 echo round($attempt->sumgrades, $quiz->decimalpoints).'/'.$quiz->sumgrades;
226             }
227             echo ' - '.userdate($attempt->timemodified).'<br />';
228         }
229     } else {
230        print_string('noattempts', 'quiz');
231     }
233     return true;
237 function quiz_cron () {
238 /// Function to be run periodically according to the moodle cron
239 /// This function searches for things that need to be done, such
240 /// as sending out mail, toggling flags etc ...
242     global $CFG;
244     return true;
247 /**
248  * @param integer $quizid the quiz id.
249  * @param integer $userid the userid.
250  * @param string $status 'all', 'finished' or 'unfinished' to control
251  * @return an array of all the user's attempts at this quiz. Returns an empty array if there are none.
252  */
253 function quiz_get_user_attempts($quizid, $userid=0, $status = 'finished', $includepreviews = false) {
254     global $DB;
255     $status_condition = array(
256         'all' => '',
257         'finished' => ' AND timefinish > 0',
258         'unfinished' => ' AND timefinish = 0'
259     );
260     $previewclause = '';
261     if (!$includepreviews) {
262         $previewclause = ' AND preview = 0';
263     }
264     $params=array($quizid);
265     if ($userid){
266         $userclause = ' AND userid = ?';
267         $params[]=$userid;
268     } else {
269         $userclause = '';
270     }
271     if ($attempts = $DB->get_records_select('quiz_attempts',
272             "quiz = ?" .$userclause. $previewclause . $status_condition[$status], $params,
273             'attempt ASC')) {
274         return $attempts;
275     } else {
276         return array();
277     }
280 /**
281  * Return grade for given user or all users.
282  *
283  * @param int $quizid id of quiz
284  * @param int $userid optional user id, 0 means all users
285  * @return array array of grades, false if none
286  */
287 function quiz_get_user_grades($quiz, $userid=0) {
288     global $CFG, $DB;
290     $params = array($quiz->id);
291     $wheresql = '';
292     if ($userid) {
293         $params[] = $userid;
294         $wheresql = "AND u.id = ?";
295     }
296     $sql = "SELECT u.id, u.id AS userid, g.grade AS rawgrade, g.timemodified AS dategraded, MAX(a.timefinish) AS datesubmitted
297             FROM {user} u, {quiz_grades} g, {quiz_attempts} a
298             WHERE u.id = g.userid AND g.quiz = ? AND a.quiz = g.quiz AND u.id = a.userid $wheresql
299             GROUP BY u.id, g.grade, g.timemodified";
301     return $DB->get_records_sql($sql, $params);
304 /**
305  * Update grades in central gradebook
306  *
307  * @param object $quiz null means all quizs
308  * @param int $userid specific user only, 0 mean all
309  */
310 function quiz_update_grades($quiz=null, $userid=0, $nullifnone=true) {
311     global $CFG, $DB;
312     if (!function_exists('grade_update')) { //workaround for buggy PHP versions
313         require_once($CFG->libdir.'/gradelib.php');
314     }
316     if ($quiz != null) {
317         if ($grades = quiz_get_user_grades($quiz, $userid)) {
318             quiz_grade_item_update($quiz, $grades);
320         } else if ($userid and $nullifnone) {
321             $grade = new object();
322             $grade->userid   = $userid;
323             $grade->rawgrade = NULL;
324             quiz_grade_item_update($quiz, $grade);
326         } else {
327             quiz_grade_item_update($quiz);
328         }
330     } else {
331         $sql = "SELECT a.*, cm.idnumber as cmidnumber, a.course as courseid
332                   FROM {quiz} a, {course_modules} cm, {modules} m
333                  WHERE m.name='quiz' AND m.id=cm.module AND cm.instance=a.id";
334         if ($rs = $DB->get_recordset_sql($sql)) {
335             foreach ($rs as $quiz) {
336                 if ($quiz->grade != 0) {
337                     quiz_update_grades($quiz, 0, false);
338                 } else {
339                     quiz_grade_item_update($quiz);
340                 }
341             }
342             $rs->close();
343         }
344     }
347 /**
348  * Create grade item for given quiz
349  *
350  * @param object $quiz object with extra cmidnumber
351  * @param mixed optional array/object of grade(s); 'reset' means reset grades in gradebook
352  * @return int 0 if ok, error code otherwise
353  */
354 function quiz_grade_item_update($quiz, $grades=NULL) {
355     global $CFG;
356     if (!function_exists('grade_update')) { //workaround for buggy PHP versions
357         require_once($CFG->libdir.'/gradelib.php');
358     }
360     if (array_key_exists('cmidnumber', $quiz)) { //it may not be always present
361         $params = array('itemname'=>$quiz->name, 'idnumber'=>$quiz->cmidnumber);
362     } else {
363         $params = array('itemname'=>$quiz->name);
364     }
366     if ($quiz->grade > 0) {
367         $params['gradetype'] = GRADE_TYPE_VALUE;
368         $params['grademax']  = $quiz->grade;
369         $params['grademin']  = 0;
371     } else {
372         $params['gradetype'] = GRADE_TYPE_NONE;
373     }
375 /* description by TJ:
376 1/ If the quiz is set to not show scores while the quiz is still open, and is set to show scores after
377    the quiz is closed, then create the grade_item with a show-after date that is the quiz close date.
378 2/ If the quiz is set to not show scores at either of those times, create the grade_item as hidden.
379 3/ If the quiz is set to show scores, create the grade_item visible.
380 */
381     if (!($quiz->review & QUIZ_REVIEW_SCORES & QUIZ_REVIEW_CLOSED)
382     and !($quiz->review & QUIZ_REVIEW_SCORES & QUIZ_REVIEW_OPEN)) {
383         $params['hidden'] = 1;
385     } else if ( ($quiz->review & QUIZ_REVIEW_SCORES & QUIZ_REVIEW_CLOSED)
386            and !($quiz->review & QUIZ_REVIEW_SCORES & QUIZ_REVIEW_OPEN)) {
387         if ($quiz->timeclose) {
388             $params['hidden'] = $quiz->timeclose;
389         } else {
390             $params['hidden'] = 1;
391         }
393     } else {
394         // a) both open and closed enabled
395         // b) open enabled, closed disabled - we can not "hide after", grades are kept visible even after closing
396         $params['hidden'] = 0;
397     }
399     if ($grades  === 'reset') {
400         $params['reset'] = true;
401         $grades = NULL;
402     }
404     $gradebook_grades = grade_get_grades($quiz->course, 'mod', 'quiz', $quiz->id);
405     if (!empty($gradebook_grades->items)) {
406         $grade_item = $gradebook_grades->items[0];
407         if ($grade_item->locked) {
408             $confirm_regrade = optional_param('confirm_regrade', 0, PARAM_INT);
409             if (!$confirm_regrade) {
410                 $message = get_string('gradeitemislocked', 'grades');
411                 $back_link = $CFG->wwwroot . '/mod/quiz/report.php?q=' . $quiz->id . '&amp;mode=overview';
412                 $regrade_link = qualified_me() . '&amp;confirm_regrade=1';
413                 print_box_start('generalbox', 'notice');
414                 echo '<p>'. $message .'</p>';
415                 echo '<div class="buttons">';
416                 print_single_button($regrade_link, null, get_string('regradeanyway', 'grades'), 'post', $CFG->framename);
417                 print_single_button($back_link,  null,  get_string('cancel'),  'post',  $CFG->framename);
418                 echo '</div>';
419                 print_box_end();
421                 return GRADE_UPDATE_ITEM_LOCKED;
422             }
423         }
424     }
426     return grade_update('mod/quiz', $quiz->course, 'mod', 'quiz', $quiz->id, 0, $grades, $params);
429 /**
430  * Delete grade item for given quiz
431  *
432  * @param object $quiz object
433  * @return object quiz
434  */
435 function quiz_grade_item_delete($quiz) {
436     global $CFG;
437     require_once($CFG->libdir.'/gradelib.php');
439     return grade_update('mod/quiz', $quiz->course, 'mod', 'quiz', $quiz->id, 0, NULL, array('deleted'=>1));
443 function quiz_get_participants($quizid) {
444 /// Returns an array of users who have data in a given quiz
445 /// (users with records in quiz_attempts and quiz_question_versions)
447     global $CFG, $DB;
449     //Get users from attempts
450     $us_attempts = $DB->get_records_sql("SELECT DISTINCT u.id, u.id
451                                     FROM {user} u,
452                                          {quiz_attempts} a
453                                     WHERE a.quiz = ? and
454                                           u.id = a.userid", array($quizid));
456     //Get users from question_versions
457     $us_versions = $DB->get_records_sql("SELECT DISTINCT u.id, u.id
458                                     FROM {user} u,
459                                          {quiz_question_versions} v
460                                     WHERE v.quiz = ? and
461                                           u.id = v.userid", array($quizid));
463     //Add us_versions to us_attempts
464     if ($us_versions) {
465         foreach ($us_versions as $us_version) {
466             $us_attempts[$us_version->id] = $us_version;
467         }
468     }
469     //Return us_attempts array (it contains an array of unique users)
470     return ($us_attempts);
474 function quiz_refresh_events($courseid = 0) {
475     global $DB;
476 // This horrible function only seems to be called from mod/quiz/db/[dbtype].php.
478 // This standard function will check all instances of this module
479 // and make sure there are up-to-date events created for each of them.
480 // If courseid = 0, then every quiz event in the site is checked, else
481 // only quiz events belonging to the course specified are checked.
482 // This function is used, in its new format, by restore_refresh_events()
484     if ($courseid == 0) {
485         if (! $quizzes = $DB->get_records('quiz')) {
486             return true;
487         }
488     } else {
489         if (! $quizzes = $DB->get_records('quiz', array('course' => $courseid))) {
490             return true;
491         }
492     }
493     $moduleid = $DB->get_field('modules', 'id', array('name' => 'quiz'));
495     foreach ($quizzes as $quiz) {
496         $event = NULL;
497         $event2 = NULL;
498         $event2old = NULL;
500         if ($events = $DB->get_records_select('event', "modulename = 'quiz' AND instance = ? ORDER BY timestart", array($quiz->id))) {
501             $event = array_shift($events);
502             if (!empty($events)) {
503                 $event2old = array_shift($events);
504                 if (!empty($events)) {
505                     foreach ($events as $badevent) {
506                         $DB->delete_records('event', array('id' => $badevent->id));
507                     }
508                 }
509             }
510         }
512         $event->name        = $quiz->name;
513         $event->description = $quiz->intro;
514         $event->courseid    = $quiz->course;
515         $event->groupid     = 0;
516         $event->userid      = 0;
517         $event->modulename  = 'quiz';
518         $event->instance    = $quiz->id;
519         $event->visible     = instance_is_visible('quiz', $quiz);
520         $event->timestart   = $quiz->timeopen;
521         $event->eventtype   = 'open';
522         $event->timeduration = ($quiz->timeclose - $quiz->timeopen);
524         if ($event->timeduration > QUIZ_MAX_EVENT_LENGTH) {  /// Set up two events
526             $event2 = $event;
528             $event->name         = $quiz->name.' ('.get_string('quizopens', 'quiz').')';
529             $event->timeduration = 0;
531             $event2->name        = $quiz->name.' ('.get_string('quizcloses', 'quiz').')';
532             $event2->timestart   = $quiz->timeclose;
533             $event2->eventtype   = 'close';
534             $event2->timeduration = 0;
536             if (empty($event2old->id)) {
537                 unset($event2->id);
538                 add_event($event2);
539             } else {
540                 $event2->id = $event2old->id;
541                 update_event($event2);
542             }
543         } else if (!empty($event2old->id)) {
544             delete_event($event2old->id);
545         }
547         if (empty($event->id)) {
548             if (!empty($event->timestart)) {
549                 add_event($event);
550             }
551         } else {
552             update_event($event);
553         }
555     }
556     return true;
559 /**
560  * Returns all quiz graded users since a given time for specified quiz
561  */
562 function quiz_get_recent_mod_activity(&$activities, &$index, $timestart, $courseid, $cmid, $userid=0, $groupid=0)  {
563     global $CFG, $COURSE, $USER, $DB;
565     if ($COURSE->id == $courseid) {
566         $course = $COURSE;
567     } else {
568         $course = $DB->get_record('course', array('id' => $courseid));
569     }
571     $modinfo =& get_fast_modinfo($course);
573     $cm = $modinfo->cms[$cmid];
575     $params = array($timestart, $cm->instance);
577     if ($userid) {
578         $userselect = "AND u.id = ?";
579         $params[] = $userid;
580     } else {
581         $userselect = "";
582     }
584     if ($groupid) {
585         $groupselect = "AND gm.groupid = ?";
586         $groupjoin   = "JOIN {groups_members} gm ON  gm.userid=u.id";
587         $params[] = $groupid;
588     } else {
589         $groupselect = "";
590         $groupjoin   = "";
591     }
593     if (!$attempts = $DB->get_records_sql("SELECT qa.*, q.sumgrades AS maxgrade,
594                                              u.firstname, u.lastname, u.email, u.picture
595                                         FROM {quiz_attempts} qa
596                                              JOIN {quiz} q ON q.id = qa.quiz
597                                              JOIN {user} u ON u.id = qa.userid
598                                              $groupjoin
599                                        WHERE qa.timefinish > $timestart AND q.id = $cm->instance
600                                              $userselect $groupselect
601                                     ORDER BY qa.timefinish ASC", $params)) {
602          return;
603     }
606     $cm_context      = get_context_instance(CONTEXT_MODULE, $cm->id);
607     $grader          = has_capability('moodle/grade:viewall', $cm_context);
608     $accessallgroups = has_capability('moodle/site:accessallgroups', $cm_context);
609     $viewfullnames   = has_capability('moodle/site:viewfullnames', $cm_context);
610     $grader          = has_capability('mod/quiz:grade', $cm_context);
611     $groupmode       = groups_get_activity_groupmode($cm, $course);
613     if (is_null($modinfo->groups)) {
614         $modinfo->groups = groups_get_user_groups($course->id); // load all my groups and cache it in modinfo
615     }
617     $aname = format_string($cm->name,true);
618     foreach ($attempts as $attempt) {
619         if ($attempt->userid != $USER->id) {
620             if (!$grader) {
621                 // grade permission required
622                 continue;
623             }
625             if ($groupmode == SEPARATEGROUPS and !$accessallgroups) {
626                 $usersgroups = groups_get_all_groups($course->id, $attempt->userid, $cm->groupingid);
627                 if (!is_array($usersgroups)) {
628                     continue;
629                 }
630                 $usersgroups = array_keys($usersgroups);
631                 $interset = array_intersect($usersgroups, $modinfo->groups[$cm->id]);
632                 if (empty($intersect)) {
633                     continue;
634                 }
635             }
636        }
638         $tmpactivity = new object();
640         $tmpactivity->type      = 'quiz';
641         $tmpactivity->cmid      = $cm->id;
642         $tmpactivity->name      = $aname;
643         $tmpactivity->sectionnum= $cm->sectionnum;
644         $tmpactivity->timestamp = $attempt->timefinish;
646         $tmpactivity->content->attemptid = $attempt->id;
647         $tmpactivity->content->sumgrades = $attempt->sumgrades;
648         $tmpactivity->content->maxgrade  = $attempt->maxgrade;
649         $tmpactivity->content->attempt   = $attempt->attempt;
651         $tmpactivity->user->userid   = $attempt->userid;
652         $tmpactivity->user->fullname = fullname($attempt, $viewfullnames);
653         $tmpactivity->user->picture  = $attempt->picture;
655         $activities[$index++] = $tmpactivity;
656     }
658   return;
662 function quiz_print_recent_mod_activity($activity, $courseid, $detail, $modnames) {
663     global $CFG;
665     echo '<table border="0" cellpadding="3" cellspacing="0" class="forum-recent">';
667     echo "<tr><td class=\"userpicture\" valign=\"top\">";
668     print_user_picture($activity->user->userid, $courseid, $activity->user->picture);
669     echo "</td><td>";
671     if ($detail) {
672         $modname = $modnames[$activity->type];
673         echo '<div class="title">';
674         echo "<img src=\"$CFG->modpixpath/{$activity->type}/icon.gif\" ".
675              "class=\"icon\" alt=\"$modname\" />";
676         echo "<a href=\"$CFG->wwwroot/mod/quiz/view.php?id={$activity->cmid}\">{$activity->name}</a>";
677         echo '</div>';
678     }
680     echo '<div class="grade">';
681     echo  get_string("attempt", "quiz")." {$activity->content->attempt}: ";
682     $grades = "({$activity->content->sumgrades} / {$activity->content->maxgrade})";
683     echo "<a href=\"$CFG->wwwroot/mod/quiz/review.php?attempt={$activity->content->attemptid}\">$grades</a>";
684     echo '</div>';
686     echo '<div class="user">';
687     echo "<a href=\"$CFG->wwwroot/user/view.php?id={$activity->user->userid}&amp;course=$courseid\">"
688          ."{$activity->user->fullname}</a> - ".userdate($activity->timestamp);
689     echo '</div>';
691     echo "</td></tr></table>";
693     return;
696 /**
697  * Pre-process the quiz options form data, making any necessary adjustments.
698  * Called by add/update instance in this file, and the save code in admin/module.php.
699  *
700  * @param object $quiz The variables set on the form.
701  */
702 function quiz_process_options(&$quiz) {
703     $quiz->timemodified = time();
705     // Quiz open time.
706     if (empty($quiz->timeopen)) {
707         $quiz->preventlate = 0;
708     }
710     // Quiz name.
711     if (!empty($quiz->name)) {
712         $quiz->name = trim($quiz->name);
713     }
715     // Time limit. (Get rid of it if the checkbox was not ticked.)
716     if (empty($quiz->timelimitenable)) {
717         $quiz->timelimit = 0;
718     }
719     $quiz->timelimit = round($quiz->timelimit);
721     // Password field - different in form to stop browsers that remember passwords
722     // getting confused.
723     $quiz->password = $quiz->quizpassword;
724     unset($quiz->quizpassword);
726     // Quiz feedback
727     if (isset($quiz->feedbacktext)) {
728         // Clean up the boundary text.
729         for ($i = 0; $i < count($quiz->feedbacktext); $i += 1) {
730             if (empty($quiz->feedbacktext[$i])) {
731                 $quiz->feedbacktext[$i] = '';
732             } else {
733                 $quiz->feedbacktext[$i] = trim($quiz->feedbacktext[$i]);
734             }
735         }
737         // Check the boundary value is a number or a percentage, and in range.
738         $i = 0;
739         while (!empty($quiz->feedbackboundaries[$i])) {
740             $boundary = trim($quiz->feedbackboundaries[$i]);
741             if (!is_numeric($boundary)) {
742                 if (strlen($boundary) > 0 && $boundary[strlen($boundary) - 1] == '%') {
743                     $boundary = trim(substr($boundary, 0, -1));
744                     if (is_numeric($boundary)) {
745                         $boundary = $boundary * $quiz->grade / 100.0;
746                     } else {
747                         return get_string('feedbackerrorboundaryformat', 'quiz', $i + 1);
748                     }
749                 }
750             }
751             if ($boundary <= 0 || $boundary >= $quiz->grade) {
752                 return get_string('feedbackerrorboundaryoutofrange', 'quiz', $i + 1);
753             }
754             if ($i > 0 && $boundary >= $quiz->feedbackboundaries[$i - 1]) {
755                 return get_string('feedbackerrororder', 'quiz', $i + 1);
756             }
757             $quiz->feedbackboundaries[$i] = $boundary;
758             $i += 1;
759         }
760         $numboundaries = $i;
762         // Check there is nothing in the remaining unused fields.
763         for ($i = $numboundaries; $i < count($quiz->feedbackboundaries); $i += 1) {
764             if (!empty($quiz->feedbackboundaries[$i]) && trim($quiz->feedbackboundaries[$i]) != '') {
765                 return get_string('feedbackerrorjunkinboundary', 'quiz', $i + 1);
766             }
767         }
768         for ($i = $numboundaries + 1; $i < count($quiz->feedbacktext); $i += 1) {
769             if (!empty($quiz->feedbacktext[$i]) && trim($quiz->feedbacktext[$i]) != '') {
770                 return get_string('feedbackerrorjunkinfeedback', 'quiz', $i + 1);
771             }
772         }
773         $quiz->feedbackboundaries[-1] = $quiz->grade + 1; // Needs to be bigger than $quiz->grade because of '<' test in quiz_feedback_for_grade().
774         $quiz->feedbackboundaries[$numboundaries] = 0;
775         $quiz->feedbackboundarycount = $numboundaries;
776     }
778     // Settings that get combined to go into the optionflags column.
779     $quiz->optionflags = 0;
780     if (!empty($quiz->adaptive)) {
781         $quiz->optionflags |= QUESTION_ADAPTIVE;
782     }
784     // Settings that get combined to go into the review column.
785     $review = 0;
786     if (isset($quiz->responsesimmediately)) {
787         $review += (QUIZ_REVIEW_RESPONSES & QUIZ_REVIEW_IMMEDIATELY);
788         unset($quiz->responsesimmediately);
789     }
790     if (isset($quiz->responsesopen)) {
791         $review += (QUIZ_REVIEW_RESPONSES & QUIZ_REVIEW_OPEN);
792         unset($quiz->responsesopen);
793     }
794     if (isset($quiz->responsesclosed)) {
795         $review += (QUIZ_REVIEW_RESPONSES & QUIZ_REVIEW_CLOSED);
796         unset($quiz->responsesclosed);
797     }
799     if (isset($quiz->scoreimmediately)) {
800         $review += (QUIZ_REVIEW_SCORES & QUIZ_REVIEW_IMMEDIATELY);
801         unset($quiz->scoreimmediately);
802     }
803     if (isset($quiz->scoreopen)) {
804         $review += (QUIZ_REVIEW_SCORES & QUIZ_REVIEW_OPEN);
805         unset($quiz->scoreopen);
806     }
807     if (isset($quiz->scoreclosed)) {
808         $review += (QUIZ_REVIEW_SCORES & QUIZ_REVIEW_CLOSED);
809         unset($quiz->scoreclosed);
810     }
812     if (isset($quiz->feedbackimmediately)) {
813         $review += (QUIZ_REVIEW_FEEDBACK & QUIZ_REVIEW_IMMEDIATELY);
814         unset($quiz->feedbackimmediately);
815     }
816     if (isset($quiz->feedbackopen)) {
817         $review += (QUIZ_REVIEW_FEEDBACK & QUIZ_REVIEW_OPEN);
818         unset($quiz->feedbackopen);
819     }
820     if (isset($quiz->feedbackclosed)) {
821         $review += (QUIZ_REVIEW_FEEDBACK & QUIZ_REVIEW_CLOSED);
822         unset($quiz->feedbackclosed);
823     }
825     if (isset($quiz->answersimmediately)) {
826         $review += (QUIZ_REVIEW_ANSWERS & QUIZ_REVIEW_IMMEDIATELY);
827         unset($quiz->answersimmediately);
828     }
829     if (isset($quiz->answersopen)) {
830         $review += (QUIZ_REVIEW_ANSWERS & QUIZ_REVIEW_OPEN);
831         unset($quiz->answersopen);
832     }
833     if (isset($quiz->answersclosed)) {
834         $review += (QUIZ_REVIEW_ANSWERS & QUIZ_REVIEW_CLOSED);
835         unset($quiz->answersclosed);
836     }
838     if (isset($quiz->solutionsimmediately)) {
839         $review += (QUIZ_REVIEW_SOLUTIONS & QUIZ_REVIEW_IMMEDIATELY);
840         unset($quiz->solutionsimmediately);
841     }
842     if (isset($quiz->solutionsopen)) {
843         $review += (QUIZ_REVIEW_SOLUTIONS & QUIZ_REVIEW_OPEN);
844         unset($quiz->solutionsopen);
845     }
846     if (isset($quiz->solutionsclosed)) {
847         $review += (QUIZ_REVIEW_SOLUTIONS & QUIZ_REVIEW_CLOSED);
848         unset($quiz->solutionsclosed);
849     }
851     if (isset($quiz->generalfeedbackimmediately)) {
852         $review += (QUIZ_REVIEW_GENERALFEEDBACK & QUIZ_REVIEW_IMMEDIATELY);
853         unset($quiz->generalfeedbackimmediately);
854     }
855     if (isset($quiz->generalfeedbackopen)) {
856         $review += (QUIZ_REVIEW_GENERALFEEDBACK & QUIZ_REVIEW_OPEN);
857         unset($quiz->generalfeedbackopen);
858     }
859     if (isset($quiz->generalfeedbackclosed)) {
860         $review += (QUIZ_REVIEW_GENERALFEEDBACK & QUIZ_REVIEW_CLOSED);
861         unset($quiz->generalfeedbackclosed);
862     }
864     if (isset($quiz->overallfeedbackimmediately)) {
865         $review += (QUIZ_REVIEW_OVERALLFEEDBACK & QUIZ_REVIEW_IMMEDIATELY);
866         unset($quiz->overallfeedbackimmediately);
867     }
868     if (isset($quiz->overallfeedbackopen)) {
869         $review += (QUIZ_REVIEW_OVERALLFEEDBACK & QUIZ_REVIEW_OPEN);
870         unset($quiz->overallfeedbackopen);
871     }
872     if (isset($quiz->overallfeedbackclosed)) {
873         $review += (QUIZ_REVIEW_OVERALLFEEDBACK & QUIZ_REVIEW_CLOSED);
874         unset($quiz->overallfeedbackclosed);
875     }
877     $quiz->review = $review;
880 /**
881  * This function is called at the end of quiz_add_instance
882  * and quiz_update_instance, to do the common processing.
883  *
884  * @param object $quiz the quiz object.
885  */
886 function quiz_after_add_or_update($quiz) {
887     global $DB;
889     // Save the feedback
890     $DB->delete_records('quiz_feedback', array('quizid'=>$quiz->id));
892     for ($i = 0; $i <= $quiz->feedbackboundarycount; $i += 1) {
893         $feedback = new stdClass;
894         $feedback->quizid = $quiz->id;
895         $feedback->feedbacktext = $quiz->feedbacktext[$i];
896         $feedback->mingrade = $quiz->feedbackboundaries[$i];
897         $feedback->maxgrade = $quiz->feedbackboundaries[$i - 1];
898         if (!$DB->insert_record('quiz_feedback', $feedback, false)) {
899             return "Could not save quiz feedback.";
900         }
901     }
904     // Update the events relating to this quiz.
905     // This is slightly inefficient, deleting the old events and creating new ones. However,
906     // there are at most two events, and this keeps the code simpler.
907     if ($events = $DB->get_records('event', array('modulename'=>'quiz', 'instance'=>$quiz->id))) {
908         foreach($events as $event) {
909             delete_event($event->id);
910         }
911     }
913     $event = new stdClass;
914     $event->description = $quiz->intro;
915     $event->courseid    = $quiz->course;
916     $event->groupid     = 0;
917     $event->userid      = 0;
918     $event->modulename  = 'quiz';
919     $event->instance    = $quiz->id;
920     $event->timestart   = $quiz->timeopen;
921     $event->timeduration = $quiz->timeclose - $quiz->timeopen;
922     $event->visible     = instance_is_visible('quiz', $quiz);
923     $event->eventtype   = 'open';
925     if ($quiz->timeclose and $quiz->timeopen and $event->timeduration <= QUIZ_MAX_EVENT_LENGTH) {
926         // Single event for the whole quiz.
927         $event->name = $quiz->name;
928         add_event($event);
929     } else {
930         // Separate start and end events.
931         $event->timeduration  = 0;
932         if ($quiz->timeopen) {
933             $event->name = $quiz->name.' ('.get_string('quizopens', 'quiz').')';
934             add_event($event);
935             unset($event->id); // So we can use the same object for the close event.
936         }
937         if ($quiz->timeclose) {
938             $event->name      = $quiz->name.' ('.get_string('quizcloses', 'quiz').')';
939             $event->timestart = $quiz->timeclose;
940             $event->eventtype = 'close';
941             add_event($event);
942         }
943     }
945     //update related grade item
946     quiz_grade_item_update($quiz);
949 function quiz_get_view_actions() {
950     return array('view','view all','report');
953 function quiz_get_post_actions() {
954     return array('attempt','editquestions','review','submit');
957 /**
958  * Returns an array of names of quizzes that use this question
959  *
960  * @param object $questionid
961  * @return array of strings
962  */
963 function quiz_question_list_instances($questionid) {
964     global $CFG, $DB;
966     // TODO: we should also consider other questions that are used by
967     // random questions in this quiz, but that is very hard.
969     $sql = "SELECT q.id, q.name
970             FROM {quiz} q
971             JOIN {quiz_question_instances} qqi ON q.id = qqi.quiz
972             WHERE qqi.question = ?";
974     if ($instances = $DB->get_records_sql_menu($sql, array($questionid))) {
975         return $instances;
976     }
977     return array();
980 /**
981  * Implementation of the function for printing the form elements that control
982  * whether the course reset functionality affects the quiz.
983  * @param $mform form passed by reference
984  */
985 function quiz_reset_course_form_definition(&$mform) {
986     $mform->addElement('header', 'forumheader', get_string('modulenameplural', 'quiz'));
987     $mform->addElement('advcheckbox', 'reset_quiz_attempts', get_string('removeallquizattempts','quiz'));
990 /**
991  * Course reset form defaults.
992  */
993 function quiz_reset_course_form_defaults($course) {
994     return array('reset_quiz_attempts'=>1);
997 /**
998  * Removes all grades from gradebook
999  * @param int $courseid
1000  * @param string optional type
1001  */
1002 function quiz_reset_gradebook($courseid, $type='') {
1003     global $CFG, $DB;
1005     $sql = "SELECT q.*, cm.idnumber as cmidnumber, q.course as courseid
1006               FROM {quiz} q, {course_modules} cm, {modules} m
1007              WHERE m.name='quiz' AND m.id=cm.module AND cm.instance=q.id AND q.course=?";
1009     if ($quizs = $DB->get_records_sql($sql, array($courseid))) {
1010         foreach ($quizs as $quiz) {
1011             quiz_grade_item_update($quiz, 'reset');
1012         }
1013     }
1016 /**
1017  * Actual implementation of the rest coures functionality, delete all the
1018  * quiz attempts for course $data->courseid, if $data->reset_quiz_attempts is
1019  * set and true.
1020  *
1021  * Also, move the quiz open and close dates, if the course start date is changing.
1022  * @param $data the data submitted from the reset course.
1023  * @return array status array
1024  */
1025 function quiz_reset_userdata($data) {
1026     global $CFG, $QTYPES, $DB;
1028     $componentstr = get_string('modulenameplural', 'quiz');
1029     $status = array();
1031     /// Delete attempts.
1032     if (!empty($data->reset_quiz_attempts)) {
1033         $params = array($data->courseid);
1034         $stateslistsql = "SELECT s.id
1035                             FROM {question_states} s
1036                                  INNER JOIN {quiz_attempts} qza ON s.attempt=qza.uniqueid
1037                                  INNER JOIN {quiz} q ON qza.quiz=q.id
1038                            WHERE q.course=?";
1040         $attemptssql   = "SELECT a.uniqueid
1041                             FROM {quiz_attempts} a, {quiz} q
1042                            WHERE q.course=? AND a.quiz=q.id";
1044         $quizessql     = "SELECT q.id
1045                             FROM {quiz} q
1046                            WHERE q.course=?";
1048         if ($states = $DB->get_records_sql($stateslistsql, $params)) {
1049             //TODO: not sure if this works
1050             $stateslist = implode(',', array_keys($states));
1051             foreach ($QTYPES as $qtype) {
1052                 $qtype->delete_states($stateslist);
1053             }
1054         }
1056         $DB->delete_records_select('question_states', "attempt IN ($attemptssql)", $params);
1057         $DB->delete_records_select('question_sessions', "attemptid IN ($attemptssql)", $params);
1058         $DB->delete_records_select('question_attempts', "id IN ($attemptssql)", $params);
1060         // remove all grades from gradebook
1061         if (empty($data->reset_gradebook_grades)) {
1062             quiz_reset_gradebook($data->courseid);
1063         }
1065         $DB->delete_records_select('quiz_grades', "quiz IN ($quizessql)", $params);
1066         $status[] = array('component'=>$componentstr, 'item'=>get_string('gradesdeleted','quiz'), 'error'=>false);
1068         $DB->delete_records_select('quiz_attempts', "quiz IN ($quizessql)", $params);
1069         $status[] = array('component'=>$componentstr, 'item'=>get_string('attemptsdeleted','quiz'), 'error'=>false);
1070     }
1072     /// updating dates - shift may be negative too
1073     if ($data->timeshift) {
1074         shift_course_mod_dates('quiz', array('timeopen', 'timeclose'), $data->timeshift, $data->courseid);
1075         $status[] = array('component'=>$componentstr, 'item'=>get_string('openclosedatesupdated', 'quiz'), 'error'=>false);
1076     }
1078     return $status;
1081 /**
1082  * Checks whether the current user is allowed to view a file uploaded in a quiz.
1083  * Teachers can view any from their courses, students can only view their own.
1084  *
1085  * @param int $attemptuniqueid int attempt id
1086  * @param int $questionid int question id
1087  * @return boolean to indicate access granted or denied
1088  */
1089 function quiz_check_file_access($attemptuniqueid, $questionid) {
1090     global $USER, $DB;
1092     $attempt = $DB->get_record('quiz_attempts', array('uniqueid' => $attemptuniqueid));
1093     $quiz = $DB->get_record('quiz', array('id' => $attempt->quiz));
1094     $context = get_context_instance(CONTEXT_COURSE, $quiz->course);
1096     // access granted if the current user submitted this file
1097     if ($attempt->userid == $USER->id) {
1098         return true;
1099     // access granted if the current user has permission to grade quizzes in this course
1100     } else if (has_capability('mod/quiz:viewreports', $context) || has_capability('mod/quiz:grade', $context)) {
1101         return true;
1102     }
1104     // otherwise, this user does not have permission
1105     return false;
1108 /**
1109  * Prints quiz summaries on MyMoodle Page
1110  */
1111 function quiz_print_overview($courses, &$htmlarray) {
1112     global $USER, $CFG;
1113 /// These next 6 Lines are constant in all modules (just change module name)
1114     if (empty($courses) || !is_array($courses) || count($courses) == 0) {
1115         return array();
1116     }
1118     if (!$quizzes = get_all_instances_in_courses('quiz', $courses)) {
1119         return;
1120     }
1122 /// Fetch some language strings outside the main loop.
1123     $strquiz = get_string('modulename', 'quiz');
1124     $strnoattempts = get_string('noattempts', 'quiz');
1126 /// We want to list quizzes that are currently available, and which have a close date.
1127 /// This is the same as what the lesson does, and the dabate is in MDL-10568.
1128     $now = time();
1129     foreach ($quizzes as $quiz) {
1130         if ($quiz->timeclose >= $now && $quiz->timeopen < $now) {
1131         /// Give a link to the quiz, and the deadline.
1132             $str = '<div class="quiz overview">' .
1133                     '<div class="name">' . $strquiz . ': <a ' . ($quiz->visible ? '' : ' class="dimmed"') .
1134                     ' href="' . $CFG->wwwroot . '/mod/quiz/view.php?id=' . $quiz->coursemodule . '">' .
1135                     $quiz->name . '</a></div>';
1136             $str .= '<div class="info">' . get_string('quizcloseson', 'quiz', userdate($quiz->timeclose)) . '</div>';
1138         /// Now provide more information depending on the uers's role.
1139             $context = get_context_instance(CONTEXT_MODULE, $quiz->coursemodule);
1140             if (has_capability('mod/quiz:viewreports', $context)) {
1141             /// For teacher-like people, show a summary of the number of student attempts.
1142                 // The $quiz objects returned by get_all_instances_in_course have the necessary $cm
1143                 // fields set to make the following call work.
1144                 $str .= '<div class="info">' . quiz_num_attempt_summary($quiz, $quiz, true) . '</div>';
1145             } else if (has_capability('mod/quiz:attempt', $context)){ // Student
1146             /// For student-like people, tell them how many attempts they have made.
1147                 if (isset($USER->id) && ($attempts = quiz_get_user_attempts($quiz->id, $USER->id))) {
1148                     $numattempts = count($attempts);
1149                     $str .= '<div class="info">' . get_string('numattemptsmade', 'quiz', $numattempts) . '</div>';
1150                 } else {
1151                     $str .= '<div class="info">' . $strnoattempts . '</div>';
1152                 }
1153             } else {
1154             /// For ayone else, there is no point listing this quiz, so stop processing.
1155                 continue;
1156             }
1158         /// Add the output for this quiz to the rest.
1159             $str .= '</div>';
1160             if (empty($htmlarray[$quiz->course]['quiz'])) {
1161                 $htmlarray[$quiz->course]['quiz'] = $str;
1162             } else {
1163                 $htmlarray[$quiz->course]['quiz'] .= $str;
1164             }
1165         }
1166     }
1169 /**
1170  * Return a textual summary of the number of attemtps that have been made at a particular quiz,
1171  * returns '' if no attemtps have been made yet, unless $returnzero is passed as true.
1172  * @param object $quiz the quiz object. Only $quiz->id is used at the moment.
1173  * @param object $cm the cm object. Only $cm->course, $cm->groupmode and $cm->groupingid fields are used at the moment.
1174  * @param boolean $returnzero if false (default), when no attempts have been made '' is returned instead of 'Attempts: 0'.
1175  * @param int $currentgroup if there is a concept of current group where this method is being called
1176  *         (e.g. a report) pass it in here. Default 0 which means no current group.
1177  * @return string a string like "Attempts: 123", "Attemtps 123 (45 from your groups)" or
1178  *          "Attemtps 123 (45 from this group)".
1179  */
1180 function quiz_num_attempt_summary($quiz, $cm, $returnzero = false, $currentgroup = 0) {
1181     global $CFG, $USER, $DB;
1182     $numattempts = $DB->count_records('quiz_attempts', array('quiz'=> $quiz->id, 'preview'=>0));
1183     if ($numattempts || $returnzero) {
1184         if (groups_get_activity_groupmode($cm)) {
1185             $a->total = $numattempts;
1186             if ($currentgroup) {
1187                 $a->group = $DB->count_records_sql('SELECT count(1) FROM ' .
1188                         '{quiz_attempts} qa JOIN ' .
1189                         '{groups_members} gm ON qa.userid = gm.userid ' .
1190                         'WHERE quiz = ? AND preview = 0 AND groupid = ?', array($quiz->id, $currentgroup));
1191                 return get_string('attemptsnumthisgroup', 'quiz', $a);
1192             } else if ($groups = groups_get_all_groups($cm->course, $USER->id, $cm->groupingid)) {
1193                 list($usql, $params) = $DB->get_in_or_equal(array_keys($groups));
1194                 $a->group = $DB->count_records_sql('SELECT count(1) FROM ' .
1195                         '{quiz_attempts} qa JOIN ' .
1196                         '{groups_members} gm ON qa.userid = gm.userid ' .
1197                         'WHERE quiz = ? AND preview = 0 AND ' .
1198                         "groupid $usql", array_merge(array($quiz->id), $params));
1199                 return get_string('attemptsnumyourgroups', 'quiz', $a);
1200             }
1201         }
1202         return get_string('attemptsnum', 'quiz', $numattempts);
1203     }
1204     return '';
1207 /**
1208  * @param string $feature FEATURE_xx constant for requested feature
1209  * @return bool True if quiz supports feature
1210  */
1211 function quiz_supports($feature) {
1212     switch($feature) {
1213         case FEATURE_GRADE_HAS_GRADE: return true;
1214         case FEATURE_COMPLETION_TRACKS_VIEWS: return true;
1215         default: return null;
1216     }
1219 /**
1220  * Returns all other caps used in module
1221  */
1222 function quiz_get_extra_capabilities() {
1223     return array(
1224         'moodle/site:accessallgroups',
1225         'moodle/question:add',
1226         'moodle/question:editmine',
1227         'moodle/question:editall',
1228         'moodle/question:viewmine',
1229         'moodle/question:viewall',
1230         'moodle/question:usemine',
1231         'moodle/question:useall',
1232         'moodle/question:movemine',
1233         'moodle/question:moveall',
1234         'moodle/question:managecategory',
1235     );
1238 ?>