MDL-10107 Fixed the definition of message providers ... it now works through files...
[moodle.git] / mod / lesson / lib.php
1 <?php  // $Id$
2 /**
3  * Standard library of functions and constants for lesson
4  *
5  * @version $Id$
6  * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
7  * @package lesson
8  **/
10 require_once($CFG->libdir.'/eventslib.php');
12 define("LESSON_MAX_EVENT_LENGTH", "432000");   // 5 days maximum
14 /** 
15  * Code to be executed when a module is installed
16  */ 
17 function lesson_install() {
18     return true; 
19 }
22 /**
23  * Given an object containing all the necessary data,
24  * (defined by the form in mod_form.php) this function
25  * will create a new instance and return the id number
26  * of the new instance.
27  *
28  * @param object $lesson Lesson post data from the form
29  * @return int
30  **/
31 function lesson_add_instance($lesson) {
32     global $SESSION, $DB;
34     lesson_process_pre_save($lesson);
36     if (!$lesson->id = $DB->insert_record("lesson", $lesson)) {
37         return false; // bad
38     }
40     lesson_process_post_save($lesson);
42     lesson_grade_item_update($lesson);
44     return $lesson->id;
45 }
47 /**
48  * Given an object containing all the necessary data,
49  * (defined by the form in mod_form.php) this function
50  * will update an existing instance with new data.
51  *
52  * @param object $lesson Lesson post data from the form
53  * @return boolean
54  **/
55 function lesson_update_instance($lesson) {
56     global $DB;
58     $lesson->id = $lesson->instance;
60     lesson_process_pre_save($lesson);
62     if (!$result = $DB->update_record("lesson", $lesson)) {
63         return false; // Awe man!
64     }
66     lesson_process_post_save($lesson);
68     // update grade item definition
69     lesson_grade_item_update($lesson);
71     // update grades - TODO: do it only when grading style changes
72     lesson_update_grades($lesson, 0, false);
74     return $result;
75 }
78 /*******************************************************************/
79 function lesson_delete_instance($id) {
80     global $DB;
81 /// Given an ID of an instance of this module,
82 /// this function will permanently delete the instance
83 /// and any data that depends on it.
85     if (! $lesson = $DB->get_record("lesson", array("id"=>$id))) {
86         return false;
87     }
89     $result = true;
91     if (! $DB->delete_records("lesson", array("id"=>$lesson->id))) {
92         $result = false;
93     }
94     if (! $DB->delete_records("lesson_pages", array("lessonid"=>$lesson->id))) {
95         $result = false;
96     }
97     if (! $DB->delete_records("lesson_answers", array("lessonid"=>$lesson->id))) {
98         $result = false;
99     }
100     if (! $DB->delete_records("lesson_attempts", array("lessonid"=>$lesson->id))) {
101         $result = false;
102     }
103     if (! $DB->delete_records("lesson_grades", array("lessonid"=>$lesson->id))) {
104         $result = false;
105     }
106     if (! $DB->delete_records("lesson_timer", array("lessonid"=>$lesson->id))) {
107             $result = false;
108     }
109     if (! $DB->delete_records("lesson_branch", array("lessonid"=>$lesson->id))) {
110             $result = false;
111     }
112     if (! $DB->delete_records("lesson_high_scores", array("lessonid"=>$lesson->id))) {
113             $result = false;
114     }
115     if ($events = $DB->get_records('event', array("modulename"=>'lesson', "instance"=>$lesson->id))) {
116         foreach($events as $event) {
117             delete_event($event->id);
118         }
119     }
120     $pagetypes = page_import_types('mod/lesson/');
121     foreach ($pagetypes as $pagetype) {
122         if (!$DB->delete_records('block_instance', array('pageid'=>$lesson->id, 'pagetype'=>$pagetype))) {
123             $result = false;
124         }
125     }
127     lesson_grade_item_delete($lesson);
129     return $result;
132 /**
133  * Given a course object, this function will clean up anything that
134  * would be leftover after all the instances were deleted.
135  *
136  * As of now, this function just cleans the lesson_default table
137  *
138  * @param object $course an object representing the course that is being deleted
139  * @param boolean $feedback to specify if the process must output a summary of its work
140  * @return boolean
141  */
142 function lesson_delete_course($course, $feedback=true) {
143     global $DB;
145     $count = $DB->count_records('lesson_default', array('course'=>$course->id));
146     $DB->delete_records('lesson_default', array('course' => $course->id));
148     //Inform about changes performed if feedback is enabled
149     if ($feedback) {
150         notify(get_string('deletedefaults', 'lesson', $count));
151     }
153     return true;
156 /*******************************************************************/
157 function lesson_user_outline($course, $user, $mod, $lesson) {
158 /// Return a small object with summary information about what a
159 /// user has done with a given particular instance of this module
160 /// Used for user activity reports.
161 /// $return->time = the time they did it
162 /// $return->info = a short text description
163     global $DB;
164     
165     $params = array ("lessonid" => $lesson->id, "userid" => $user->id);
166     if ($grades = $DB->get_records_select("lesson_grades", "lessonid = :lessonid AND userid = :userid", $params,
167                 "grade DESC")) {
168         foreach ($grades as $grade) {
169             $max_grade = number_format($grade->grade * $lesson->grade / 100.0, 1);
170             break;
171         }
172         $return->time = $grade->completed;
173         if ($lesson->retake) {
174             $return->info = get_string("gradeis", "lesson", $max_grade)." (".
175                 get_string("attempt", "lesson", count($grades)).")";
176         } else {
177             $return->info = get_string("gradeis", "lesson", $max_grade);
178         }
179     } else {
180         $return->info = get_string("no")." ".get_string("attempts", "lesson");
181     }
182     return $return;
185 /*******************************************************************/
186 function lesson_user_complete($course, $user, $mod, $lesson) {
187 /// Print a detailed representation of what a  user has done with
188 /// a given particular instance of this module, for user activity reports.
189     global $DB;
190     
191     $params = array ("lessonid" => $lesson->id, "userid" => $user->id);
192     if ($attempts = $DB->get_records_select("lesson_attempts", "lessonid = :lessonid AND userid = :userid", $params,
193                 "retry, timeseen")) {
194         print_simple_box_start();
195         $table->head = array (get_string("attempt", "lesson"),  get_string("numberofpagesviewed", "lesson"),
196             get_string("numberofcorrectanswers", "lesson"), get_string("time"));
197         $table->width = "100%";
198         $table->align = array ("center", "center", "center", "center");
199         $table->size = array ("*", "*", "*", "*");
200         $table->cellpadding = 2;
201         $table->cellspacing = 0;
203         $retry = 0;
204         $npages = 0;
205         $ncorrect = 0;
207         foreach ($attempts as $attempt) {
208             if ($attempt->retry == $retry) {
209                 $npages++;
210                 if ($attempt->correct) {
211                     $ncorrect++;
212                 }
213                 $timeseen = $attempt->timeseen;
214             } else {
215                 $table->data[] = array($retry + 1, $npages, $ncorrect, userdate($timeseen));
216                 $retry++;
217                 $npages = 1;
218                 if ($attempt->correct) {
219                     $ncorrect = 1;
220                 } else {
221                     $ncorrect = 0;
222                 }
223             }
224         }
225         if ($npages) {
226                 $table->data[] = array($retry + 1, $npages, $ncorrect, userdate($timeseen));
227         }
228         print_table($table);
229         print_simple_box_end();
230         // also print grade summary
231         $params = array ("lessonid" => $lesson->id, "userid" => $user->id);
232         if ($grades = $DB->get_records_select("lesson_grades", "lessonid = :lessonid AND userid = :userid", $params,
233                     "grade DESC")) {
234             foreach ($grades as $grade) {
235                 $max_grade = number_format($grade->grade * $lesson->grade / 100.0, 1);
236                 break;
237             }
238             if ($lesson->retake) {
239                 echo "<p>".get_string("gradeis", "lesson", $max_grade)." (".
240                     get_string("attempts", "lesson").": ".count($grades).")</p>";
241             } else {
242                 echo "<p>".get_string("gradeis", "lesson", $max_grade)."</p>";
243             }
244         }
245     } else {
246         echo get_string("no")." ".get_string("attempts", "lesson");
247     }
250     return true;
253 /**
254  * Prints lesson summaries on MyMoodle Page
255  *
256  * Prints lesson name, due date and attempt information on
257  * lessons that have a deadline that has not already passed
258  * and it is available for taking.
259  *
260  * @param array $courses An array of course objects to get lesson instances from
261  * @param array $htmlarray Store overview output array( course ID => 'lesson' => HTML output )
262  */
263 function lesson_print_overview($courses, &$htmlarray) {
264     global $USER, $CFG, $DB;
266     if (!$lessons = get_all_instances_in_courses('lesson', $courses)) {
267         return;
268     }
270 /// Get Necessary Strings
271     $strlesson       = get_string('modulename', 'lesson');
272     $strnotattempted = get_string('nolessonattempts', 'lesson');
273     $strattempted    = get_string('lessonattempted', 'lesson');
275     $now = time();
276     foreach ($lessons as $lesson) {
277         if ($lesson->deadline != 0                                         // The lesson has a deadline
278             and $lesson->deadline >= $now                                  // And it is before the deadline has been met
279             and ($lesson->available == 0 or $lesson->available <= $now)) { // And the lesson is available
281             // Lesson name
282             if (!$lesson->visible) {
283                 $class = ' class="dimmed"';
284             } else {
285                 $class = '';
286             }
287             $str = print_box("$strlesson: <a$class href=\"$CFG->wwwroot/mod/lesson/view.php?id=$lesson->coursemodule\">".
288                              format_string($lesson->name).'</a>', 'name', '', true);
290             // Deadline
291             $str .= print_box(get_string('lessoncloseson', 'lesson', userdate($lesson->deadline)), 'info', '', true);
293             // Attempt information
294             if (has_capability('mod/lesson:manage', get_context_instance(CONTEXT_MODULE, $lesson->coursemodule))) {
295                 // Number of user attempts
296                 $attempts = $DB->count_records('lesson_attempts', array('lessonid'=>$lesson->id));
297                 $str     .= print_box(get_string('xattempts', 'lesson', $attempts), 'info', '', true);
298             } else {
299                 // Determine if the user has attempted the lesson or not
300                 if ($DB->count_records('lesson_attempts', array('lessonid'=>$lesson->id, 'userid'=>$USER->id))) {
301                     $str .= print_box($strattempted, 'info', '', true);
302                 } else {
303                     $str .= print_box($strnotattempted, 'info', '', true);
304                 }
305             }
306             $str = print_box($str, 'lesson overview', '', true);
308             if (empty($htmlarray[$lesson->course]['lesson'])) {
309                 $htmlarray[$lesson->course]['lesson'] = $str;
310             } else {
311                 $htmlarray[$lesson->course]['lesson'] .= $str;
312             }
313         }
314     }
317 /*******************************************************************/
318 function lesson_cron () {
319 /// Function to be run periodically according to the moodle cron
320 /// This function searches for things that need to be done, such
321 /// as sending out mail, toggling flags etc ...
323     global $CFG;
325     return true;
328 /**
329  * Return grade for given user or all users.
330  *
331  * @param int $lessonid id of lesson
332  * @param int $userid optional user id, 0 means all users
333  * @return array array of grades, false if none
334  */
335 function lesson_get_user_grades($lesson, $userid=0) {
336     global $CFG, $DB;
338     $params = array("lessonid" => $lesson->id,"lessonid2" => $lesson->id);
339     
340     if (isset($userid)) {
341         $params["userid"] = $userid;
342         $params["userid2"] = $userid;
343         $user = "AND u.id = :userid";
344         $fuser = "AND uu.id = :userid2";
345     }
346     else {
347         $user="";
348         $fuser="";
349     }
350     
351     if ($lesson->retake) {
352         if ($lesson->usemaxgrade) {
353             $sql = "SELECT u.id, u.id AS userid, MAX(g.grade) AS rawgrade
354                       FROM {user} u, {lesson_grades} g
355                      WHERE u.id = g.userid AND g.lessonid = :lessonid
356                            $user
357                   GROUP BY u.id";
358         } else {
359             $sql = "SELECT u.id, u.id AS userid, AVG(g.grade) AS rawgrade
360                       FROM {user} u, {lesson_grades} g
361                      WHERE u.id = g.userid AND g.lessonid = :lessonid
362                            $user
363                   GROUP BY u.id";
364         }
365         unset($params['lessonid2']);
366         unset($params['userid2']);
367     } else {
368         // use only first attempts (with lowest id in lesson_grades table)
369         $firstonly = "SELECT uu.id AS userid, MIN(gg.id) AS firstcompleted
370                         FROM {user} uu, {lesson_grades} gg
371                        WHERE uu.id = gg.userid AND gg.lessonid = :lessonid2
372                              $fuser
373                        GROUP BY uu.id";
375         $sql = "SELECT u.id, u.id AS userid, g.grade AS rawgrade
376                   FROM {user} u, {lesson_grades} g, ($firstonly) f
377                  WHERE u.id = g.userid AND g.lessonid = :lessonid
378                        AND g.id = f.firstcompleted AND g.userid=f.userid
379                        $user";
380     }
382     return $DB->get_records_sql($sql, $params);
385 /**
386  * Update grades in central gradebook
387  *
388  * @param object $lesson null means all lessons
389  * @param int $userid specific user only, 0 mean all
390  */
391 function lesson_update_grades($lesson=null, $userid=0, $nullifnone=true) {
392     global $CFG, $DB;
393     if (!function_exists('grade_update')) { //workaround for buggy PHP versions
394         require_once($CFG->libdir.'/gradelib.php');
395     }
397     if ($lesson != null) {
398         if ($grades = lesson_get_user_grades($lesson, $userid)) {
399             lesson_grade_item_update($lesson, $grades);
401         } else if ($userid and $nullifnone) {
402             $grade = new object();
403             $grade->userid   = $userid;
404             $grade->rawgrade = NULL;
405             lesson_grade_item_update($lesson, $grade);
407         } else {
408             lesson_grade_item_update($lesson);
409         }
411     } else {
412         $sql = "SELECT l.*, cm.idnumber as cmidnumber, l.course as courseid
413                   FROM {lesson} l, {course_modules} cm, {modules} m
414                  WHERE m.name='lesson' AND m.id=cm.module AND cm.instance=l.id";
415         if ($rs = $DB->get_recordset_sql($sql)) {
416             foreach ($rs as $lesson) {
417                 if ($lesson->grade != 0) {
418                     lesson_update_grades($lesson, 0, false);
419                 } else {
420                     lesson_grade_item_update($lesson);
421                 }
422             }
423             $rs->close();
424         }
425     }
428 /**
429  * Create grade item for given lesson
430  *
431  * @param object $lesson object with extra cmidnumber
432  * @param mixed optional array/object of grade(s); 'reset' means reset grades in gradebook
433  * @return int 0 if ok, error code otherwise
434  */
435 function lesson_grade_item_update($lesson, $grades=NULL) {
436     global $CFG;
437     if (!function_exists('grade_update')) { //workaround for buggy PHP versions
438         require_once($CFG->libdir.'/gradelib.php');
439     }
441     if (array_key_exists('cmidnumber', $lesson)) { //it may not be always present
442         $params = array('itemname'=>$lesson->name, 'idnumber'=>$lesson->cmidnumber);
443     } else {
444         $params = array('itemname'=>$lesson->name);
445     }
447     if ($lesson->grade > 0) {
448         $params['gradetype']  = GRADE_TYPE_VALUE;
449         $params['grademax']   = 100; //means 100%
450         $params['grademin']   = 0;
451         $params['multfactor'] = $lesson->grade / 100.0;
453     } else {
454         $params['gradetype']  = GRADE_TYPE_NONE;
455         $params['multfactor'] = 1.0;
456     }
458     if ($grades  === 'reset') {
459         $params['reset'] = true;
460         $grades = NULL;
461     }
463     return grade_update('mod/lesson', $lesson->course, 'mod', 'lesson', $lesson->id, 0, $grades, $params);
466 /**
467  * Delete grade item for given lesson
468  *
469  * @param object $lesson object
470  * @return object lesson
471  */
472 function lesson_grade_item_delete($lesson) {
473     global $CFG;
474     require_once($CFG->libdir.'/gradelib.php');
476     return grade_update('mod/lesson', $lesson->course, 'mod', 'lesson', $lesson->id, 0, NULL, array('deleted'=>1));
480 /*******************************************************************/
481 function lesson_get_participants($lessonid) {
482 //Must return an array of user records (all data) who are participants
483 //for a given instance of lesson. Must include every user involved
484 //in the instance, independient of his role (student, teacher, admin...)
486     global $CFG, $DB;
488     //Get students
489     $params = array ("lessonid" => $lessonid);
490     $students = $DB->get_records_sql("SELECT DISTINCT u.id, u.id
491                                  FROM {user} u,
492                                       {lesson_attempts} a
493                                  WHERE a.lessonid = :lessonid and
494                                        u.id = a.userid", $params);
496     //Return students array (it contains an array of unique users)
497     return ($students);
500 function lesson_get_view_actions() {
501     return array('view','view all');
504 function lesson_get_post_actions() {
505     return array('end','start', 'update grade attempt');
508 /**
509  * Runs any processes that must run before
510  * a lesson insert/update
511  *
512  * @param object $lesson Lesson form data
513  * @return void
514  **/
515 function lesson_process_pre_save(&$lesson) {
516     global $DB;
517     
518     $lesson->timemodified = time();
520     if (empty($lesson->timed)) {
521         $lesson->timed = 0;
522     }
523     if (empty($lesson->timespent) or !is_numeric($lesson->timespent) or $lesson->timespent < 0) {
524         $lesson->timespent = 0;
525     }
526     if (!isset($lesson->completed)) {
527         $lesson->completed = 0;
528     }
529     if (empty($lesson->gradebetterthan) or !is_numeric($lesson->gradebetterthan) or $lesson->gradebetterthan < 0) {
530         $lesson->gradebetterthan = 0;
531     } else if ($lesson->gradebetterthan > 100) {
532         $lesson->gradebetterthan = 100;
533     }
535     // Conditions for dependency
536     $conditions = new stdClass;
537     $conditions->timespent = $lesson->timespent;
538     $conditions->completed = $lesson->completed;
539     $conditions->gradebetterthan = $lesson->gradebetterthan;
540     $lesson->conditions = serialize($conditions);
541     unset($lesson->timespent);
542     unset($lesson->completed);
543     unset($lesson->gradebetterthan);
545     if (!empty($lesson->password)) {
546         $lesson->password = md5($lesson->password);
547     } else {
548         unset($lesson->password);
549     }
551     if ($lesson->lessondefault) {
552         $default = new stdClass;
553         $default = clone($lesson);
554         unset($default->name);
555         unset($default->timemodified);
556         unset($default->available);
557         unset($default->deadline);
558         if ($default->id = $DB->get_field('lesson_default', 'id', array('course' => $default->course))) {
559             $DB->update_record('lesson_default', $default);
560         } else {
561             $DB->insert_record('lesson_default', $default);
562         }
563     }
564     unset($lesson->lessondefault);
567 /**
568  * Runs any processes that must be run
569  * after a lesson insert/update
570  *
571  * @param object $lesson Lesson form data
572  * @return void
573  **/
574 function lesson_process_post_save(&$lesson) {
575     global $DB;
577     if ($events = $DB->get_records('event', array('modulename'=>'lesson', 'instance'=>$lesson->id))) {
578         foreach($events as $event) {
579             delete_event($event->id);
580         }
581     }
583     $event = new stdClass;
584     $event->description = $lesson->name;
585     $event->courseid    = $lesson->course;
586     $event->groupid     = 0;
587     $event->userid      = 0;
588     $event->modulename  = 'lesson';
589     $event->instance    = $lesson->id;
590     $event->eventtype   = 'open';
591     $event->timestart   = $lesson->available;
592     
593     $event->visible     = instance_is_visible('lesson', $lesson);
594    
595     $event->timeduration = ($lesson->deadline - $lesson->available);
597     if ($lesson->deadline and $lesson->available and $event->timeduration <= LESSON_MAX_EVENT_LENGTH) {
598         // Single event for the whole lesson.
599         $event->name = $lesson->name;
600         add_event($event);
601     } else {
602         // Separate start and end events.
603         $event->timeduration  = 0;
604         if ($lesson->available) {
605             $event->name = $lesson->name.' ('.get_string('lessonopens', 'lesson').')';
606             add_event($event);
607             unset($event->id); // So we can use the same object for the close event.
608         }
609         if ($lesson->deadline) {
610             $event->name      = $lesson->name.' ('.get_string('lessoncloses', 'lesson').')';
611             $event->timestart = $lesson->deadline;
612             $event->eventtype = 'close';
613             add_event($event);
614         }
615     }
619 /**
620  * Implementation of the function for printing the form elements that control
621  * whether the course reset functionality affects the lesson.
622  * @param $mform form passed by reference
623  */
624 function lesson_reset_course_form_definition(&$mform) {
625     $mform->addElement('header', 'lessonheader', get_string('modulenameplural', 'lesson'));
626     $mform->addElement('advcheckbox', 'reset_lesson', get_string('deleteallattempts','lesson'));
629 /**
630  * Course reset form defaults.
631  */
632 function lesson_reset_course_form_defaults($course) {
633     return array('reset_lesson'=>1);
636 /**
637  * Removes all grades from gradebook
638  * @param int $courseid
639  * @param string optional type
640  */
641 function lesson_reset_gradebook($courseid, $type='') {
642     global $CFG, $DB;
644     $sql = "SELECT l.*, cm.idnumber as cmidnumber, l.course as courseid
645               FROM {lesson} l, {course_modules} cm, {modules} m
646              WHERE m.name='lesson' AND m.id=cm.module AND cm.instance=l.id AND l.course=:course";
647     $params = array ("course" => $courseid);
648     if ($lessons = $DB->get_records_sql($sql,$params)) {
649         foreach ($lessons as $lesson) {
650             lesson_grade_item_update($lesson, 'reset');
651         }
652     }
655 /**
656  * Actual implementation of the rest coures functionality, delete all the
657  * lesson attempts for course $data->courseid.
658  * @param $data the data submitted from the reset course.
659  * @return array status array
660  */
661 function lesson_reset_userdata($data) {
662     global $CFG, $DB;
664     $componentstr = get_string('modulenameplural', 'lesson');
665     $status = array();
667     if (!empty($data->reset_lesson)) {
668         $lessonssql = "SELECT l.id
669                          FROM {lesson} l
670                         WHERE l.course=:course";
672         $params = array ("course" => $data->courseid);
673         $DB->delete_records_select('lesson_timer', "lessonid IN ($lessonssql)", $params);
674         $DB->delete_records_select('lesson_high_scores', "lessonid IN ($lessonssql)", $params);
675         $DB->delete_records_select('lesson_grades', "lessonid IN ($lessonssql)", $params);
676         $DB->delete_records_select('lesson_attempts', "lessonid IN ($lessonssql)", $params);
678         // remove all grades from gradebook
679         if (empty($data->reset_gradebook_grades)) {
680             lesson_reset_gradebook($data->courseid);
681         }
683         $status[] = array('component'=>$componentstr, 'item'=>get_string('deleteallattempts', 'lesson'), 'error'=>false);
684     }
686     /// updating dates - shift may be negative too
687     if ($data->timeshift) {
688         shift_course_mod_dates('lesson', array('available', 'deadline'), $data->timeshift, $data->courseid);
689         $status[] = array('component'=>$componentstr, 'item'=>get_string('datechanged'), 'error'=>false);
690     }
692     return $status;
695 /**
696  * Returns all other caps used in module
697  */
698 function lesson_get_extra_capabilities() {
699     return array('moodle/site:accessallgroups');
702 /**
703  * @param string $feature FEATURE_xx constant for requested feature
704  * @return mixed True if module supports feature, null if doesn't know
705  */
706 function lesson_supports($feature) {
707     switch($feature) {
708         case FEATURE_COMPLETION_TRACKS_VIEWS: return true;
709         case FEATURE_GRADE_HAS_GRADE: return true;
710         default: return null;
711     }
714 ?>