lib/gradelib.php

   1 <?php // $Id$
   2
   3 ///////////////////////////////////////////////////////////////////////////
   4 //                                                                       //
   5 // NOTICE OF COPYRIGHT                                                   //
   6 //                                                                       //
   7 // Moodle - Modular Object-Oriented Dynamic Learning Environment         //
   8 //          http://moodle.com                                            //
   9 //                                                                       //
  10 // Copyright (C) 2001-2003  Martin Dougiamas  http://dougiamas.com       //
  11 //                                                                       //
  12 // This program is free software; you can redistribute it and/or modify  //
  13 // it under the terms of the GNU General Public License as published by  //
  14 // the Free Software Foundation; either version 2 of the License, or     //
  15 // (at your option) any later version.                                   //
  16 //                                                                       //
  17 // This program is distributed in the hope that it will be useful,       //
  18 // but WITHOUT ANY WARRANTY; without even the implied warranty of        //
  19 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         //
  20 // GNU General Public License for more details:                          //
  21 //                                                                       //
  22 //          http://www.gnu.org/copyleft/gpl.html                         //
  23 //                                                                       //
  24 ///////////////////////////////////////////////////////////////////////////
  25
  26 /**
  27  * Library of functions for gradebook
  28  *
  29  * @author Moodle HQ developers
  30  * @version  $Id$
  31  * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
  32  * @package moodlecore
  33  */
  34
  35 // category aggregation types
  36 define('GRADE_AGGREGATE_MEAN_ALL', 0);
  37 define('GRADE_AGGREGATE_MEAN_GRADED', 1);
  38 define('GRADE_AGGREGATE_MEDIAN_ALL', 2);
  39 define('GRADE_AGGREGATE_MEDIAN_GRADED', 3);
  40 define('GRADE_AGGREGATE_MIN_ALL', 4);
  41 define('GRADE_AGGREGATE_MIN_GRADED', 5);
  42 define('GRADE_AGGREGATE_MAX_ALL', 6);
  43 define('GRADE_AGGREGATE_MAX_GRADED', 7);
  44 define('GRADE_AGGREGATE_MODE_ALL', 8);
  45 define('GRADE_AGGREGATE_MODE_GRADED', 9);
  46 define('GRADE_AGGREGATE_WEIGHTED_MEAN_ALL', 10);
  47 define('GRADE_AGGREGATE_WEIGHTED_MEAN_GRADED', 11);
  48 define('GRADE_AGGREGATE_EXTRACREDIT_MEAN_ALL', 12);
  49 define('GRADE_AGGREGATE_EXTRACREDIT_MEAN_GRADED', 13);
  50
  51 // grade types
  52 define('GRADE_TYPE_NONE', 0);
  53 define('GRADE_TYPE_VALUE', 1);
  54 define('GRADE_TYPE_SCALE', 2);
  55 define('GRADE_TYPE_TEXT', 3);
  56
  57 // grade_update() return status
  58 define('GRADE_UPDATE_OK', 0);
  59 define('GRADE_UPDATE_FAILED', 1);
  60 define('GRADE_UPDATE_MULTIPLE', 2);
  61 define('GRADE_UPDATE_ITEM_DELETED', 3);
  62 define('GRADE_UPDATE_ITEM_LOCKED', 4);
  63
  64 // Grate teables history tracking actions
  65 define('GRADE_HISTORY_INSERT', 1);
  66 define('GRADE_HISTORY_UPDATE', 2);
  67 define('GRADE_HISTORY_DELETE', 3);
  68
  69 define('GRADE_REPORT_AGGREGATION_POSITION_LEFT', 0);
  70 define('GRADE_REPORT_AGGREGATION_POSITION_RIGHT', 1);
  71 define('GRADE_REPORT_AGGREGATION_VIEW_FULL', 0);
  72 define('GRADE_REPORT_AGGREGATION_VIEW_AGGREGATES_ONLY', 1);
  73 define('GRADE_REPORT_AGGREGATION_VIEW_GRADES_ONLY', 2);
  74 define('GRADE_REPORT_GRADE_DISPLAY_TYPE_REAL', 0);
  75 define('GRADE_REPORT_GRADE_DISPLAY_TYPE_PERCENTAGE', 1);
  76 define('GRADE_REPORT_GRADE_DISPLAY_TYPE_LETTER', 2);
  77 define('GRADE_REPORT_PREFERENCE_DEFAULT', 'default');
  78 define('GRADE_REPORT_PREFERENCE_INHERIT', 'inherit');
  79 define('GRADE_REPORT_PREFERENCE_UNUSED', -1);
  80
  81 require_once($CFG->libdir . '/grade/grade_category.php');
  82 require_once($CFG->libdir . '/grade/grade_item.php');
  83 require_once($CFG->libdir . '/grade/grade_grade.php');
  84 require_once($CFG->libdir . '/grade/grade_scale.php');
  85 require_once($CFG->libdir . '/grade/grade_outcome.php');
  86 require_once($CFG->libdir . '/grade/grade_grade_text.php');
  87
  88 /***** PUBLIC GRADE API *****/
  89
  90 /**
  91  * Submit new or update grade; update/create grade_item definition. Grade must have userid specified,
  92  * rawgrade and feedback with format are optional. rawgrade NULL means 'Not graded', missing property
  93  * or key means do not change existing.
  94  *
  95  * Only following grade item properties can be changed 'itemname', 'idnumber', 'gradetype', 'grademax',
  96  * 'grademin', 'scaleid', 'multfactor', 'plusfactor', 'deleted'.
  97  *
  98  * @param string $source source of the grade such as 'mod/assignment', often used to prevent infinite loops when processing grade_updated events
  99  * @param int $courseid id of course
 100  * @param string $itemtype type of grade item - mod, block
 101  * @param string $itemmodule more specific then $itemtype - assignment, forum, etc.; maybe NULL for some item types
 102  * @param int $iteminstance instance it of graded subject
 103  * @param int $itemnumber most probably 0, modules can use other numbers when having more than one grades for each user
 104  * @param mixed $grades grade (object, array) or several grades (arrays of arrays or objects), NULL if updating rgade_item definition only\
 105  * @param mixed $itemdetails object or array describing the grading item, NULL if no change
 106  */
 107 function grade_update($source, $courseid, $itemtype, $itemmodule, $iteminstance, $itemnumber, $grades=NULL, $itemdetails=NULL) {
 108     global $USER;
 109
 110     // only following grade_item properties can be changed in this function
 111     $allowed = array('itemname', 'idnumber', 'gradetype', 'grademax', 'grademin', 'scaleid', 'multfactor', 'plusfactor', 'deleted');
 112
 113     // grade item identification
 114     $params = compact('courseid', 'itemtype', 'itemmodule', 'iteminstance', 'itemnumber');
 115
 116     if (is_null($courseid) or is_null($itemtype)) {
 117         debugging('Missing courseid or itemtype');
 118         return GRADE_UPDATE_FAILED;
 119     }
 120
 121     if (!$grade_items = grade_item::fetch_all($params)) {
 122         // create a new one
 123         $grade_item = false;
 124
 125     } else if (count($grade_items) == 1){
 126         $grade_item = reset($grade_items);
 127         unset($grade_items); //release memory
 128
 129     } else {
 130         debugging('Found more than one grade item');
 131         return GRADE_UPDATE_MULTIPLE;
 132     }
 133
 134     if (!empty($itemdetails['deleted'])) {
 135         if ($grade_item) {
 136             if ($grade_item->delete($source)) {
 137                 return GRADE_UPDATE_OK;
 138             } else {
 139                 return GRADE_UPDATE_FAILED;
 140             }
 141         }
 142         return GRADE_UPDATE_OK;
 143     }
 144
 145 /// Create or update the grade_item if needed
 146     if (!$grade_item) {
 147         if ($itemdetails) {
 148             $itemdetails = (array)$itemdetails;
 149
 150             // grademin and grademax ignored when scale specified
 151             if (array_key_exists('scaleid', $itemdetails)) {
 152                 if ($itemdetails['scaleid']) {
 153                     unset($itemdetails['grademin']);
 154                     unset($itemdetails['grademax']);
 155                 }
 156             }
 157
 158             foreach ($itemdetails as $k=>$v) {
 159                 if (!in_array($k, $allowed)) {
 160                     // ignore it
 161                     continue;
 162                 }
 163                 if ($k == 'gradetype' and $v == GRADE_TYPE_NONE) {
 164                     // no grade item needed!
 165                     return GRADE_UPDATE_OK;
 166                 }
 167                 $params[$k] = $v;
 168             }
 169         }
 170         $grade_item = new grade_item($params);
 171         $grade_item->insert();
 172
 173     } else {
 174         if ($grade_item->is_locked()) {
 175             debugging('Grading item is locked!');
 176             return GRADE_UPDATE_ITEM_LOCKED;
 177         }
 178
 179         if ($itemdetails) {
 180             $itemdetails = (array)$itemdetails;
 181             $update = false;
 182             foreach ($itemdetails as $k=>$v) {
 183                 if (!in_array($k, $allowed)) {
 184                     // ignore it
 185                     continue;
 186                 }
 187                 if ($grade_item->{$k} != $v) {
 188                     $grade_item->{$k} = $v;
 189                     $update = true;
 190                 }
 191             }
 192             if ($update) {
 193                 $grade_item->update();
 194             }
 195         }
 196     }
 197
 198 /// Some extra checks
 199     // do we use grading?
 200     if ($grade_item->gradetype == GRADE_TYPE_NONE) {
 201         return GRADE_UPDATE_OK;
 202     }
 203
 204     // no grade submitted
 205     if (empty($grades)) {
 206         return GRADE_UPDATE_OK;
 207     }
 208
 209 /// Finally start processing of grades
 210     if (is_object($grades)) {
 211         $grades = array($grades);
 212     } else {
 213         if (array_key_exists('userid', $grades)) {
 214             $grades = array($grades);
 215         }
 216     }
 217
 218     $failed = false;
 219     foreach ($grades as $grade) {
 220         $grade = (array)$grade;
 221         if (empty($grade['userid'])) {
 222             $failed = true;
 223             debugging('Invalid userid in grade submitted');
 224             continue;
 225         } else {
 226             $userid = $grade['userid'];
 227         }
 228
 229         $rawgrade       = false;
 230         $feedback       = false;
 231         $feedbackformat = FORMAT_MOODLE;
 232
 233         if (array_key_exists('rawgrade', $grade)) {
 234             $rawgrade = $grade['rawgrade'];
 235         }
 236
 237         if (array_key_exists('feedback', $grade)) {
 238             $feedback = $grade['feedback'];
 239         }
 240
 241         if (array_key_exists('feedbackformat', $grade)) {
 242             $feedbackformat = $grade['feedbackformat'];
 243         }
 244
 245         if (array_key_exists('usermodified', $grade)) {
 246             $usermodified = $grade['usermodified'];
 247         } else {
 248             $usermodified = $USER->id;
 249         }
 250
 251         // update or insert the grade
 252         if (!$grade_item->update_raw_grade($userid, $rawgrade, $source, null, $feedback, $feedbackformat, $usermodified)) {
 253             $failed = true;
 254         }
 255     }
 256
 257     if (!$failed) {
 258         return GRADE_UPDATE_OK;
 259     } else {
 260         return GRADE_UPDATE_FAILED;
 261     }
 262 }
 263
 264
 265 /**
 266  * Tells a module whether a grade (or grade_item if $userid is not given) is currently locked or not.
 267  * If it's locked to the current user then the module can print a nice message or prevent editing in the module.
 268  * If no $userid is given, the method will always return the grade_item's locked state.
 269  * If a $userid is given, the method will first check the grade_item's locked state (the column). If it is locked,
 270  * the method will return true no matter the locked state of the specific grade being checked. If unlocked, it will
 271  * return the locked state of the specific grade.
 272  *
 273  * @param int $courseid id of course
 274  * @param string $itemtype 'mod', 'block'
 275  * @param string $itemmodule 'forum, 'quiz', etc.
 276  * @param int $iteminstance id of the item module
 277  * @param int $itemnumber most probably 0, modules can use other numbers when having more than one grades for each user
 278  * @param int $userid ID of the graded user
 279  * @return boolean Whether the grade is locked or not
 280  */
 281 function grade_is_locked($courseid, $itemtype, $itemmodule, $iteminstance, $itemnumber, $userid=NULL) {
 282
 283     if (!$grade_items = grade_item::fetch_all(compact('courseid', 'itemtype', 'itemmodule', 'iteminstance', 'itemnumber'))) {
 284         return false;
 285
 286     } else if (count($grade_items) == 1){
 287         $grade_item = reset($grade_items);
 288         return $grade_item->is_locked($userid);
 289
 290     } else {
 291         debugging('Found more than one grade item');
 292         foreach ($grade_items as $grade_item) {
 293             if ($grade_item->is_locked($userid)) {
 294                 return true;
 295             }
 296         }
 297         return false;
 298     }
 299 }
 300
 301 /**
 302  * Returns list of outcomes used in course together with current outcomes for this user
 303  * @param int $courseid id of course
 304  * @param string $itemtype 'mod', 'block'
 305  * @param string $itemmodule 'forum, 'quiz', etc.
 306  * @param int $iteminstance id of the item module
 307  * @param int $userid ID of the graded user
 308  * @return array of outcome information objects (scaleid, name, grade and locked status) indexed with itemnumbers
 309  */
 310 function grade_get_outcomes($courseid, $itemtype, $itemmodule, $iteminstance, $userid=0) {
 311     $result = array();
 312     if ($items = grade_item::fetch_all(array('itemtype'=>$itemtype, 'itemmodule'=>$itemmodule, 'iteminstance'=>$iteminstance, 'courseid'=>$courseid))) {
 313         foreach ($items as $item) {
 314             if (empty($item->outcomeid)) {
 315                 continue;
 316             }
 317             if (!$outcome = grade_outcome::fetch(array('id'=>$item->outcomeid))) {
 318                 debugging('Incorect outcomeid found');
 319                 continue;
 320             }
 321             // prepare outcome info with user grade
 322             $o = new object();
 323             $o->scaleid = $outcome->scaleid;
 324             $o->name    = $outcome->fullname;
 325
 326             if (empty($userid)) {
 327                 //no user info
 328             } if ($grade = $item->get_grade($userid,false)) {
 329                 $o->grade  = $grade->finalgrade;
 330                 $o->locked = $grade->is_locked();
 331             } else {
 332                 $o->grade = null;
 333                 $o->locked = $item->is_locked();
 334             }
 335             $o->grade = intval($o->grade); // 0 means no grade, int for scales
 336
 337             $result[$item->itemnumber] = $o;
 338         }
 339     }
 340
 341     return $result;
 342 }
 343
 344 /**
 345  * Updates outcomes of user
 346  * @param int $courseid id of course
 347  * @param string $itemtype 'mod', 'block'
 348  * @param string $itemmodule 'forum, 'quiz', etc.
 349  * @param int $iteminstance id of the item module
 350  * @param int $userid ID of the graded user
 351  */
 352 function grade_update_outcomes($source, $courseid, $itemtype, $itemmodule, $iteminstance, $userid, $data) {
 353     if ($items = grade_item::fetch_all(array('itemtype'=>$itemtype, 'itemmodule'=>$itemmodule, 'iteminstance'=>$iteminstance, 'courseid'=>$courseid))) {
 354         foreach ($items as $item) {
 355             if (!array_key_exists($item->itemnumber, $data)) {
 356                 continue;
 357             }
 358             $grade = $data[$item->itemnumber] < 1 ? null : $data[$item->itemnumber];
 359             $item->update_final_grade($userid, $grade, $source);
 360         }
 361     }
 362 }
 363
 364 /***** END OF PUBLIC API *****/
 365
 366
 367 /**
 368  * Verify nwe value of idnumber - checks for uniqueness of new idnubmers, old are kept intact
 369  * @param string idnumber string (with magic quotes)
 370  * @param object $cm used for course module idnumbers and items attached to modules
 371  * @param object $gradeitem is item idnumber
 372  * @return boolean true means idnumber ok
 373  */
 374 function grade_verify_idnumber($idnumber, $grade_item=null, $cm=null) {
 375     if ($idnumber == '') {
 376         //we allow empty idnumbers
 377         return true;
 378     }
 379
 380     // keep existing even when not unique
 381     if ($cm and $cm->idnumber == $idnumber) {
 382         return true;
 383     } else if ($grade_item and $grade_item->idnumber == $idnumber) {
 384         return true;
 385     }
 386
 387     if (get_records('course_modules', 'idnumber', $idnumber)) {
 388         return false;
 389     }
 390
 391     if (get_records('grade_items', 'idnumber', $idnumber)) {
 392         return false;
 393     }
 394
 395     return true;
 396 }
 397
 398 /**
 399  * Force final grade recalculation in all course items
 400  * @param int $courseid
 401  */
 402 function grade_force_full_regrading($courseid) {
 403     set_field('grade_items', 'needsupdate', 1, 'courseid', $courseid);
 404 }
 405
 406 /**
 407  * Updates all final grades in course.
 408  *
 409  * @param int $courseid
 410  * @param int $userid if specified, try to do a quick regrading of grades of this user only
 411  * @param object $updated_item the item in which
 412  * @return boolean true if ok, array of errors if problems found (item id is used as key)
 413  */
 414 function grade_regrade_final_grades($courseid, $userid=null, $updated_item=null) {
 415
 416     $course_item = grade_item::fetch_course_item($courseid);
 417
 418     if ($userid) {
 419         // one raw grade updated for one user
 420         if (empty($updated_item)) {
 421             error("updated_item_id can not be null!");
 422         }
 423         if ($course_item->needsupdate) {
 424             $updated_item->force_regrading();
 425             return 'Can not do fast regrading after updating of raw grades';
 426         }
 427
 428     } else {
 429         if (!$course_item->needsupdate) {
 430             // nothing to do :-)
 431             return true;
 432         }
 433     }
 434
 435     $grade_items = grade_item::fetch_all(array('courseid'=>$courseid));
 436     $depends_on = array();
 437
 438     // first mark all category and calculated items as needing regrading
 439     // this is slower, but 100% accurate
 440     foreach ($grade_items as $gid=>$gitem) {
 441         if (!empty($updated_item) and $updated_item->id == $gid) {
 442             $grade_items[$gid]->needsupdate = 1;
 443
 444         } else if ($gitem->is_course_item() or $gitem->is_category_item() or $gitem->is_calculated()) {
 445             $grade_items[$gid]->needsupdate = 1;
 446         }
 447
 448         // construct depends_on lookup array
 449         $depends_on[$gid] = $grade_items[$gid]->depends_on();
 450     }
 451
 452     $errors = array();
 453     $finalids = array();
 454     $gids     = array_keys($grade_items);
 455     $failed = 0;
 456
 457     while (count($finalids) < count($gids)) { // work until all grades are final or error found
 458         $count = 0;
 459         foreach ($gids as $gid) {
 460             if (in_array($gid, $finalids)) {
 461                 continue; // already final
 462             }
 463
 464             if (!$grade_items[$gid]->needsupdate) {
 465                 $finalids[] = $gid; // we can make it final - does not need update
 466                 continue;
 467             }
 468
 469             $doupdate = true;
 470             foreach ($depends_on[$gid] as $did) {
 471                 if (!in_array($did, $finalids)) {
 472                     $doupdate = false;
 473                     continue; // this item depends on something that is not yet in finals array
 474                 }
 475             }
 476
 477             //oki - let's update, calculate or aggregate :-)
 478             if ($doupdate) {
 479                 $result = $grade_items[$gid]->regrade_final_grades($userid);
 480
 481                 if ($result === true) {
 482                     $grade_items[$gid]->regrading_finished();
 483                     $grade_items[$gid]->check_locktime(); // do the locktime item locking
 484                     $count++;
 485                     $finalids[] = $gid;
 486
 487                 } else {
 488                     $grade_items[$gid]->force_regrading();
 489                     $errors[$gid] = $result;
 490                 }
 491             }
 492         }
 493
 494         if ($count == 0) {
 495             $failed++;
 496         } else {
 497             $failed = 0;
 498         }
 499
 500         if ($failed > 1) {
 501             foreach($gids as $gid) {
 502                 if (in_array($gid, $finalids)) {
 503                     continue; // this one is ok
 504                 }
 505                 $grade_items[$gid]->force_regrading();
 506                 $errors[$grade_items[$gid]->id] = 'Probably circular reference or broken calculation formula'; // TODO: localize
 507             }
 508             break; // oki, found error
 509         }
 510     }
 511
 512     if (count($errors) == 0) {
 513         if (empty($userid)) {
 514             // do the locktime locking of grades, but only when doing full regrading
 515             grade_grade::check_locktime_all($gids);
 516         }
 517         return true;
 518     } else {
 519         return $errors;
 520     }
 521 }
 522
 523 /**
 524  * For backwards compatibility with old third-party modules, this function can
 525  * be used to import all grades from activities with legacy grading.
 526  * @param int $courseid or null if all courses
 527  */
 528 function grade_grab_legacy_grades($courseid=null) {
 529
 530     global $CFG;
 531
 532     if (!$mods = get_list_of_plugins('mod') ) {
 533         error('No modules installed!');
 534     }
 535
 536     if ($courseid) {
 537         $course_sql = " AND cm.course=$courseid";
 538     } else {
 539         $course_sql = "";
 540     }
 541
 542     foreach ($mods as $mod) {
 543
 544         if ($mod == 'NEWMODULE') {   // Someone has unzipped the template, ignore it
 545             continue;
 546         }
 547
 548         if (!$module = get_record('modules', 'name', $mod)) {
 549             //not installed
 550             continue;
 551         }
 552
 553         if (!$module->visible) {
 554             //disabled module
 555             continue;
 556         }
 557
 558         $fullmod = $CFG->dirroot.'/mod/'.$mod;
 559
 560         // include the module lib once
 561         if (file_exists($fullmod.'/lib.php')) {
 562             include_once($fullmod.'/lib.php');
 563             // look for modname_grades() function - old gradebook pulling function
 564             // if present sync the grades with new grading system
 565             $gradefunc = $mod.'_grades';
 566             if (function_exists($gradefunc)) {
 567
 568                 // get all instance of the activity
 569                 $sql = "SELECT a.*, cm.idnumber as cmidnumber, m.name as modname
 570                           FROM {$CFG->prefix}$mod a, {$CFG->prefix}course_modules cm, {$CFG->prefix}modules m
 571                          WHERE m.name='$mod' AND m.id=cm.module AND cm.instance=a.id $course_sql";
 572
 573                 if ($modinstances = get_records_sql($sql)) {
 574                     foreach ($modinstances as $modinstance) {
 575                         grade_update_mod_grades($modinstance);
 576                     }
 577                 }
 578             }
 579         }
 580     }
 581 }
 582
 583 /**
 584  * For testing purposes mainly, reloads grades from all non legacy modules into gradebook.
 585  */
 586 function grade_grab_grades() {
 587
 588     global $CFG;
 589
 590     if (!$mods = get_list_of_plugins('mod') ) {
 591         error('No modules installed!');
 592     }
 593
 594     foreach ($mods as $mod) {
 595
 596         if ($mod == 'NEWMODULE') {   // Someone has unzipped the template, ignore it
 597             continue;
 598         }
 599
 600         if (!$module = get_record('modules', 'name', $mod)) {
 601             //not installed
 602             continue;
 603         }
 604
 605         if (!$module->visible) {
 606             //disabled module
 607             continue;
 608         }
 609
 610         $fullmod = $CFG->dirroot.'/mod/'.$mod;
 611
 612         // include the module lib once
 613         if (file_exists($fullmod.'/lib.php')) {
 614             include_once($fullmod.'/lib.php');
 615             // look for modname_grades() function - old gradebook pulling function
 616             // if present sync the grades with new grading system
 617             $gradefunc = $mod.'_update_grades';
 618             if (function_exists($gradefunc)) {
 619                 $gradefunc();
 620             }
 621         }
 622     }
 623 }
 624
 625 /**
 626  * Force full update of module grades in central gradebook - works for both legacy and converted activities.
 627  * @param object $modinstance object with extra cmidnumber and modname property
 628  * @return boolean success
 629  */
 630 function grade_update_mod_grades($modinstance, $userid=0) {
 631     global $CFG;
 632
 633     $fullmod = $CFG->dirroot.'/mod/'.$modinstance->modname;
 634     if (!file_exists($fullmod.'/lib.php')) {
 635         debugging('missing lib.php file in module');
 636         return false;
 637     }
 638     include_once($fullmod.'/lib.php');
 639
 640     // does it use legacy grading?
 641     $gradefunc        = $modinstance->modname.'_grades';
 642     $updategradesfunc = $modinstance->modname.'_update_grades';
 643     $updateitemfunc   = $modinstance->modname.'_grade_item_update';
 644
 645     if (function_exists($gradefunc)) {
 646
 647         // legacy module - not yet converted
 648         if ($oldgrades = $gradefunc($modinstance->id)) {
 649
 650             $grademax = $oldgrades->maxgrade;
 651             $scaleid = NULL;
 652             if (!is_numeric($grademax)) {
 653                 // scale name is provided as a string, try to find it
 654                 if (!$scale = get_record('scale', 'name', $grademax)) {
 655                     debugging('Incorrect scale name! name:'.$grademax);
 656                     return false;
 657                 }
 658                 $scaleid = $scale->id;
 659             }
 660
 661             if (!$grade_item = grade_get_legacy_grade_item($modinstance, $grademax, $scaleid)) {
 662                 debugging('Can not get/create legacy grade item!');
 663                 return false;
 664             }
 665
 666             $grades = array();
 667             foreach ($oldgrades->grades as $uid=>$usergrade) {
 668                 if ($userid and $uid != $userid) {
 669                     continue;
 670                 }
 671                 $grade = new object();
 672                 $grade->userid = $uid;
 673
 674                 if ($usergrade == '-') {
 675                     // no grade
 676                     $grade->rawgrade = null;
 677
 678                 } else if ($scaleid) {
 679                     // scale in use, words used
 680                     $gradescale = explode(",", $scale->scale);
 681                     $grade->rawgrade = array_search($usergrade, $gradescale) + 1;
 682
 683                 } else {
 684                     // good old numeric value
 685                     $grade->rawgrade = $usergrade;
 686                 }
 687                 $grades[] = $grade;
 688             }
 689
 690             grade_update('legacygrab', $grade_item->courseid, $grade_item->itemtype, $grade_item->itemmodule,
 691                          $grade_item->iteminstance, $grade_item->itemnumber, $grades);
 692         }
 693
 694     } else if (function_exists($updategradesfunc) and function_exists($updateitemfunc)) {
 695         //new grading supported, force updating of grades
 696         $updateitemfunc($modinstance);
 697         $updategradesfunc($modinstance, $userid);
 698
 699     } else {
 700         // mudule does not support grading??
 701     }
 702
 703     return true;
 704 }
 705
 706 /**
 707  * Get and update/create grade item for legacy modules.
 708  */
 709 function grade_get_legacy_grade_item($modinstance, $grademax, $scaleid) {
 710
 711     // does it already exist?
 712     if ($grade_items = grade_item::fetch_all(array('courseid'=>$modinstance->course, 'itemtype'=>'mod', 'itemmodule'=>$modinstance->modname, 'iteminstance'=>$modinstance->id, 'itemnumber'=>0))) {
 713         if (count($grade_items) > 1) {
 714             debugging('Multiple legacy grade_items found.');
 715             return false;
 716         }
 717
 718         $grade_item = reset($grade_items);
 719
 720         if (is_null($grademax) and is_null($scaleid)) {
 721            $grade_item->gradetype  = GRADE_TYPE_NONE;
 722
 723         } else if ($scaleid) {
 724             $grade_item->gradetype = GRADE_TYPE_SCALE;
 725             $grade_item->scaleid   = $scaleid;
 726             $grade_item->grademin  = 1;
 727
 728         } else {
 729             $grade_item->gradetype  = GRADE_TYPE_VALUE;
 730             $grade_item->grademax   = $grademax;
 731             $grade_item->grademin   = 0;
 732         }
 733
 734         $grade_item->itemname = $modinstance->name;
 735         $grade_item->idnumber = $modinstance->cmidnumber;
 736
 737         $grade_item->update();
 738
 739         return $grade_item;
 740     }
 741
 742     // create new one
 743     $params = array('courseid'    =>$modinstance->course,
 744                     'itemtype'    =>'mod',
 745                     'itemmodule'  =>$modinstance->modname,
 746                     'iteminstance'=>$modinstance->id,
 747                     'itemnumber'  =>0,
 748                     'itemname'    =>$modinstance->name,
 749                     'idnumber'    =>$modinstance->cmidnumber);
 750
 751     if (is_null($grademax) and is_null($scaleid)) {
 752         $params['gradetype'] = GRADE_TYPE_NONE;
 753
 754     } else if ($scaleid) {
 755         $params['gradetype'] = GRADE_TYPE_SCALE;
 756         $params['scaleid']   = $scaleid;
 757         $grade_item->grademin  = 1;
 758     } else {
 759         $params['gradetype'] = GRADE_TYPE_VALUE;
 760         $params['grademax']  = $grademax;
 761         $params['grademin']  = 0;
 762     }
 763
 764     $grade_item = new grade_item($params);
 765     $grade_item->insert();
 766
 767     return $grade_item;
 768 }
 769
 770 /**
 771  * Remove all grade related course data - history is kept
 772  * @param int $courseid
 773  * @showfeedback boolean print feedback
 774  */
 775 function remove_course_grades($courseid, $showfeedback) {
 776     $strdeleted = get_string('deleted');
 777
 778     $course_category = grade_category::fetch_course_category($courseid);
 779     $course_category->delete('coursedelete');
 780     if ($showfeedback) {
 781         notify($strdeleted.' - '.get_string('grades', 'grades').', '.get_string('items', 'grades').', '.get_string('categories', 'grades'));
 782     }
 783
 784     if ($outcomes = grade_outcome::fetch_all(array('courseid'=>$courseid))) {
 785         foreach ($outcomes as $outcome) {
 786             $outcome->delete('coursedelete');
 787         }
 788     }
 789     delete_records('grade_outcomes_courses', 'courseid', $courseid);
 790     if ($showfeedback) {
 791         notify($strdeleted.' - '.get_string('outcomes', 'grades'));
 792     }
 793
 794     if ($scales = grade_scale::fetch_all(array('courseid'=>$courseid))) {
 795         foreach ($scales as $scale) {
 796             $scale->delete('coursedelete');
 797         }
 798     }
 799     if ($showfeedback) {
 800         notify($strdeleted.' - '.get_string('scales'));
 801     }
 802 }
 803
 804 /**
 805  * Builds an array of percentages indexed by integers for the purpose of building a select drop-down element.
 806  * @param int $steps The value between each level.
 807  * @param string $order 'asc' for 0-100 and 'desc' for 100-0
 808  * @param int $lowest The lowest value to include
 809  * @param int $highest The highest value to include
 810  */
 811 function build_percentages_array($steps=1, $order='desc', $lowest=0, $highest=100) {
 812     // TODO reject or implement
 813 }
 814
 815 /**
 816  * Grading cron job
 817  */
 818 function grade_cron() {
 819     global $CFG;
 820
 821     $now = time();
 822
 823     $sql = "SELECT i.*
 824               FROM {$CFG->prefix}grade_items i
 825              WHERE i.locked = 0 AND i.locktime > 0 AND i.locktime < $now AND EXISTS (
 826                 SELECT 'x' FROM {$CFG->prefix}grade_items c WHERE c.itemtype='course' AND c.needsupdate=0 AND c.courseid=i.courseid)";
 827
 828     // go through all courses that have proper final grades and lock them if needed
 829     if ($rs = get_recordset_sql($sql)) {
 830         if ($rs->RecordCount() > 0) {
 831             while ($item = rs_fetch_next_record($rs)) {
 832                 $grade_item = new grade_item($item, false);
 833                 $grade_item->locked = $now;
 834                 $grade_item->update('locktime');
 835             }
 836         }
 837         rs_close($rs);
 838     }
 839
 840     $sql = "SELECT g.*
 841               FROM {$CFG->prefix}grade_grades g, {$CFG->prefix}grade_items i
 842              WHERE g.locked = 0 AND g.locktime > 0 AND g.locktime < $now AND g.itemid=i.id AND EXISTS (
 843                 SELECT 'x' FROM {$CFG->prefix}grade_items c WHERE c.itemtype='course' AND c.needsupdate=0 AND c.courseid=i.courseid)";
 844
 845     // go through all courses that have proper final grades and lock them if needed
 846     if ($rs = get_recordset_sql($sql)) {
 847         if ($rs->RecordCount() > 0) {
 848             while ($grade = rs_fetch_next_record($rs)) {
 849                 $grade_grade = new grade_grade($grade, false);
 850                 $grade_grade->locked = $now;
 851                 $grade_grade->update('locktime');
 852             }
 853         }
 854         rs_close($rs);
 855     }
 856
 857 }
 858
 859 ?>