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