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  * Prints lesson summaries on MyMoodle Page
 237  *
 238  * Prints lesson name, due date and attempt information on
 239  * lessons that have a deadline that has not already passed
 240  * and it is available for taking.
 241  *
 242  * @param array $courses An array of course objects to get lesson instances from
 243  * @param array $htmlarray Store overview output array( course ID => 'lesson' => HTML output )
 244  */
 245 function lesson_print_overview($courses, &$htmlarray) {
 246     global $USER, $CFG;
 247
 248     if (!$lessons = get_all_instances_in_courses('lesson', $courses)) {
 249         return;
 250     }
 251
 252 /// Get Necessary Strings
 253     $strlesson       = get_string('modulename', 'lesson');
 254     $strnotattempted = get_string('nolessonattempts', 'lesson');
 255     $strattempted    = get_string('lessonattempted', 'lesson');
 256
 257     $now = time();
 258     foreach ($lessons as $lesson) {
 259         if ($lesson->deadline != 0                                         // The lesson has a deadline
 260             and $lesson->deadline >= $now                                  // And it is before the deadline has been met
 261             and ($lesson->available == 0 or $lesson->available <= $now)) { // And the lesson is available
 262
 263             // Lesson name
 264             if (!$lesson->visible) {
 265                 $class = ' class="dimmed"';
 266             } else {
 267                 $class = '';
 268             }
 269             $str = print_box("$strlesson: <a$class href=\"$CFG->wwwroot/mod/lesson/view.php?id=$lesson->coursemodule\">".
 270                              format_string($lesson->name).'</a>', 'name', '', true);
 271
 272             // Deadline
 273             $str .= print_box(get_string('lessoncloseson', 'lesson', userdate($lesson->deadline)), 'info', '', true);
 274
 275             // Attempt information
 276             if (has_capability('mod/lesson:manage', get_context_instance(CONTEXT_MODULE, $lesson->coursemodule))) {
 277                 // Number of user attempts
 278                 $attempts = count_records('lesson_attempts', 'lessonid', $lesson->id);
 279                 $str     .= print_box(get_string('xattempts', 'lesson', $attempts), 'info', '', true);
 280             } else {
 281                 // Determine if the user has attempted the lesson or not
 282                 if (count_records('lesson_attempts', 'lessonid', $lesson->id, 'userid', $USER->id)) {
 283                     $str .= print_box($strattempted, 'info', '', true);
 284                 } else {
 285                     $str .= print_box($strnotattempted, 'info', '', true);
 286                 }
 287             }
 288             $str = print_box($str, 'lesson overview', '', true);
 289
 290             if (empty($htmlarray[$lesson->course]['lesson'])) {
 291                 $htmlarray[$lesson->course]['lesson'] = $str;
 292             } else {
 293                 $htmlarray[$lesson->course]['lesson'] .= $str;
 294             }
 295         }
 296     }
 297 }
 298
 299 /*******************************************************************/
 300 function lesson_cron () {
 301 /// Function to be run periodically according to the moodle cron
 302 /// This function searches for things that need to be done, such
 303 /// as sending out mail, toggling flags etc ...
 304
 305     global $CFG;
 306
 307     return true;
 308 }
 309
 310 /**
 311  * Return grade for given user or all users.
 312  *
 313  * @param int $lessonid id of lesson
 314  * @param int $userid optional user id, 0 means all users
 315  * @return array array of grades, false if none
 316  */
 317 function lesson_get_user_grades($lesson, $userid=0) {
 318     global $CFG;
 319
 320     $user = $userid ? "AND u.id = $userid" : "";
 321     $fuser = $userid ? "AND uu.id = $userid" : "";
 322
 323     if ($lesson->retake) {
 324         if ($lesson->usemaxgrade) {
 325             $sql = "SELECT u.id, u.id AS userid, MAX(g.grade) AS rawgrade
 326                       FROM {$CFG->prefix}user u, {$CFG->prefix}lesson_grades g
 327                      WHERE u.id = g.userid AND g.lessonid = $lesson->id
 328                            $user
 329                   GROUP BY u.id";
 330         } else {
 331             $sql = "SELECT u.id, u.id AS userid, AVG(g.grade) AS rawgrade
 332                       FROM {$CFG->prefix}user u, {$CFG->prefix}lesson_grades g
 333                      WHERE u.id = g.userid AND g.lessonid = $lesson->id
 334                            $user
 335                   GROUP BY u.id";
 336         }
 337
 338     } else {
 339         // use only first attempts (with lowest id in lesson_grades table)
 340         $firstonly = "SELECT uu.id AS userid, MIN(gg.id) AS firstcompleted
 341                         FROM {$CFG->prefix}user uu, {$CFG->prefix}lesson_grades gg
 342                        WHERE uu.id = gg.userid AND gg.lessonid = $lesson->id
 343                              $fuser
 344                        GROUP BY uu.id";
 345
 346         $sql = "SELECT u.id, u.id AS userid, g.grade AS rawgrade
 347                   FROM {$CFG->prefix}user u, {$CFG->prefix}lesson_grades g, ($firstonly) f
 348                  WHERE u.id = g.userid AND g.lessonid = $lesson->id
 349                        AND g.id = f.firstcompleted AND g.userid=f.userid
 350                        $user";
 351     }
 352
 353     return get_records_sql($sql);
 354 }
 355
 356 /**
 357  * Update grades in central gradebook
 358  *
 359  * @param object $lesson null means all lessons
 360  * @param int $userid specific user only, 0 mean all
 361  */
 362 function lesson_update_grades($lesson=null, $userid=0, $nullifnone=true) {
 363     global $CFG;
 364     if (!function_exists('grade_update')) { //workaround for buggy PHP versions
 365         require_once($CFG->libdir.'/gradelib.php');
 366     }
 367
 368     if ($lesson != null) {
 369         if ($grades = lesson_get_user_grades($lesson, $userid)) {
 370             lesson_grade_item_update($lesson, $grades);
 371
 372         } else if ($userid and $nullifnone) {
 373             $grade = new object();
 374             $grade->userid   = $userid;
 375             $grade->rawgrade = NULL;
 376             lesson_grade_item_update($lesson, $grade);
 377
 378         } else {
 379             lesson_grade_item_update($lesson);
 380         }
 381
 382     } else {
 383         $sql = "SELECT l.*, cm.idnumber as cmidnumber, l.course as courseid
 384                   FROM {$CFG->prefix}lesson l, {$CFG->prefix}course_modules cm, {$CFG->prefix}modules m
 385                  WHERE m.name='lesson' AND m.id=cm.module AND cm.instance=l.id";
 386         if ($rs = get_recordset_sql($sql)) {
 387             while ($lesson = rs_fetch_next_record($rs)) {
 388                 if ($lesson->grade != 0) {
 389                     lesson_update_grades($lesson, 0, false);
 390                 } else {
 391                     lesson_grade_item_update($lesson);
 392                 }
 393             }
 394             rs_close($rs);
 395         }
 396     }
 397 }
 398
 399 /**
 400  * Create grade item for given lesson
 401  *
 402  * @param object $lesson object with extra cmidnumber
 403  * @param mixed optional array/object of grade(s); 'reset' means reset grades in gradebook
 404  * @return int 0 if ok, error code otherwise
 405  */
 406 function lesson_grade_item_update($lesson, $grades=NULL) {
 407     global $CFG;
 408     if (!function_exists('grade_update')) { //workaround for buggy PHP versions
 409         require_once($CFG->libdir.'/gradelib.php');
 410     }
 411
 412     if (array_key_exists('cmidnumber', $lesson)) { //it may not be always present
 413         $params = array('itemname'=>$lesson->name, 'idnumber'=>$lesson->cmidnumber);
 414     } else {
 415         $params = array('itemname'=>$lesson->name);
 416     }
 417
 418     if ($lesson->grade > 0) {
 419         $params['gradetype']  = GRADE_TYPE_VALUE;
 420         $params['grademax']   = 100; //means 100%
 421         $params['grademin']   = 0;
 422         $params['multfactor'] = $lesson->grade / 100.0;
 423
 424     } else {
 425         $params['gradetype']  = GRADE_TYPE_NONE;
 426         $params['multfactor'] = 1.0;
 427     }
 428
 429     if ($grades  === 'reset') {
 430         $params['reset'] = true;
 431         $grades = NULL;
 432     }
 433
 434     return grade_update('mod/lesson', $lesson->course, 'mod', 'lesson', $lesson->id, 0, $grades, $params);
 435 }
 436
 437 /**
 438  * Delete grade item for given lesson
 439  *
 440  * @param object $lesson object
 441  * @return object lesson
 442  */
 443 function lesson_grade_item_delete($lesson) {
 444     global $CFG;
 445     require_once($CFG->libdir.'/gradelib.php');
 446
 447     return grade_update('mod/lesson', $lesson->course, 'mod', 'lesson', $lesson->id, 0, NULL, array('deleted'=>1));
 448 }
 449
 450
 451 /*******************************************************************/
 452 function lesson_get_participants($lessonid) {
 453 //Must return an array of user records (all data) who are participants
 454 //for a given instance of lesson. Must include every user involved
 455 //in the instance, independient of his role (student, teacher, admin...)
 456
 457     global $CFG;
 458
 459     //Get students
 460     $students = get_records_sql("SELECT DISTINCT u.id, u.id
 461                                  FROM {$CFG->prefix}user u,
 462                                       {$CFG->prefix}lesson_attempts a
 463                                  WHERE a.lessonid = '$lessonid' and
 464                                        u.id = a.userid");
 465
 466     //Return students array (it contains an array of unique users)
 467     return ($students);
 468 }
 469
 470 function lesson_get_view_actions() {
 471     return array('view','view all');
 472 }
 473
 474 function lesson_get_post_actions() {
 475     return array('end','start', 'update grade attempt');
 476 }
 477
 478 /**
 479  * Runs any processes that must run before
 480  * a lesson insert/update
 481  *
 482  * @param object $lesson Lesson form data
 483  * @return void
 484  **/
 485 function lesson_process_pre_save(&$lesson) {
 486     $lesson->timemodified = time();
 487
 488     if (empty($lesson->timed)) {
 489         $lesson->timed = 0;
 490     }
 491     if (empty($lesson->timespent) or !is_numeric($lesson->timespent) or $lesson->timespent < 0) {
 492         $lesson->timespent = 0;
 493     }
 494     if (!isset($lesson->completed)) {
 495         $lesson->completed = 0;
 496     }
 497     if (empty($lesson->gradebetterthan) or !is_numeric($lesson->gradebetterthan) or $lesson->gradebetterthan < 0) {
 498         $lesson->gradebetterthan = 0;
 499     } else if ($lesson->gradebetterthan > 100) {
 500         $lesson->gradebetterthan = 100;
 501     }
 502
 503     // Conditions for dependency
 504     $conditions = new stdClass;
 505     $conditions->timespent = $lesson->timespent;
 506     $conditions->completed = $lesson->completed;
 507     $conditions->gradebetterthan = $lesson->gradebetterthan;
 508     $lesson->conditions = addslashes(serialize($conditions));
 509     unset($lesson->timespent);
 510     unset($lesson->completed);
 511     unset($lesson->gradebetterthan);
 512
 513     if (!empty($lesson->password)) {
 514         $lesson->password = md5($lesson->password);
 515     } else {
 516         unset($lesson->password);
 517     }
 518
 519     if ($lesson->lessondefault) {
 520         $default = new stdClass;
 521         $default = clone($lesson);
 522         unset($default->name);
 523         unset($default->timemodified);
 524         unset($default->available);
 525         unset($default->deadline);
 526         if ($default->id = get_field('lesson_default', 'id', 'course', $default->course)) {
 527             update_record('lesson_default', $default);
 528         } else {
 529             insert_record('lesson_default', $default);
 530         }
 531     }
 532     unset($lesson->lessondefault);
 533 }
 534
 535 /**
 536  * Runs any processes that must be run
 537  * after a lesson insert/update
 538  *
 539  * @param object $lesson Lesson form data
 540  * @return void
 541  **/
 542 function lesson_process_post_save(&$lesson) {
 543     if ($events = get_records_select('event', "modulename = 'lesson' and instance = '$lesson->id'")) {
 544         foreach($events as $event) {
 545             delete_event($event->id);
 546         }
 547     }
 548
 549     $event = new stdClass;
 550     $event->description = $lesson->name;
 551     $event->courseid    = $lesson->course;
 552     $event->groupid     = 0;
 553     $event->userid      = 0;
 554     $event->modulename  = 'lesson';
 555     $event->instance    = $lesson->id;
 556     $event->eventtype   = 'open';
 557     $event->timestart   = $lesson->available;
 558     $event->visible     = instance_is_visible('lesson', $lesson);
 559     $event->timeduration = ($lesson->deadline - $lesson->available);
 560
 561     if ($lesson->deadline and $lesson->available and $event->timeduration <= LESSON_MAX_EVENT_LENGTH) {
 562         // Single event for the whole lesson.
 563         $event->name = $lesson->name;
 564         add_event($event);
 565     } else {
 566         // Separate start and end events.
 567         $event->timeduration  = 0;
 568         if ($lesson->available) {
 569             $event->name = $lesson->name.' ('.get_string('lessonopens', 'lesson').')';
 570             add_event($event);
 571             unset($event->id); // So we can use the same object for the close event.
 572         }
 573         if ($lesson->deadline) {
 574             $event->name      = $lesson->name.' ('.get_string('lessoncloses', 'lesson').')';
 575             $event->timestart = $lesson->deadline;
 576             $event->eventtype = 'close';
 577             add_event($event);
 578         }
 579     }
 580 }
 581
 582
 583 /**
 584  * Implementation of the function for printing the form elements that control
 585  * whether the course reset functionality affects the lesson.
 586  * @param $mform form passed by reference
 587  */
 588 function lesson_reset_course_form_definition(&$mform) {
 589     $mform->addElement('header', 'lessonheader', get_string('modulenameplural', 'lesson'));
 590     $mform->addElement('advcheckbox', 'reset_lesson', get_string('deleteallattempts','lesson'));
 591 }
 592
 593 /**
 594  * Course reset form defaults.
 595  */
 596 function lesson_reset_course_form_defaults($course) {
 597     return array('reset_lesson'=>1);
 598 }
 599
 600 /**
 601  * Removes all grades from gradebook
 602  * @param int $courseid
 603  * @param string optional type
 604  */
 605 function lesson_reset_gradebook($courseid, $type='') {
 606     global $CFG;
 607
 608     $sql = "SELECT l.*, cm.idnumber as cmidnumber, l.course as courseid
 609               FROM {$CFG->prefix}lesson l, {$CFG->prefix}course_modules cm, {$CFG->prefix}modules m
 610              WHERE m.name='lesson' AND m.id=cm.module AND cm.instance=l.id AND l.course=$courseid";
 611
 612     if ($lessons = get_records_sql($sql)) {
 613         foreach ($lessons as $lesson) {
 614             lesson_grade_item_update($lesson, 'reset');
 615         }
 616     }
 617 }
 618
 619 /**
 620  * Actual implementation of the rest coures functionality, delete all the
 621  * lesson attempts for course $data->courseid.
 622  * @param $data the data submitted from the reset course.
 623  * @return array status array
 624  */
 625 function lesson_reset_userdata($data) {
 626     global $CFG;
 627
 628     $componentstr = get_string('modulenameplural', 'lesson');
 629     $status = array();
 630
 631     if (!empty($data->reset_lesson)) {
 632         $lessonssql = "SELECT l.id
 633                          FROM {$CFG->prefix}lesson l
 634                         WHERE l.course={$data->courseid}";
 635
 636
 637         delete_records_select('lesson_timer', "lessonid IN ($lessonssql)");
 638         delete_records_select('lesson_high_scores', "lessonid IN ($lessonssql)");
 639         delete_records_select('lesson_grades', "lessonid IN ($lessonssql)");
 640         delete_records_select('lesson_attempts', "lessonid IN ($lessonssql)");
 641
 642         // remove all grades from gradebook
 643         if (empty($data->reset_gradebook_grades)) {
 644             lesson_reset_gradebook($data->courseid);
 645         }
 646
 647         $status[] = array('component'=>$componentstr, 'item'=>get_string('deleteallattempts', 'lesson'), 'error'=>false);
 648     }
 649
 650     /// updating dates - shift may be negative too
 651     if ($data->timeshift) {
 652         shift_course_mod_dates('lesson', array('available', 'deadline'), $data->timeshift, $data->courseid);
 653         $status[] = array('component'=>$componentstr, 'item'=>get_string('datechanged'), 'error'=>false);
 654     }
 655
 656     return $status;
 657 }
 658
 659 /**
 660  * Returns all other caps used in module
 661  */
 662 function lesson_get_extra_capabilities() {
 663     return array('moodle/site:accessallgroups');
 664 }
 665
 666 ?>