lib/gradelib.php

   1 <?php // $Id$
   2
   3 ///////////////////////////////////////////////////////////////////////////
   4 // NOTICE OF COPYRIGHT                                                   //
   5 //                                                                       //
   6 // Moodle - Modular Object-Oriented Dynamic Learning Environment         //
   7 //          http://moodle.org                                            //
   8 //                                                                       //
   9 // Copyright (C) 1999 onwards  Martin Dougiamas  http://moodle.com       //
  10 //                                                                       //
  11 // This program is free software; you can redistribute it and/or modify  //
  12 // it under the terms of the GNU General Public License as published by  //
  13 // the Free Software Foundation; either version 2 of the License, or     //
  14 // (at your option) any later version.                                   //
  15 //                                                                       //
  16 // This program is distributed in the hope that it will be useful,       //
  17 // but WITHOUT ANY WARRANTY; without even the implied warranty of        //
  18 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         //
  19 // GNU General Public License for more details:                          //
  20 //                                                                       //
  21 //          http://www.gnu.org/copyleft/gpl.html                         //
  22 //                                                                       //
  23 ///////////////////////////////////////////////////////////////////////////
  24
  25 /**
  26  * Library of functions for gradebook - both public and internal
  27  *
  28  * @author Moodle HQ developers
  29  * @version  $Id$
  30  * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
  31  * @package moodlecore
  32  */
  33
  34 require_once($CFG->libdir . '/grade/constants.php');
  35
  36 require_once($CFG->libdir . '/grade/grade_category.php');
  37 require_once($CFG->libdir . '/grade/grade_item.php');
  38 require_once($CFG->libdir . '/grade/grade_grade.php');
  39 require_once($CFG->libdir . '/grade/grade_scale.php');
  40 require_once($CFG->libdir . '/grade/grade_outcome.php');
  41
  42 /////////////////////////////////////////////////////////////////////
  43 ///// Start of public API for communication with modules/blocks /////
  44 /////////////////////////////////////////////////////////////////////
  45
  46 /**
  47  * Submit new or update grade; update/create grade_item definition. Grade must have userid specified,
  48  * rawgrade and feedback with format are optional. rawgrade NULL means 'Not graded', missing property
  49  * or key means do not change existing.
  50  *
  51  * Only following grade item properties can be changed 'itemname', 'idnumber', 'gradetype', 'grademax',
  52  * 'grademin', 'scaleid', 'multfactor', 'plusfactor', 'deleted' and 'hidden'. 'reset' means delete all current grades including locked ones.
  53  *
  54  * Manual, course or category items can not be updated by this function.
  55  * @public
  56  * @param string $source source of the grade such as 'mod/assignment'
  57  * @param int $courseid id of course
  58  * @param string $itemtype type of grade item - mod, block
  59  * @param string $itemmodule more specific then $itemtype - assignment, forum, etc.; maybe NULL for some item types
  60  * @param int $iteminstance instance it of graded subject
  61  * @param int $itemnumber most probably 0, modules can use other numbers when having more than one grades for each user
  62  * @param mixed $grades grade (object, array) or several grades (arrays of arrays or objects), NULL if updating grade_item definition only
  63  * @param mixed $itemdetails object or array describing the grading item, NULL if no change
  64  */
  65 function grade_update($source, $courseid, $itemtype, $itemmodule, $iteminstance, $itemnumber, $grades=NULL, $itemdetails=NULL) {
  66     global $USER, $CFG;
  67
  68     // only following grade_item properties can be changed in this function
  69     $allowed = array('itemname', 'idnumber', 'gradetype', 'grademax', 'grademin', 'scaleid', 'multfactor', 'plusfactor', 'deleted', 'hidden');
  70     // list of 10,5 numeric fields
  71     $floats  = array('grademin', 'grademax', 'multfactor', 'plusfactor');
  72
  73     // grade item identification
  74     $params = compact('courseid', 'itemtype', 'itemmodule', 'iteminstance', 'itemnumber');
  75
  76     if (is_null($courseid) or is_null($itemtype)) {
  77         debugging('Missing courseid or itemtype');
  78         return GRADE_UPDATE_FAILED;
  79     }
  80
  81     if (!$grade_items = grade_item::fetch_all($params)) {
  82         // create a new one
  83         $grade_item = false;
  84
  85     } else if (count($grade_items) == 1){
  86         $grade_item = reset($grade_items);
  87         unset($grade_items); //release memory
  88
  89     } else {
  90         debugging('Found more than one grade item');
  91         return GRADE_UPDATE_MULTIPLE;
  92     }
  93
  94     if (!empty($itemdetails['deleted'])) {
  95         if ($grade_item) {
  96             if ($grade_item->delete($source)) {
  97                 return GRADE_UPDATE_OK;
  98             } else {
  99                 return GRADE_UPDATE_FAILED;
 100             }
 101         }
 102         return GRADE_UPDATE_OK;
 103     }
 104
 105 /// Create or update the grade_item if needed
 106
 107     if (!$grade_item) {
 108         if ($itemdetails) {
 109             $itemdetails = (array)$itemdetails;
 110
 111             // grademin and grademax ignored when scale specified
 112             if (array_key_exists('scaleid', $itemdetails)) {
 113                 if ($itemdetails['scaleid']) {
 114                     unset($itemdetails['grademin']);
 115                     unset($itemdetails['grademax']);
 116                 }
 117             }
 118
 119             foreach ($itemdetails as $k=>$v) {
 120                 if (!in_array($k, $allowed)) {
 121                     // ignore it
 122                     continue;
 123                 }
 124                 if ($k == 'gradetype' and $v == GRADE_TYPE_NONE) {
 125                     // no grade item needed!
 126                     return GRADE_UPDATE_OK;
 127                 }
 128                 $params[$k] = $v;
 129             }
 130         }
 131         $grade_item = new grade_item($params);
 132         $grade_item->insert();
 133
 134     } else {
 135         if ($grade_item->is_locked()) {
 136             // no notice() here, test returned value instead!
 137             return GRADE_UPDATE_ITEM_LOCKED;
 138         }
 139
 140         if ($itemdetails) {
 141             $itemdetails = (array)$itemdetails;
 142             $update = false;
 143             foreach ($itemdetails as $k=>$v) {
 144                 if (!in_array($k, $allowed)) {
 145                     // ignore it
 146                     continue;
 147                 }
 148                 if (in_array($k, $floats)) {
 149                     if (grade_floats_different($grade_item->{$k}, $v)) {
 150                         $grade_item->{$k} = $v;
 151                         $update = true;
 152                     }
 153
 154                 } else {
 155                     if ($grade_item->{$k} != $v) {
 156                         $grade_item->{$k} = $v;
 157                         $update = true;
 158                     }
 159                 }
 160             }
 161             if ($update) {
 162                 $grade_item->update();
 163             }
 164         }
 165     }
 166
 167 /// reset grades if requested
 168     if (!empty($itemdetails['reset'])) {
 169         $grade_item->delete_all_grades('reset');
 170         return GRADE_UPDATE_OK;
 171     }
 172
 173 /// Some extra checks
 174     // do we use grading?
 175     if ($grade_item->gradetype == GRADE_TYPE_NONE) {
 176         return GRADE_UPDATE_OK;
 177     }
 178
 179     // no grade submitted
 180     if (empty($grades)) {
 181         return GRADE_UPDATE_OK;
 182     }
 183
 184 /// Finally start processing of grades
 185     if (is_object($grades)) {
 186         $grades = array($grades->userid=>$grades);
 187     } else {
 188         if (array_key_exists('userid', $grades)) {
 189             $grades = array($grades['userid']=>$grades);
 190         }
 191     }
 192
 193 /// normalize and verify grade array
 194     foreach($grades as $k=>$g) {
 195         if (!is_array($g)) {
 196             $g = (array)$g;
 197             $grades[$k] = $g;
 198         }
 199
 200         if (empty($g['userid']) or $k != $g['userid']) {
 201             debugging('Incorrect grade array index, must be user id! Grade ignored.');
 202             unset($grades[$k]);
 203         }
 204     }
 205
 206     if (empty($grades)) {
 207         return GRADE_UPDATE_FAILED;
 208     }
 209
 210     $count = count($grades);
 211     if ($count == 1) {
 212         reset($grades);
 213         $uid = key($grades);
 214         $sql = "SELECT * FROM {$CFG->prefix}grade_grades WHERE itemid = $grade_item->id AND userid = $uid";
 215
 216     } else if ($count < 200) {
 217         $uids = implode(',', array_keys($grades));
 218         $sql = "SELECT * FROM {$CFG->prefix}grade_grades WHERE itemid = $grade_item->id AND userid IN ($uids)";
 219
 220     } else {
 221         $sql = "SELECT * FROM {$CFG->prefix}grade_grades WHERE itemid = $grade_item->id";
 222     }
 223
 224     $rs = get_recordset_sql($sql);
 225
 226     $failed = false;
 227
 228     while (count($grades) > 0) {
 229         $grade_grade = null;
 230         $grade       = null;
 231
 232         while ($rs and !rs_EOF($rs)) {
 233             if (!$gd = rs_fetch_next_record($rs)) {
 234                 break;
 235             }
 236             $userid = $gd->userid;
 237             if (!isset($grades[$userid])) {
 238                 // this grade not requested, continue
 239                 continue;
 240             }
 241             // existing grade requested
 242             $grade       = $grades[$userid];
 243             $grade_grade = new grade_grade($gd, false);
 244             unset($grades[$userid]);
 245             break;
 246         }
 247
 248         if (is_null($grade_grade)) {
 249             if (count($grades) == 0) {
 250                 // no more grades to process
 251                 break;
 252             }
 253
 254             $grade       = reset($grades);
 255             $userid      = $grade['userid'];
 256             $grade_grade = new grade_grade(array('itemid'=>$grade_item->id, 'userid'=>$userid), false);
 257             $grade_grade->load_optional_fields(); // add feedback and info too
 258             unset($grades[$userid]);
 259         }
 260
 261         $rawgrade       = false;
 262         $feedback       = false;
 263         $feedbackformat = FORMAT_MOODLE;
 264         $usermodified   = $USER->id;
 265         $datesubmitted  = null;
 266         $dategraded     = null;
 267
 268         if (array_key_exists('rawgrade', $grade)) {
 269             $rawgrade = $grade['rawgrade'];
 270         }
 271
 272         if (array_key_exists('feedback', $grade)) {
 273             $feedback = $grade['feedback'];
 274         }
 275
 276         if (array_key_exists('feedbackformat', $grade)) {
 277             $feedbackformat = $grade['feedbackformat'];
 278         }
 279
 280         if (array_key_exists('usermodified', $grade)) {
 281             $usermodified = $grade['usermodified'];
 282         }
 283
 284         if (array_key_exists('datesubmitted', $grade)) {
 285             $datesubmitted = $grade['datesubmitted'];
 286         }
 287
 288         if (array_key_exists('dategraded', $grade)) {
 289             $dategraded = $grade['dategraded'];
 290         }
 291
 292         // update or insert the grade
 293         if (!$grade_item->update_raw_grade($userid, $rawgrade, $source, $feedback, $feedbackformat, $usermodified, $dategraded, $datesubmitted, $grade_grade)) {
 294             $failed = true;
 295         }
 296     }
 297
 298     if ($rs) {
 299         rs_close($rs);
 300     }
 301
 302     if (!$failed) {
 303         return GRADE_UPDATE_OK;
 304     } else {
 305         return GRADE_UPDATE_FAILED;
 306     }
 307 }
 308
 309 /**
 310  * Updates outcomes of user
 311  * Manual outcomes can not be updated.
 312  * @public
 313  * @param string $source source of the grade such as 'mod/assignment'
 314  * @param int $courseid id of course
 315  * @param string $itemtype 'mod', 'block'
 316  * @param string $itemmodule 'forum, 'quiz', etc.
 317  * @param int $iteminstance id of the item module
 318  * @param int $userid ID of the graded user
 319  * @param array $data array itemnumber=>outcomegrade
 320  * @return boolean returns true if grade items were found and updated successfully
 321  */
 322 function grade_update_outcomes($source, $courseid, $itemtype, $itemmodule, $iteminstance, $userid, $data) {
 323     if ($items = grade_item::fetch_all(array('itemtype'=>$itemtype, 'itemmodule'=>$itemmodule, 'iteminstance'=>$iteminstance, 'courseid'=>$courseid))) {
 324         $result = true;
 325         foreach ($items as $item) {
 326             if (!array_key_exists($item->itemnumber, $data)) {
 327                 continue;
 328             }
 329             $grade = $data[$item->itemnumber] < 1 ? null : $data[$item->itemnumber];
 330             $result = ($item->update_final_grade($userid, $grade, $source) && $result);
 331         }
 332         return $result;
 333     }
 334     return false; //grade items not found
 335 }
 336
 337 /**
 338  * Returns grading information for given activity - optionally with users grades
 339  * Manual, course or category items can not be queried.
 340  * @public
 341  * @param int $courseid id of course
 342  * @param string $itemtype 'mod', 'block'
 343  * @param string $itemmodule 'forum, 'quiz', etc.
 344  * @param int $iteminstance id of the item module
 345  * @param int $userid_or_ids optional id of the graded user or array of ids; if userid not used, returns only information about grade_item
 346  * @return array of grade information objects (scaleid, name, grade and locked status, etc.) indexed with itemnumbers
 347  */
 348 function grade_get_grades($courseid, $itemtype, $itemmodule, $iteminstance, $userid_or_ids=null) {
 349     global $CFG;
 350
 351     $return = new object();
 352     $return->items    = array();
 353     $return->outcomes = array();
 354
 355     $course_item = grade_item::fetch_course_item($courseid);
 356     $needsupdate = array();
 357     if ($course_item->needsupdate) {
 358         $result = grade_regrade_final_grades($courseid);
 359         if ($result !== true) {
 360             $needsupdate = array_keys($result);
 361         }
 362     }
 363
 364     if ($grade_items = grade_item::fetch_all(array('itemtype'=>$itemtype, 'itemmodule'=>$itemmodule, 'iteminstance'=>$iteminstance, 'courseid'=>$courseid))) {
 365         foreach ($grade_items as $grade_item) {
 366             $decimalpoints = null;
 367
 368             if (empty($grade_item->outcomeid)) {
 369                 // prepare information about grade item
 370                 $item = new object();
 371                 $item->itemnumber = $grade_item->itemnumber;
 372                 $item->scaleid    = $grade_item->scaleid;
 373                 $item->name       = $grade_item->get_name();
 374                 $item->grademin   = $grade_item->grademin;
 375                 $item->grademax   = $grade_item->grademax;
 376                 $item->gradepass  = $grade_item->gradepass;
 377                 $item->locked     = $grade_item->is_locked();
 378                 $item->hidden     = $grade_item->is_hidden();
 379                 $item->grades     = array();
 380
 381                 switch ($grade_item->gradetype) {
 382                     case GRADE_TYPE_NONE:
 383                         continue;
 384
 385                     case GRADE_TYPE_VALUE:
 386                         $item->scaleid = 0;
 387                         break;
 388
 389                     case GRADE_TYPE_TEXT:
 390                         $item->scaleid   = 0;
 391                         $item->grademin   = 0;
 392                         $item->grademax   = 0;
 393                         $item->gradepass  = 0;
 394                         break;
 395                 }
 396
 397                 if (empty($userid_or_ids)) {
 398                     $userids = array();
 399
 400                 } else if (is_array($userid_or_ids)) {
 401                     $userids = $userid_or_ids;
 402
 403                 } else {
 404                     $userids = array($userid_or_ids);
 405                 }
 406
 407                 if ($userids) {
 408                     $grade_grades = grade_grade::fetch_users_grades($grade_item, $userids, true);
 409                     foreach ($userids as $userid) {
 410                         $grade_grades[$userid]->grade_item =& $grade_item;
 411
 412                         $grade = new object();
 413                         $grade->grade          = $grade_grades[$userid]->finalgrade;
 414                         $grade->locked         = $grade_grades[$userid]->is_locked();
 415                         $grade->hidden         = $grade_grades[$userid]->is_hidden();
 416                         $grade->overridden     = $grade_grades[$userid]->overridden;
 417                         $grade->feedback       = $grade_grades[$userid]->feedback;
 418                         $grade->feedbackformat = $grade_grades[$userid]->feedbackformat;
 419                         $grade->usermodified   = $grade_grades[$userid]->usermodified;
 420                         $grade->datesubmitted  = $grade_grades[$userid]->get_datesubmitted();
 421                         $grade->dategraded     = $grade_grades[$userid]->get_dategraded();
 422
 423                         // create text representation of grade
 424                         if ($grade_item->gradetype == GRADE_TYPE_TEXT or $grade_item->gradetype == GRADE_TYPE_NONE) {
 425                             $grade->grade          = null;
 426                             $grade->str_grade      = '-';
 427                             $grade->str_long_grade = $grade->str_grade;
 428
 429                         } else if (in_array($grade_item->id, $needsupdate)) {
 430                             $grade->grade          = false;
 431                             $grade->str_grade      = get_string('error');
 432                             $grade->str_long_grade = $grade->str_grade;
 433
 434                         } else if (is_null($grade->grade)) {
 435                             $grade->str_grade      = '-';
 436                             $grade->str_long_grade = $grade->str_grade;
 437
 438                         } else {
 439                             $grade->str_grade = grade_format_gradevalue($grade->grade, $grade_item);
 440                             if ($grade_item->gradetype == GRADE_TYPE_SCALE or $grade_item->get_displaytype() != GRADE_DISPLAY_TYPE_REAL) {
 441                                 $grade->str_long_grade = $grade->str_grade;
 442                             } else {
 443                                 $a = new object();
 444                                 $a->grade = $grade->str_grade;
 445                                 $a->max   = grade_format_gradevalue($grade_item->grademax, $grade_item);
 446                                 $grade->str_long_grade = get_string('gradelong', 'grades', $a);
 447                             }
 448                         }
 449
 450                         // create html representation of feedback
 451                         if (is_null($grade->feedback)) {
 452                             $grade->str_feedback = '';
 453                         } else {
 454                             $grade->str_feedback = format_text($grade->feedback, $grade->feedbackformat);
 455                         }
 456
 457                         $item->grades[$userid] = $grade;
 458                     }
 459                 }
 460                 $return->items[$grade_item->itemnumber] = $item;
 461
 462             } else {
 463                 if (!$grade_outcome = grade_outcome::fetch(array('id'=>$grade_item->outcomeid))) {
 464                     debugging('Incorect outcomeid found');
 465                     continue;
 466                 }
 467
 468                 // outcome info
 469                 $outcome = new object();
 470                 $outcome->itemnumber = $grade_item->itemnumber;
 471                 $outcome->scaleid    = $grade_outcome->scaleid;
 472                 $outcome->name       = $grade_outcome->get_name();
 473                 $outcome->locked     = $grade_item->is_locked();
 474                 $outcome->hidden     = $grade_item->is_hidden();
 475
 476                 if (empty($userid_or_ids)) {
 477                     $userids = array();
 478                 } else if (is_array($userid_or_ids)) {
 479                     $userids = $userid_or_ids;
 480                 } else {
 481                     $userids = array($userid_or_ids);
 482                 }
 483
 484                 if ($userids) {
 485                     $grade_grades = grade_grade::fetch_users_grades($grade_item, $userids, true);
 486                     foreach ($userids as $userid) {
 487                         $grade_grades[$userid]->grade_item =& $grade_item;
 488
 489                         $grade = new object();
 490                         $grade->grade          = $grade_grades[$userid]->finalgrade;
 491                         $grade->locked         = $grade_grades[$userid]->is_locked();
 492                         $grade->hidden         = $grade_grades[$userid]->is_hidden();
 493                         $grade->feedback       = $grade_grades[$userid]->feedback;
 494                         $grade->feedbackformat = $grade_grades[$userid]->feedbackformat;
 495                         $grade->usermodified   = $grade_grades[$userid]->usermodified;
 496
 497                         // create text representation of grade
 498                         if (in_array($grade_item->id, $needsupdate)) {
 499                             $grade->grade     = false;
 500                             $grade->str_grade = get_string('error');
 501
 502                         } else if (is_null($grade->grade)) {
 503                             $grade->grade = 0;
 504                             $grade->str_grade = get_string('nooutcome', 'grades');
 505
 506                         } else {
 507                             $grade->grade = (int)$grade->grade;
 508                             $scale = $grade_item->load_scale();
 509                             $grade->str_grade = format_string($scale->scale_items[(int)$grade->grade-1]);
 510                         }
 511
 512                         // create html representation of feedback
 513                         if (is_null($grade->feedback)) {
 514                             $grade->str_feedback = '';
 515                         } else {
 516                             $grade->str_feedback = format_text($grade->feedback, $grade->feedbackformat);
 517                         }
 518
 519                         $outcome->grades[$userid] = $grade;
 520                     }
 521                 }
 522
 523                 if (isset($return->outcomes[$grade_item->itemnumber])) {
 524                     // itemnumber duplicates - lets fix them!
 525                     $newnumber = $grade_item->itemnumber + 1;
 526                     while(grade_item::fetch(array('itemtype'=>$itemtype, 'itemmodule'=>$itemmodule, 'iteminstance'=>$iteminstance, 'courseid'=>$courseid, 'itemnumber'=>$newnumber))) {
 527                         $newnumber++;
 528                     }
 529                     $outcome->itemnumber    = $newnumber;
 530                     $grade_item->itemnumber = $newnumber;
 531                     $grade_item->update('system');
 532                 }
 533
 534                 $return->outcomes[$grade_item->itemnumber] = $outcome;
 535
 536             }
 537         }
 538     }
 539
 540     // sort results using itemnumbers
 541     ksort($return->items, SORT_NUMERIC);
 542     ksort($return->outcomes, SORT_NUMERIC);
 543
 544     return $return;
 545 }
 546
 547 ///////////////////////////////////////////////////////////////////
 548 ///// End of public API for communication with modules/blocks /////
 549 ///////////////////////////////////////////////////////////////////
 550
 551
 552
 553 ///////////////////////////////////////////////////////////////////
 554 ///// Internal API: used by gradebook plugins and Moodle core /////
 555 ///////////////////////////////////////////////////////////////////
 556
 557 /**
 558  * Returns course gradebook setting
 559  * @param int $courseid
 560  * @param string $name of setting, maybe null if reset only
 561  * @param bool $resetcache force reset of internal static cache
 562  * @return string value, NULL if no setting
 563  */
 564 function grade_get_setting($courseid, $name, $default=null, $resetcache=false) {
 565     static $cache = array();
 566
 567     if ($resetcache or !array_key_exists($courseid, $cache)) {
 568         $cache[$courseid] = array();
 569
 570     } else if (is_null($name)) {
 571         return null;
 572
 573     } else if (array_key_exists($name, $cache[$courseid])) {
 574         return $cache[$courseid][$name];
 575     }
 576
 577     if (!$data = get_record('grade_settings', 'courseid', $courseid, 'name', addslashes($name))) {
 578         $result = null;
 579     } else {
 580         $result = $data->value;
 581     }
 582
 583     if (is_null($result)) {
 584         $result = $default;
 585     }
 586
 587     $cache[$courseid][$name] = $result;
 588     return $result;
 589 }
 590
 591 /**
 592  * Returns all course gradebook settings as object properties
 593  * @param int $courseid
 594  * @return object
 595  */
 596 function grade_get_settings($courseid) {
 597      $settings = new object();
 598      $settings->id = $courseid;
 599
 600     if ($records = get_records('grade_settings', 'courseid', $courseid)) {
 601         foreach ($records as $record) {
 602             $settings->{$record->name} = $record->value;
 603         }
 604     }
 605
 606     return $settings;
 607 }
 608
 609 /**
 610  * Add/update course gradebook setting
 611  * @param int $courseid
 612  * @param string $name of setting
 613  * @param string value, NULL means no setting==remove
 614  * @return void
 615  */
 616 function grade_set_setting($courseid, $name, $value) {
 617     if (is_null($value)) {
 618         delete_records('grade_settings', 'courseid', $courseid, 'name', addslashes($name));
 619
 620     } else if (!$existing = get_record('grade_settings', 'courseid', $courseid, 'name', addslashes($name))) {
 621         $data = new object();
 622         $data->courseid = $courseid;
 623         $data->name     = addslashes($name);
 624         $data->value    = addslashes($value);
 625         insert_record('grade_settings', $data);
 626
 627     } else {
 628         $data = new object();
 629         $data->id       = $existing->id;
 630         $data->value    = addslashes($value);
 631         update_record('grade_settings', $data);
 632     }
 633
 634     grade_get_setting($courseid, null, null, true); // reset the cache
 635 }
 636
 637 /**
 638  * Returns string representation of grade value
 639  * @param float $value grade value
 640  * @param object $grade_item - by reference to prevent scale reloading
 641  * @param bool $localized use localised decimal separator
 642  * @param int $displaytype type of display - GRADE_DISPLAY_TYPE_REAL, GRADE_DISPLAY_TYPE_PERCENTAGE, GRADE_DISPLAY_TYPE_LETTER
 643  * @param int $decimalplaces number of decimal places when displaying float values
 644  * @return string
 645  */
 646 function grade_format_gradevalue($value, &$grade_item, $localized=true, $displaytype=null, $decimals=null) {
 647     if ($grade_item->gradetype == GRADE_TYPE_NONE or $grade_item->gradetype == GRADE_TYPE_TEXT) {
 648         return '';
 649     }
 650
 651     // no grade yet?
 652     if (is_null($value)) {
 653         return '-';
 654     }
 655
 656     if ($grade_item->gradetype != GRADE_TYPE_VALUE and $grade_item->gradetype != GRADE_TYPE_SCALE) {
 657         //unknown type??
 658         return '';
 659     }
 660
 661     if (is_null($displaytype)) {
 662         $displaytype = $grade_item->get_displaytype();
 663     }
 664
 665     if (is_null($decimals)) {
 666         $decimals = $grade_item->get_decimals();
 667     }
 668
 669     switch ($displaytype) {
 670         case GRADE_DISPLAY_TYPE_REAL:
 671             return grade_format_gradevalue_real($value, $grade_item, $decimals, $localized);
 672
 673         case GRADE_DISPLAY_TYPE_PERCENTAGE:
 674             return grade_format_gradevalue_percentage($value, $grade_item, $decimals, $localized);
 675
 676         case GRADE_DISPLAY_TYPE_LETTER:
 677             return grade_format_gradevalue_letter($value, $grade_item);
 678
 679         case GRADE_DISPLAY_TYPE_REAL_PERCENTAGE:
 680             return grade_format_gradevalue_real($value, $grade_item, $decimals, $localized) . ' (' .
 681                     grade_format_gradevalue_percentage($value, $grade_item, $decimals, $localized) . ')';
 682
 683         case GRADE_DISPLAY_TYPE_REAL_LETTER:
 684             return grade_format_gradevalue_real($value, $grade_item, $decimals, $localized) . ' (' .
 685                     grade_format_gradevalue_letter($value, $grade_item) . ')';
 686
 687         case GRADE_DISPLAY_TYPE_PERCENTAGE_REAL:
 688             return grade_format_gradevalue_percentage($value, $grade_item, $decimals, $localized) . ' (' .
 689                     grade_format_gradevalue_real($value, $grade_item, $decimals, $localized) . ')';
 690
 691         case GRADE_DISPLAY_TYPE_LETTER_REAL:
 692             return grade_format_gradevalue_letter($value, $grade_item) . ' (' .
 693                     grade_format_gradevalue_real($value, $grade_item, $decimals, $localized) . ')';
 694
 695         case GRADE_DISPLAY_TYPE_LETTER_PERCENTAGE:
 696             return grade_format_gradevalue_letter($value, $grade_item) . ' (' .
 697                     grade_format_gradevalue_percentage($value, $grade_item, $decimals, $localized) . ')';
 698
 699         case GRADE_DISPLAY_TYPE_PERCENTAGE_LETTER:
 700             return grade_format_gradevalue_percentage($value, $grade_item, $decimals, $localized) . ' (' .
 701                     grade_format_gradevalue_letter($value, $grade_item) . ')';
 702         default:
 703             return '';
 704     }
 705 }
 706
 707 function grade_format_gradevalue_real($value, $grade_item, $decimals, $localized) {
 708     if ($grade_item->gradetype == GRADE_TYPE_SCALE) {
 709         if (!$scale = $grade_item->load_scale()) {
 710             return get_string('error');
 711         }
 712
 713         $value = $grade_item->bounded_grade($value);
 714         return format_string($scale->scale_items[$value-1]);
 715
 716     } else {
 717         return format_float($value, $decimals, $localized);
 718     }
 719 }
 720
 721 function grade_format_gradevalue_percentage($value, $grade_item, $decimals, $localized) {
 722     $min = $grade_item->grademin;
 723     $max = $grade_item->grademax;
 724     if ($min == $max) {
 725         return '';
 726     }
 727     $value = $grade_item->bounded_grade($value);
 728     $percentage = (($value-$min)*100)/($max-$min);
 729     return format_float($percentage, $decimals, $localized).' %';
 730 }
 731
 732 function grade_format_gradevalue_letter($value, $grade_item) {
 733     $context = get_context_instance(CONTEXT_COURSE, $grade_item->courseid);
 734     if (!$letters = grade_get_letters($context)) {
 735         return ''; // no letters??
 736     }
 737
 738     if (is_null($value)) {
 739         return '-';
 740     }
 741
 742     $value = grade_grade::standardise_score($value, $grade_item->grademin, $grade_item->grademax, 0, 100);
 743     $value = bounded_number(0, $value, 100); // just in case
 744     foreach ($letters as $boundary => $letter) {
 745         if ($value >= $boundary) {
 746             return format_string($letter);
 747         }
 748     }
 749     return '-'; // no match? maybe '' would be more correct
 750 }
 751
 752
 753 /**
 754  * Returns grade options for gradebook category menu
 755  * @param int $courseid
 756  * @param bool $includenew include option for new category (-1)
 757  * @return array of grade categories in course
 758  */
 759 function grade_get_categories_menu($courseid, $includenew=false) {
 760     $result = array();
 761     if (!$categories = grade_category::fetch_all(array('courseid'=>$courseid))) {
 762         //make sure course category exists
 763         if (!grade_category::fetch_course_category($courseid)) {
 764             debugging('Can not create course grade category!');
 765             return $result;
 766         }
 767         $categories = grade_category::fetch_all(array('courseid'=>$courseid));
 768     }
 769     foreach ($categories as $key=>$category) {
 770         if ($category->is_course_category()) {
 771             $result[$category->id] = get_string('uncategorised', 'grades');
 772             unset($categories[$key]);
 773         }
 774     }
 775     if ($includenew) {
 776         $result[-1] = get_string('newcategory', 'grades');
 777     }
 778     $cats = array();
 779     foreach ($categories as $category) {
 780         $cats[$category->id] = $category->get_name();
 781     }
 782     asort($cats, SORT_LOCALE_STRING);
 783
 784     return ($result+$cats);
 785 }
 786
 787 /**
 788  * Returns grade letters array used in context
 789  * @param object $context object or null for defaults
 790  * @return array of grade_boundary=>letter_string
 791  */
 792 function grade_get_letters($context=null) {
 793     if (empty($context)) {
 794         //default grading letters
 795         return array('93'=>'A', '90'=>'A-', '87'=>'B+', '83'=>'B', '80'=>'B-', '77'=>'C+', '73'=>'C', '70'=>'C-', '67'=>'D+', '60'=>'D', '0'=>'F');
 796     }
 797
 798     static $cache = array();
 799
 800     if (array_key_exists($context->id, $cache)) {
 801         return $cache[$context->id];
 802     }
 803
 804     if (count($cache) > 100) {
 805         $cache = array(); // cache size limit
 806     }
 807
 808     $letters = array();
 809
 810     $contexts = get_parent_contexts($context);
 811     array_unshift($contexts, $context->id);
 812
 813     foreach ($contexts as $ctxid) {
 814         if ($records = get_records('grade_letters', 'contextid', $ctxid, 'lowerboundary DESC')) {
 815             foreach ($records as $record) {
 816                 $letters[$record->lowerboundary] = $record->letter;
 817             }
 818         }
 819
 820         if (!empty($letters)) {
 821             $cache[$context->id] = $letters;
 822             return $letters;
 823         }
 824     }
 825
 826     $letters = grade_get_letters(null);
 827     $cache[$context->id] = $letters;
 828     return $letters;
 829 }
 830
 831
 832 /**
 833  * Verify new value of idnumber - checks for uniqueness of new idnumbers, old are kept intact
 834  * @param string idnumber string (with magic quotes)
 835  * @param int $courseid - id numbers are course unique only
 836  * @param object $cm used for course module idnumbers and items attached to modules
 837  * @param object $gradeitem is item idnumber
 838  * @return boolean true means idnumber ok
 839  */
 840 function grade_verify_idnumber($idnumber, $courseid, $grade_item=null, $cm=null) {
 841     if ($idnumber == '') {
 842         //we allow empty idnumbers
 843         return true;
 844     }
 845
 846     // keep existing even when not unique
 847     if ($cm and $cm->idnumber == $idnumber) {
 848         return true;
 849     } else if ($grade_item and $grade_item->idnumber == $idnumber) {
 850         return true;
 851     }
 852
 853     if (get_records_select('course_modules', "course = $courseid AND idnumber='$idnumber'")) {
 854         return false;
 855     }
 856
 857     if (get_records_select('grade_items', "courseid = $courseid AND idnumber='$idnumber'")) {
 858         return false;
 859     }
 860
 861     return true;
 862 }
 863
 864 /**
 865  * Force final grade recalculation in all course items
 866  * @param int $courseid
 867  */
 868 function grade_force_full_regrading($courseid) {
 869     set_field('grade_items', 'needsupdate', 1, 'courseid', $courseid);
 870 }
 871
 872 /**
 873  * Forces regrading of all site grades - usualy when chanign site setings
 874  */
 875 function grade_force_site_regrading() {
 876     global $CFG;
 877     $sql = "UPDATE {$CFG->prefix}grade_items SET needsupdate=1";
 878     execute_sql($sql, false);
 879 }
 880
 881 /**
 882  * Updates all final grades in course.
 883  *
 884  * @param int $courseid
 885  * @param int $userid if specified, try to do a quick regrading of grades of this user only
 886  * @param object $updated_item the item in which
 887  * @return boolean true if ok, array of errors if problems found (item id is used as key)
 888  */
 889 function grade_regrade_final_grades($courseid, $userid=null, $updated_item=null) {
 890
 891     $course_item = grade_item::fetch_course_item($courseid);
 892
 893     if ($userid) {
 894         // one raw grade updated for one user
 895         if (empty($updated_item)) {
 896             error("updated_item_id can not be null!");
 897         }
 898         if ($course_item->needsupdate) {
 899             $updated_item->force_regrading();
 900             return array($course_item->id =>'Can not do fast regrading after updating of raw grades');
 901         }
 902
 903     } else {
 904         if (!$course_item->needsupdate) {
 905             // nothing to do :-)
 906             return true;
 907         }
 908     }
 909
 910     $grade_items = grade_item::fetch_all(array('courseid'=>$courseid));
 911     $depends_on = array();
 912
 913     // first mark all category and calculated items as needing regrading
 914     // this is slower, but 100% accurate
 915     foreach ($grade_items as $gid=>$gitem) {
 916         if (!empty($updated_item) and $updated_item->id == $gid) {
 917             $grade_items[$gid]->needsupdate = 1;
 918
 919         } else if ($gitem->is_course_item() or $gitem->is_category_item() or $gitem->is_calculated()) {
 920             $grade_items[$gid]->needsupdate = 1;
 921         }
 922
 923         // construct depends_on lookup array
 924         $depends_on[$gid] = $grade_items[$gid]->depends_on();
 925     }
 926
 927     $errors = array();
 928     $finalids = array();
 929     $gids     = array_keys($grade_items);
 930     $failed = 0;
 931
 932     while (count($finalids) < count($gids)) { // work until all grades are final or error found
 933         $count = 0;
 934         foreach ($gids as $gid) {
 935             if (in_array($gid, $finalids)) {
 936                 continue; // already final
 937             }
 938
 939             if (!$grade_items[$gid]->needsupdate) {
 940                 $finalids[] = $gid; // we can make it final - does not need update
 941                 continue;
 942             }
 943
 944             $doupdate = true;
 945             foreach ($depends_on[$gid] as $did) {
 946                 if (!in_array($did, $finalids)) {
 947                     $doupdate = false;
 948                     continue; // this item depends on something that is not yet in finals array
 949                 }
 950             }
 951
 952             //oki - let's update, calculate or aggregate :-)
 953             if ($doupdate) {
 954                 $result = $grade_items[$gid]->regrade_final_grades($userid);
 955
 956                 if ($result === true) {
 957                     $grade_items[$gid]->regrading_finished();
 958                     $grade_items[$gid]->check_locktime(); // do the locktime item locking
 959                     $count++;
 960                     $finalids[] = $gid;
 961
 962                 } else {
 963                     $grade_items[$gid]->force_regrading();
 964                     $errors[$gid] = $result;
 965                 }
 966             }
 967         }
 968
 969         if ($count == 0) {
 970             $failed++;
 971         } else {
 972             $failed = 0;
 973         }
 974
 975         if ($failed > 1) {
 976             foreach($gids as $gid) {
 977                 if (in_array($gid, $finalids)) {
 978                     continue; // this one is ok
 979                 }
 980                 $grade_items[$gid]->force_regrading();
 981                 $errors[$grade_items[$gid]->id] = 'Probably circular reference or broken calculation formula'; // TODO: localize
 982             }
 983             break; // oki, found error
 984         }
 985     }
 986
 987     if (count($errors) == 0) {
 988         if (empty($userid)) {
 989             // do the locktime locking of grades, but only when doing full regrading
 990             grade_grade::check_locktime_all($gids);
 991         }
 992         return true;
 993     } else {
 994         return $errors;
 995     }
 996 }
 997
 998 /**
 999  * For backwards compatibility with old third-party modules, this function can
1000  * be used to import all grades from activities with legacy grading.
1001  * @param int $courseid
1002  */
1003 function grade_grab_legacy_grades($courseid) {
1004     global $CFG;
1005
1006     if (!$mods = get_list_of_plugins('mod') ) {
1007         error('No modules installed!');
1008     }
1009
1010     foreach ($mods as $mod) {
1011         if ($mod == 'NEWMODULE') {   // Someone has unzipped the template, ignore it
1012             continue;
1013         }
1014
1015         $fullmod = $CFG->dirroot.'/mod/'.$mod;
1016
1017         // include the module lib once
1018         if (file_exists($fullmod.'/lib.php')) {
1019             include_once($fullmod.'/lib.php');
1020             // look for modname_grades() function - old gradebook pulling function
1021             // if present sync the grades with new grading system
1022             $gradefunc = $mod.'_grades';
1023             if (function_exists($gradefunc)) {
1024                 grade_grab_course_grades($courseid, $mod);
1025             }
1026         }
1027     }
1028 }
1029
1030 /**
1031  * Refetches data from all course activities
1032  * @param int $courseid
1033  * @param string $modname
1034  * @return success
1035  */
1036 function grade_grab_course_grades($courseid, $modname=null) {
1037     global $CFG;
1038
1039     if ($modname) {
1040         $sql = "SELECT a.*, cm.idnumber as cmidnumber, m.name as modname
1041                   FROM {$CFG->prefix}$modname a, {$CFG->prefix}course_modules cm, {$CFG->prefix}modules m
1042                  WHERE m.name='$modname' AND m.visible=1 AND m.id=cm.module AND cm.instance=a.id AND cm.course=$courseid";
1043
1044         if ($modinstances = get_records_sql($sql)) {
1045             foreach ($modinstances as $modinstance) {
1046                 grade_update_mod_grades($modinstance);
1047             }
1048         }
1049         return;
1050     }
1051
1052     if (!$mods = get_list_of_plugins('mod') ) {
1053         error('No modules installed!');
1054     }
1055
1056     foreach ($mods as $mod) {
1057         if ($mod == 'NEWMODULE') {   // Someone has unzipped the template, ignore it
1058             continue;
1059         }
1060
1061         $fullmod = $CFG->dirroot.'/mod/'.$mod;
1062
1063         // include the module lib once
1064         if (file_exists($fullmod.'/lib.php')) {
1065             // get all instance of the activity
1066             $sql = "SELECT a.*, cm.idnumber as cmidnumber, m.name as modname
1067                       FROM {$CFG->prefix}$mod a, {$CFG->prefix}course_modules cm, {$CFG->prefix}modules m
1068                      WHERE m.name='$mod' AND m.visible=1 AND m.id=cm.module AND cm.instance=a.id AND cm.course=$courseid";
1069
1070             if ($modinstances = get_records_sql($sql)) {
1071                 foreach ($modinstances as $modinstance) {
1072                     grade_update_mod_grades($modinstance);
1073                 }
1074             }
1075         }
1076     }
1077 }
1078
1079 /**
1080  * Force full update of module grades in central gradebook - works for both legacy and converted activities.
1081  * @param object $modinstance object with extra cmidnumber and modname property
1082  * @return boolean success
1083  */
1084 function grade_update_mod_grades($modinstance, $userid=0) {
1085     global $CFG;
1086
1087     $fullmod = $CFG->dirroot.'/mod/'.$modinstance->modname;
1088     if (!file_exists($fullmod.'/lib.php')) {
1089         debugging('missing lib.php file in module ' . $modinstance->modname);
1090         return false;
1091     }
1092     include_once($fullmod.'/lib.php');
1093
1094     // does it use legacy grading?
1095     $gradefunc        = $modinstance->modname.'_grades';
1096     $updategradesfunc = $modinstance->modname.'_update_grades';
1097     $updateitemfunc   = $modinstance->modname.'_grade_item_update';
1098
1099     if (function_exists($gradefunc)) {
1100
1101         // legacy module - not yet converted
1102         if ($oldgrades = $gradefunc($modinstance->id)) {
1103
1104             $grademax = $oldgrades->maxgrade;
1105             $scaleid = NULL;
1106             if (!is_numeric($grademax)) {
1107                 // scale name is provided as a string, try to find it
1108                 if (!$scale = get_record('scale', 'name', $grademax)) {
1109                     debugging('Incorrect scale name! name:'.$grademax);
1110                     return false;
1111                 }
1112                 $scaleid = $scale->id;
1113             }
1114
1115             if (!$grade_item = grade_get_legacy_grade_item($modinstance, $grademax, $scaleid)) {
1116                 debugging('Can not get/create legacy grade item!');
1117                 return false;
1118             }
1119
1120             if (!empty($oldgrades->grades)) {
1121                 $grades = array();
1122
1123                 foreach ($oldgrades->grades as $uid=>$usergrade) {
1124                     if ($userid and $uid != $userid) {
1125                         continue;
1126                     }
1127                     $grade = new object();
1128                     $grade->userid = $uid;
1129
1130                     if ($usergrade == '-') {
1131                         // no grade
1132                         $grade->rawgrade = null;
1133
1134                     } else if ($scaleid) {
1135                         // scale in use, words used
1136                         $gradescale = explode(",", $scale->scale);
1137                         $grade->rawgrade = array_search($usergrade, $gradescale) + 1;
1138
1139                     } else {
1140                         // good old numeric value
1141                         $grade->rawgrade = $usergrade;
1142                     }
1143                     $grades[$uid] = $grade;
1144                 }
1145
1146                 grade_update('legacygrab', $grade_item->courseid, $grade_item->itemtype, $grade_item->itemmodule,
1147                              $grade_item->iteminstance, $grade_item->itemnumber, $grades);
1148             }
1149         }
1150
1151     } else if (function_exists($updategradesfunc) and function_exists($updateitemfunc)) {
1152         //new grading supported, force updating of grades
1153         $updateitemfunc($modinstance);
1154         $updategradesfunc($modinstance, $userid);
1155
1156     } else {
1157         // mudule does not support grading??
1158     }
1159
1160     return true;
1161 }
1162
1163 /**
1164  * Returns list of currently used mods with legacy grading in course
1165  * @param $courseid int
1166  * @return array of modname=>modulenamestring mods with legacy grading
1167  */
1168 function grade_get_legacy_modules($courseid) {
1169     global $CFG;
1170
1171     if (!$mods = get_course_mods($courseid)) {
1172         return array();
1173     }
1174     $legacy = array();
1175
1176     foreach ($mods as $mod) {
1177         $modname = $mod->modname;
1178
1179         $modlib = "$CFG->dirroot/mod/$modname/lib.php";
1180         if (!$modlib) {
1181             continue;
1182         }
1183         include_once($modlib);
1184         $gradefunc = $modname.'_grades';
1185         if (!function_exists($gradefunc)) {
1186             continue;
1187         }
1188         $legacy[$modname] = get_string('modulename', $modname);
1189     }
1190
1191     return $legacy;
1192 }
1193
1194 /**
1195  * Get and update/create grade item for legacy modules.
1196  */
1197 function grade_get_legacy_grade_item($modinstance, $grademax, $scaleid) {
1198
1199     // does it already exist?
1200     if ($grade_items = grade_item::fetch_all(array('courseid'=>$modinstance->course, 'itemtype'=>'mod', 'itemmodule'=>$modinstance->modname, 'iteminstance'=>$modinstance->id, 'itemnumber'=>0))) {
1201         if (count($grade_items) > 1) {
1202             debugging('Multiple legacy grade_items found.');
1203             return false;
1204         }
1205
1206         $grade_item = reset($grade_items);
1207
1208         if (is_null($grademax) and is_null($scaleid)) {
1209            $grade_item->gradetype  = GRADE_TYPE_NONE;
1210
1211         } else if ($scaleid) {
1212             $grade_item->gradetype = GRADE_TYPE_SCALE;
1213             $grade_item->scaleid   = $scaleid;
1214             $grade_item->grademin  = 1;
1215
1216         } else {
1217             $grade_item->gradetype  = GRADE_TYPE_VALUE;
1218             $grade_item->grademax   = $grademax;
1219             $grade_item->grademin   = 0;
1220         }
1221
1222         $grade_item->itemname = $modinstance->name;
1223         $grade_item->idnumber = $modinstance->cmidnumber;
1224
1225         $grade_item->update();
1226
1227         return $grade_item;
1228     }
1229
1230     // create new one
1231     $params = array('courseid'    =>$modinstance->course,
1232                     'itemtype'    =>'mod',
1233                     'itemmodule'  =>$modinstance->modname,
1234                     'iteminstance'=>$modinstance->id,
1235                     'itemnumber'  =>0,
1236                     'itemname'    =>$modinstance->name,
1237                     'idnumber'    =>$modinstance->cmidnumber);
1238
1239     if (is_null($grademax) and is_null($scaleid)) {
1240         $params['gradetype'] = GRADE_TYPE_NONE;
1241
1242     } else if ($scaleid) {
1243         $params['gradetype'] = GRADE_TYPE_SCALE;
1244         $params['scaleid']   = $scaleid;
1245         $grade_item->grademin  = 1;
1246     } else {
1247         $params['gradetype'] = GRADE_TYPE_VALUE;
1248         $params['grademax']  = $grademax;
1249         $params['grademin']  = 0;
1250     }
1251
1252     $grade_item = new grade_item($params);
1253     $grade_item->insert();
1254
1255     return $grade_item;
1256 }
1257
1258 /**
1259  * Remove grade letters for given context
1260  * @param object $context
1261  */
1262 function remove_grade_letters($context, $showfeedback) {
1263     $strdeleted = get_string('deleted');
1264
1265     delete_records('grade_letters', 'contextid', $context->id);
1266     if ($showfeedback) {
1267         notify($strdeleted.' - '.get_string('letters', 'grades'));
1268     }
1269 }
1270 /**
1271  * Remove all grade related course data - history is kept
1272  * @param int $courseid
1273  * @param bool $showfeedback print feedback
1274  */
1275 function remove_course_grades($courseid, $showfeedback) {
1276     $strdeleted = get_string('deleted');
1277
1278     $course_category = grade_category::fetch_course_category($courseid);
1279     $course_category->delete('coursedelete');
1280     if ($showfeedback) {
1281         notify($strdeleted.' - '.get_string('grades', 'grades').', '.get_string('items', 'grades').', '.get_string('categories', 'grades'));
1282     }
1283
1284     if ($outcomes = grade_outcome::fetch_all(array('courseid'=>$courseid))) {
1285         foreach ($outcomes as $outcome) {
1286             $outcome->delete('coursedelete');
1287         }
1288     }
1289     delete_records('grade_outcomes_courses', 'courseid', $courseid);
1290     if ($showfeedback) {
1291         notify($strdeleted.' - '.get_string('outcomes', 'grades'));
1292     }
1293
1294     if ($scales = grade_scale::fetch_all(array('courseid'=>$courseid))) {
1295         foreach ($scales as $scale) {
1296             $scale->delete('coursedelete');
1297         }
1298     }
1299     if ($showfeedback) {
1300         notify($strdeleted.' - '.get_string('scales'));
1301     }
1302
1303     delete_records('grade_settings', 'courseid', $courseid);
1304     if ($showfeedback) {
1305         notify($strdeleted.' - '.get_string('settings', 'grades'));
1306     }
1307 }
1308
1309 /**
1310  * Called when course category deleted - cleanup gradebook
1311  * @param int $categoryid course category id
1312  * @param int $newparentid empty means everything deleted, otherwise id of category where content moved
1313  * @param bool $showfeedback print feedback
1314  */
1315 function grade_course_category_delete($categoryid, $newparentid, $showfeedback) {
1316     $context = get_context_instance(CONTEXT_COURSECAT, $categoryid);
1317     delete_records('grade_letters', 'contextid', $context->id);
1318 }
1319
1320 /**
1321  * Does gradebook cleanup when module uninstalled.
1322  */
1323 function grade_uninstalled_module($modname) {
1324     global $CFG;
1325
1326     $sql = "SELECT *
1327               FROM {$CFG->prefix}grade_items
1328              WHERE itemtype='mod' AND itemmodule='$modname'";
1329
1330     // go all items for this module and delete them including the grades
1331     if ($rs = get_recordset_sql($sql)) {
1332         while ($item = rs_fetch_next_record($rs)) {
1333             $grade_item = new grade_item($item, false);
1334             $grade_item->delete('moduninstall');
1335         }
1336         rs_close($rs);
1337     }
1338 }
1339
1340 /**
1341  * Grading cron job
1342  */
1343 function grade_cron() {
1344     global $CFG;
1345
1346     $now = time();
1347
1348     $sql = "SELECT i.*
1349               FROM {$CFG->prefix}grade_items i
1350              WHERE i.locked = 0 AND i.locktime > 0 AND i.locktime < $now AND EXISTS (
1351                 SELECT 'x' FROM {$CFG->prefix}grade_items c WHERE c.itemtype='course' AND c.needsupdate=0 AND c.courseid=i.courseid)";
1352
1353     // go through all courses that have proper final grades and lock them if needed
1354     if ($rs = get_recordset_sql($sql)) {
1355         while ($item = rs_fetch_next_record($rs)) {
1356             $grade_item = new grade_item($item, false);
1357             $grade_item->locked = $now;
1358             $grade_item->update('locktime');
1359         }
1360         rs_close($rs);
1361     }
1362
1363     $grade_inst = new grade_grade();
1364     $fields = 'g.'.implode(',g.', $grade_inst->required_fields);
1365
1366     $sql = "SELECT $fields
1367               FROM {$CFG->prefix}grade_grades g, {$CFG->prefix}grade_items i
1368              WHERE g.locked = 0 AND g.locktime > 0 AND g.locktime < $now AND g.itemid=i.id AND EXISTS (
1369                 SELECT 'x' FROM {$CFG->prefix}grade_items c WHERE c.itemtype='course' AND c.needsupdate=0 AND c.courseid=i.courseid)";
1370
1371     // go through all courses that have proper final grades and lock them if needed
1372     if ($rs = get_recordset_sql($sql)) {
1373         while ($grade = rs_fetch_next_record($rs)) {
1374             $grade_grade = new grade_grade($grade, false);
1375             $grade_grade->locked = $now;
1376             $grade_grade->update('locktime');
1377         }
1378         rs_close($rs);
1379     }
1380
1381     //TODO: do not run this cleanup every cron invocation
1382     // cleanup history tables
1383     if (!empty($CFG->gradehistorylifetime)) {  // value in days
1384         $histlifetime = $now - ($CFG->gradehistorylifetime * 3600 * 24);
1385         $tables = array('grade_outcomes_history', 'grade_categories_history', 'grade_items_history', 'grade_grades_history', 'scale_history');
1386         foreach ($tables as $table) {
1387             if (delete_records_select($table, "timemodified < $histlifetime")) {
1388                 mtrace("    Deleted old grade history records from '$table'");
1389             }
1390         }
1391     }
1392 }
1393
1394 /**
1395  * Resel all course grades
1396  * @param int $courseid
1397  * @return success
1398  */
1399 function grade_course_reset($courseid) {
1400
1401     // no recalculations
1402     grade_force_full_regrading($courseid);
1403
1404     $grade_items = grade_item::fetch_all(array('courseid'=>$courseid));
1405     foreach ($grade_items as $gid=>$grade_item) {
1406         $grade_item->delete_all_grades('reset');
1407     }
1408
1409     //refetch all grades
1410     grade_grab_course_grades($courseid);
1411
1412     // recalculate all grades
1413     grade_regrade_final_grades($courseid);
1414     return true;
1415 }
1416
1417 /**
1418  * Convert number to 5 decimalfloat, empty tring or null db compatible format
1419  * (we need this to decide if db value changed)
1420  * @param mixed number
1421  * @return mixed float or null
1422  */
1423 function grade_floatval($number) {
1424     if (is_null($number) or $number === '') {
1425         return null;
1426     }
1427     // we must round to 5 digits to get the same precision as in 10,5 db fields
1428     // note: db rounding for 10,5 is different from php round() function
1429     return round($number, 5);
1430 }
1431
1432 /**
1433  * Compare two float numbers safely. Uses 5 decimals php precision. Nulls accepted too.
1434  * Used for skipping of db updates
1435  * @param float $f1
1436  * @param float $f2
1437  * @return true if different
1438  */
1439 function grade_floats_different($f1, $f2) {
1440     // note: db rounding for 10,5 is different from php round() function
1441     return (grade_floatval($f1) !== grade_floatval($f2));
1442 }
1443
1444 ?>