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