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  **/
   9
  10 define("LESSON_MAX_EVENT_LENGTH", "432000");   // 5 days maximum
  11
  12 /**
  13  * Given an object containing all the necessary data,
  14  * (defined by the form in mod_form.php) this function
  15  * will create a new instance and return the id number
  16  * of the new instance.
  17  *
  18  * @param object $lesson Lesson post data from the form
  19  * @return int
  20  **/
  21 function lesson_add_instance($lesson) {
  22     global $SESSION;
  23
  24     lesson_process_pre_save($lesson);
  25
  26     if (!$lesson->id = insert_record("lesson", $lesson)) {
  27         return false; // bad
  28     }
  29
  30     lesson_process_post_save($lesson);
  31
  32     lesson_grade_item_update(stripslashes_recursive($lesson));
  33
  34     return $lesson->id;
  35 }
  36
  37 /**
  38  * Given an object containing all the necessary data,
  39  * (defined by the form in mod_form.php) this function
  40  * will update an existing instance with new data.
  41  *
  42  * @param object $lesson Lesson post data from the form
  43  * @return boolean
  44  **/
  45 function lesson_update_instance($lesson) {
  46
  47     $lesson->id = $lesson->instance;
  48
  49     lesson_process_pre_save($lesson);
  50
  51     if (!$result = update_record("lesson", $lesson)) {
  52         return false; // Awe man!
  53     }
  54
  55     lesson_process_post_save($lesson);
  56
  57     // update grade item definition
  58     lesson_grade_item_update(stripslashes_recursive($lesson));
  59
  60     // update grades - TODO: do it only when grading style changes
  61     lesson_update_grades(stripslashes_recursive($lesson), 0, false);
  62
  63     return $result;
  64 }
  65
  66
  67 /*******************************************************************/
  68 function lesson_delete_instance($id) {
  69 /// Given an ID of an instance of this module,
  70 /// this function will permanently delete the instance
  71 /// and any data that depends on it.
  72
  73     if (! $lesson = get_record("lesson", "id", "$id")) {
  74         return false;
  75     }
  76
  77     $result = true;
  78
  79     if (! delete_records("lesson", "id", "$lesson->id")) {
  80         $result = false;
  81     }
  82     if (! delete_records("lesson_pages", "lessonid", "$lesson->id")) {
  83         $result = false;
  84     }
  85     if (! delete_records("lesson_answers", "lessonid", "$lesson->id")) {
  86         $result = false;
  87     }
  88     if (! delete_records("lesson_attempts", "lessonid", "$lesson->id")) {
  89         $result = false;
  90     }
  91     if (! delete_records("lesson_grades", "lessonid", "$lesson->id")) {
  92         $result = false;
  93     }
  94     if (! delete_records("lesson_timer", "lessonid", "$lesson->id")) {
  95             $result = false;
  96     }
  97     if (! delete_records("lesson_branch", "lessonid", "$lesson->id")) {
  98             $result = false;
  99     }
 100     if (! delete_records("lesson_high_scores", "lessonid", "$lesson->id")) {
 101             $result = false;
 102     }
 103     if ($events = get_records_select('event', "modulename = 'lesson' and instance = '$lesson->id'")) {
 104         foreach($events as $event) {
 105             delete_event($event->id);
 106         }
 107     }
 108     $pagetypes = page_import_types('mod/lesson/');
 109     foreach ($pagetypes as $pagetype) {
 110         if (!delete_records('block_instance', 'pageid', $lesson->id, 'pagetype', $pagetype)) {
 111             $result = false;
 112         }
 113     }
 114
 115     lesson_grade_item_delete($lesson);
 116
 117     return $result;
 118 }
 119
 120 /**
 121  * Given a course object, this function will clean up anything that
 122  * would be leftover after all the instances were deleted.
 123  *
 124  * As of now, this function just cleans the lesson_default table
 125  *
 126  * @param object $course an object representing the course that is being deleted
 127  * @param boolean $feedback to specify if the process must output a summary of its work
 128  * @return boolean
 129  */
 130 function lesson_delete_course($course, $feedback=true) {
 131
 132     $count = count_records('lesson_default', 'course', $course->id);
 133     delete_records('lesson_default', 'course', $course->id);
 134
 135     //Inform about changes performed if feedback is enabled
 136     if ($feedback) {
 137         notify(get_string('deletedefaults', 'lesson', $count));
 138     }
 139
 140     return true;
 141 }
 142
 143 /*******************************************************************/
 144 function lesson_user_outline($course, $user, $mod, $lesson) {
 145 /// Return a small object with summary information about what a
 146 /// user has done with a given particular instance of this module
 147 /// Used for user activity reports.
 148 /// $return->time = the time they did it
 149 /// $return->info = a short text description
 150
 151     if ($grades = get_records_select("lesson_grades", "lessonid = $lesson->id AND userid = $user->id",
 152                 "grade DESC")) {
 153         foreach ($grades as $grade) {
 154             $max_grade = number_format($grade->grade * $lesson->grade / 100.0, 1);
 155             break;
 156         }
 157         $return->time = $grade->completed;
 158         if ($lesson->retake) {
 159             $return->info = get_string("gradeis", "lesson", $max_grade)." (".
 160                 get_string("attempt", "lesson", count($grades)).")";
 161         } else {
 162             $return->info = get_string("gradeis", "lesson", $max_grade);
 163         }
 164     } else {
 165         $return->info = get_string("no")." ".get_string("attempts", "lesson");
 166     }
 167     return $return;
 168 }
 169
 170 /*******************************************************************/
 171 function lesson_user_complete($course, $user, $mod, $lesson) {
 172 /// Print a detailed representation of what a  user has done with
 173 /// a given particular instance of this module, for user activity reports.
 174
 175     if ($attempts = get_records_select("lesson_attempts", "lessonid = $lesson->id AND userid = $user->id",
 176                 "retry, timeseen")) {
 177         print_simple_box_start();
 178         $table->head = array (get_string("attempt", "lesson"),  get_string("numberofpagesviewed", "lesson"),
 179             get_string("numberofcorrectanswers", "lesson"), get_string("time"));
 180         $table->width = "100%";
 181         $table->align = array ("center", "center", "center", "center");
 182         $table->size = array ("*", "*", "*", "*");
 183         $table->cellpadding = 2;
 184         $table->cellspacing = 0;
 185
 186         $retry = 0;
 187         $npages = 0;
 188         $ncorrect = 0;
 189
 190         foreach ($attempts as $attempt) {
 191             if ($attempt->retry == $retry) {
 192                 $npages++;
 193                 if ($attempt->correct) {
 194                     $ncorrect++;
 195                 }
 196                 $timeseen = $attempt->timeseen;
 197             } else {
 198                 $table->data[] = array($retry + 1, $npages, $ncorrect, userdate($timeseen));
 199                 $retry++;
 200                 $npages = 1;
 201                 if ($attempt->correct) {
 202                     $ncorrect = 1;
 203                 } else {
 204                     $ncorrect = 0;
 205                 }
 206             }
 207         }
 208         if ($npages) {
 209                 $table->data[] = array($retry + 1, $npages, $ncorrect, userdate($timeseen));
 210         }
 211         print_table($table);
 212         print_simple_box_end();
 213         // also print grade summary
 214         if ($grades = get_records_select("lesson_grades", "lessonid = $lesson->id AND userid = $user->id",
 215                     "grade DESC")) {
 216             foreach ($grades as $grade) {
 217                 $max_grade = number_format($grade->grade * $lesson->grade / 100.0, 1);
 218                 break;
 219             }
 220             if ($lesson->retake) {
 221                 echo "<p>".get_string("gradeis", "lesson", $max_grade)." (".
 222                     get_string("attempts", "lesson").": ".count($grades).")</p>";
 223             } else {
 224                 echo "<p>".get_string("gradeis", "lesson", $max_grade)."</p>";
 225             }
 226         }
 227     } else {
 228         echo get_string("no")." ".get_string("attempts", "lesson");
 229     }
 230
 231
 232     return true;
 233 }
 234
 235 /*******************************************************************/
 236 function lesson_print_recent_activity($course, $isteacher, $timestart) {
 237 /// Given a course and a time, this module should find recent activity
 238 /// that has occurred in lesson activities and print it out.
 239 /// Return true if there was output, or false is there was none.
 240
 241     global $CFG;
 242
 243     return false;  //  True if anything was printed, otherwise false
 244 }
 245
 246 /**
 247  * Prints lesson summaries on MyMoodle Page
 248  *
 249  * Prints lesson name, due date and attempt information on
 250  * lessons that have a deadline that has not already passed
 251  * and it is available for taking.
 252  *
 253  * @param array $courses An array of course objects to get lesson instances from
 254  * @param array $htmlarray Store overview output array( course ID => 'lesson' => HTML output )
 255  */
 256 function lesson_print_overview($courses, &$htmlarray) {
 257     global $USER, $CFG;
 258
 259     if (!$lessons = get_all_instances_in_courses('lesson', $courses)) {
 260         return;
 261     }
 262
 263 /// Get Necessary Strings
 264     $strlesson       = get_string('modulename', 'lesson');
 265     $strnotattempted = get_string('nolessonattempts', 'lesson');
 266     $strattempted    = get_string('lessonattempted', 'lesson');
 267
 268     $now = time();
 269     foreach ($lessons as $lesson) {
 270         if ($lesson->deadline != 0                                         // The lesson has a deadline
 271             and $lesson->deadline >= $now                                  // And it is before the deadline has been met
 272             and ($lesson->available == 0 or $lesson->available <= $now)) { // And the lesson is available
 273
 274             // Lesson name
 275             if (!$lesson->visible) {
 276                 $class = ' class="dimmed"';
 277             } else {
 278                 $class = '';
 279             }
 280             $str = print_box("$strlesson: <a$class href=\"$CFG->wwwroot/mod/lesson/view.php?id=$lesson->coursemodule\">".
 281                              format_string($lesson->name).'</a>', 'name', '', true);
 282
 283             // Deadline
 284             $str .= print_box(get_string('lessoncloseson', 'lesson', userdate($lesson->deadline)), 'info', '', true);
 285
 286             // Attempt information
 287             if (has_capability('mod/lesson:manage', get_context_instance(CONTEXT_MODULE, $lesson->coursemodule))) {
 288                 // Number of user attempts
 289                 $attempts = count_records('lesson_attempts', 'lessonid', $lesson->id);
 290                 $str     .= print_box(get_string('xattempts', 'lesson', $attempts), 'info', '', true);
 291             } else {
 292                 // Determine if the user has attempted the lesson or not
 293                 if (count_records('lesson_attempts', 'lessonid', $lesson->id, 'userid', $USER->id)) {
 294                     $str .= print_box($strattempted, 'info', '', true);
 295                 } else {
 296                     $str .= print_box($strnotattempted, 'info', '', true);
 297                 }
 298             }
 299             $str = print_box($str, 'lesson overview', '', true);
 300
 301             if (empty($htmlarray[$lesson->course]['lesson'])) {
 302                 $htmlarray[$lesson->course]['lesson'] = $str;
 303             } else {
 304                 $htmlarray[$lesson->course]['lesson'] .= $str;
 305             }
 306         }
 307     }
 308 }
 309
 310 /*******************************************************************/
 311 function lesson_cron () {
 312 /// Function to be run periodically according to the moodle cron
 313 /// This function searches for things that need to be done, such
 314 /// as sending out mail, toggling flags etc ...
 315
 316     global $CFG;
 317
 318     return true;
 319 }
 320
 321 /**
 322  * Return grade for given user or all users.
 323  *
 324  * @param int $lessonid id of lesson
 325  * @param int $userid optional user id, 0 means all users
 326  * @return array array of grades, false if none
 327  */
 328 function lesson_get_user_grades($lesson, $userid=0) {
 329     global $CFG;
 330
 331     $user = $userid ? "AND u.id = $userid" : "";
 332     $fuser = $userid ? "AND uu.id = $userid" : "";
 333
 334     if ($lesson->retake) {
 335         if ($lesson->usemaxgrade) {
 336             $sql = "SELECT u.id, u.id AS userid, MAX(g.grade) AS rawgrade
 337                       FROM {$CFG->prefix}user u, {$CFG->prefix}lesson_grades g
 338                      WHERE u.id = g.userid AND g.lessonid = $lesson->id
 339                            $user
 340                   GROUP BY u.id";
 341         } else {
 342             $sql = "SELECT u.id, u.id AS userid, AVG(g.grade) AS rawgrade
 343                       FROM {$CFG->prefix}user u, {$CFG->prefix}lesson_grades g
 344                      WHERE u.id = g.userid AND g.lessonid = $lesson->id
 345                            $user
 346                   GROUP BY u.id";
 347         }
 348
 349     } else {
 350         // use only first attempts (with lowest id in lesson_grades table)
 351         $firstonly = "SELECT uu.id AS userid, MIN(gg.id) AS firstcompleted
 352                         FROM {$CFG->prefix}user uu, {$CFG->prefix}lesson_grades gg
 353                        WHERE uu.id = gg.userid AND gg.lessonid = $lesson->id
 354                              $fuser
 355                        GROUP BY uu.id";
 356
 357         $sql = "SELECT u.id, u.id AS userid, g.grade AS rawgrade
 358                   FROM {$CFG->prefix}user u, {$CFG->prefix}lesson_grades g, ($firstonly) f
 359                  WHERE u.id = g.userid AND g.lessonid = $lesson->id
 360                        AND g.id = f.firstcompleted AND g.userid=f.userid
 361                        $user";
 362     }
 363
 364     return get_records_sql($sql);
 365 }
 366
 367 /**
 368  * Update grades in central gradebook
 369  *
 370  * @param object $lesson null means all lessons
 371  * @param int $userid specific user only, 0 mean all
 372  */
 373 function lesson_update_grades($lesson=null, $userid=0, $nullifnone=true) {
 374     global $CFG;
 375     if (!function_exists('grade_update')) { //workaround for buggy PHP versions
 376         require_once($CFG->libdir.'/gradelib.php');
 377     }
 378
 379     if ($lesson != null) {
 380         if ($grades = lesson_get_user_grades($lesson, $userid)) {
 381             grade_update('mod/lesson', $lesson->course, 'mod', 'lesson', $lesson->id, 0, $grades);
 382
 383         } else if ($userid and $nullifnone) {
 384             $grade = new object();
 385             $grade->userid   = $userid;
 386             $grade->rawgrade = NULL;
 387             grade_update('mod/lesson', $lesson->course, 'mod', 'lesson', $lesson->id, 0, $grade);
 388         }
 389
 390     } else {
 391         $sql = "SELECT l.*, cm.idnumber as cmidnumber, l.course as courseid
 392                   FROM {$CFG->prefix}lesson l, {$CFG->prefix}course_modules cm, {$CFG->prefix}modules m
 393                  WHERE m.name='lesson' AND m.id=cm.module AND cm.instance=l.id";
 394         if ($rs = get_recordset_sql($sql)) {
 395             if ($rs->RecordCount() > 0) {
 396                 while ($lesson = rs_fetch_next_record($rs)) {
 397                     lesson_grade_item_update($lesson);
 398                     if ($lesson->grade != 0) {
 399                         lesson_update_grades($lesson, 0, false);
 400                     }
 401                 }
 402             }
 403             rs_close($rs);
 404         }
 405     }
 406 }
 407
 408 /**
 409  * Create grade item for given lesson
 410  *
 411  * @param object $lesson object with extra cmidnumber
 412  * @return int 0 if ok, error code otherwise
 413  */
 414 function lesson_grade_item_update($lesson) {
 415     global $CFG;
 416     if (!function_exists('grade_update')) { //workaround for buggy PHP versions
 417         require_once($CFG->libdir.'/gradelib.php');
 418     }
 419
 420     if (array_key_exists('cmidnumber', $lesson)) { //it may not be always present
 421         $params = array('itemname'=>$lesson->name, 'idnumber'=>$lesson->cmidnumber);
 422     } else {
 423         $params = array('itemname'=>$lesson->name);
 424     }
 425
 426     if ($lesson->grade > 0) {
 427         $params['gradetype']  = GRADE_TYPE_VALUE;
 428         $params['grademax']   = 100; //means 100%
 429         $params['grademin']   = 0;
 430         $params['multfactor'] = $lesson->grade / 100.0;
 431
 432     } else {
 433         $params['gradetype']  = GRADE_TYPE_NONE;
 434         $params['multfactor'] = 1.0;
 435     }
 436
 437     return grade_update('mod/lesson', $lesson->course, 'mod', 'lesson', $lesson->id, 0, NULL, $params);
 438 }
 439
 440 /**
 441  * Delete grade item for given lesson
 442  *
 443  * @param object $lesson object
 444  * @return object lesson
 445  */
 446 function lesson_grade_item_delete($lesson) {
 447     global $CFG;
 448     require_once($CFG->libdir.'/gradelib.php');
 449
 450     return grade_update('mod/lesson', $lesson->course, 'mod', 'lesson', $lesson->id, 0, NULL, array('deleted'=>1));
 451 }
 452
 453
 454 /*******************************************************************/
 455 function lesson_get_participants($lessonid) {
 456 //Must return an array of user records (all data) who are participants
 457 //for a given instance of lesson. Must include every user involved
 458 //in the instance, independient of his role (student, teacher, admin...)
 459
 460     global $CFG;
 461
 462     //Get students
 463     $students = get_records_sql("SELECT DISTINCT u.id, u.id
 464                                  FROM {$CFG->prefix}user u,
 465                                       {$CFG->prefix}lesson_attempts a
 466                                  WHERE a.lessonid = '$lessonid' and
 467                                        u.id = a.userid");
 468
 469     //Return students array (it contains an array of unique users)
 470     return ($students);
 471 }
 472
 473 function lesson_get_view_actions() {
 474     return array('view','view all');
 475 }
 476
 477 function lesson_get_post_actions() {
 478     return array('end','start', 'update grade attempt');
 479 }
 480
 481 /**
 482  * Runs any processes that must run before
 483  * a lesson insert/update
 484  *
 485  * @param object $lesson Lesson form data
 486  * @return void
 487  **/
 488 function lesson_process_pre_save(&$lesson) {
 489     $lesson->timemodified = time();
 490
 491     if (empty($lesson->timed)) {
 492         $lesson->timed = 0;
 493     }
 494     if (empty($lesson->timespent) or !is_numeric($lesson->timespent) or $lesson->timespent < 0) {
 495         $lesson->timespent = 0;
 496     }
 497     if (!isset($lesson->completed)) {
 498         $lesson->completed = 0;
 499     }
 500     if (empty($lesson->gradebetterthan) or !is_numeric($lesson->gradebetterthan) or $lesson->gradebetterthan < 0) {
 501         $lesson->gradebetterthan = 0;
 502     } else if ($lesson->gradebetterthan > 100) {
 503         $lesson->gradebetterthan = 100;
 504     }
 505
 506     // Conditions for dependency
 507     $conditions = new stdClass;
 508     $conditions->timespent = $lesson->timespent;
 509     $conditions->completed = $lesson->completed;
 510     $conditions->gradebetterthan = $lesson->gradebetterthan;
 511     $lesson->conditions = addslashes(serialize($conditions));
 512     unset($lesson->timespent);
 513     unset($lesson->completed);
 514     unset($lesson->gradebetterthan);
 515
 516     if (!empty($lesson->password)) {
 517         $lesson->password = md5($lesson->password);
 518     } else {
 519         unset($lesson->password);
 520     }
 521
 522     if ($lesson->lessondefault) {
 523         $default = new stdClass;
 524         $default = clone($lesson);
 525         unset($default->name);
 526         unset($default->timemodified);
 527         unset($default->available);
 528         unset($default->deadline);
 529         if ($default->id = get_field('lesson_default', 'id', 'course', $default->course)) {
 530             update_record('lesson_default', $default);
 531         } else {
 532             insert_record('lesson_default', $default);
 533         }
 534     }
 535     unset($lesson->lessondefault);
 536 }
 537
 538 /**
 539  * Runs any processes that must be run
 540  * after a lesson insert/update
 541  *
 542  * @param object $lesson Lesson form data
 543  * @return void
 544  **/
 545 function lesson_process_post_save(&$lesson) {
 546     if ($events = get_records_select('event', "modulename = 'lesson' and instance = '$lesson->id'")) {
 547         foreach($events as $event) {
 548             delete_event($event->id);
 549         }
 550     }
 551
 552     $event = new stdClass;
 553     $event->description = $lesson->name;
 554     $event->courseid    = $lesson->course;
 555     $event->groupid     = 0;
 556     $event->userid      = 0;
 557     $event->modulename  = 'lesson';
 558     $event->instance    = $lesson->id;
 559     $event->eventtype   = 'open';
 560     $event->timestart   = $lesson->available;
 561     $event->visible     = instance_is_visible('lesson', $lesson);
 562     $event->timeduration = ($lesson->deadline - $lesson->available);
 563
 564     if ($lesson->deadline and $lesson->available and $event->timeduration <= LESSON_MAX_EVENT_LENGTH) {
 565         // Single event for the whole lesson.
 566         $event->name = $lesson->name;
 567         add_event($event);
 568     } else {
 569         // Separate start and end events.
 570         $event->timeduration  = 0;
 571         if ($lesson->available) {
 572             $event->name = $lesson->name.' ('.get_string('lessonopens', 'lesson').')';
 573             add_event($event);
 574             unset($event->id); // So we can use the same object for the close event.
 575         }
 576         if ($lesson->deadline) {
 577             $event->name      = $lesson->name.' ('.get_string('lessoncloses', 'lesson').')';
 578             $event->timestart = $lesson->deadline;
 579             $event->eventtype = 'close';
 580             add_event($event);
 581         }
 582     }
 583 }
 584
 585 ?>