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 /***** END OF PUBLIC API *****/
 437
 438
 439 /**
 440  * Returns course gradebook setting
 441  * @param int $courseid
 442  * @param string $name of setting, maybe null if reset only
 443  * @param bool $resetcache force reset of internal static cache
 444  * @return string value, NULL if no setting
 445  */
 446 function grade_get_setting($courseid, $name, $default=null, $resetcache=false) {
 447     static $cache = array();
 448
 449     if ($resetcache or !array_key_exists($courseid, $cache)) {
 450         $cache[$courseid] = array();
 451
 452     } else if (is_null($name)) {
 453         return null;
 454
 455     } else if (array_key_exists($name, $cache[$courseid])) {
 456         return $cache[$courseid][$name];
 457     }
 458
 459     if (!$data = get_record('grade_settings', 'courseid', $courseid, 'name', addslashes($name))) {
 460         $result = null;
 461     } else {
 462         $result = $data->value;
 463     }
 464
 465     if (is_null($result)) {
 466         $result = $default;
 467     }
 468
 469     $cache[$courseid][$name] = $result;
 470     return $result;
 471 }
 472
 473 /**
 474  * Returns all course gradebook settings as object properties
 475  * @param int $courseid
 476  * @return object
 477  */
 478 function grade_get_settings($courseid) {
 479      $settings = new object();
 480      $settings->id = $courseid;
 481
 482     if ($records = get_records('grade_settings', 'courseid', $courseid)) {
 483         foreach ($records as $record) {
 484             $settings->{$record->name} = $record->value;
 485         }
 486     }
 487
 488     return $settings;
 489 }
 490
 491 /**
 492  * Add/update course gradebook setting
 493  * @param int $courseid
 494  * @param string $name of setting
 495  * @param string value, NULL means no setting==remove
 496  * @return void
 497  */
 498 function grade_set_setting($courseid, $name, $value) {
 499     if (is_null($value)) {
 500         delete_records('grade_settings', 'courseid', $courseid, 'name', addslashes($name));
 501
 502     } else if (!$existing = get_record('grade_settings', 'courseid', $courseid, 'name', addslashes($name))) {
 503         $data = new object();
 504         $data->courseid = $courseid;
 505         $data->name     = addslashes($name);
 506         $data->value    = addslashes($value);
 507         insert_record('grade_settings', $data);
 508
 509     } else {
 510         $data = new object();
 511         $data->id       = $existing->id;
 512         $data->value    = addslashes($value);
 513         update_record('grade_settings', $data);
 514     }
 515
 516     grade_get_setting($courseid, null, null, true); // reset the cache
 517 }
 518
 519 /**
 520  * Returns string representation of grade value
 521  * @param float $value grade value
 522  * @param object $grade_item - by reference to prevent scale reloading
 523  * @param bool $localized use localised decimal separator
 524  * @param int $display type of display - raw, letter, percentage
 525  * @param int $decimalplaces number of decimal places when displaying float values
 526  * @return string
 527  */
 528 function grade_format_gradevalue($value, &$grade_item, $localized=true, $displaytype=null, $decimals=null) {
 529     if ($grade_item->gradetype == GRADE_TYPE_NONE or $grade_item->gradetype == GRADE_TYPE_TEXT) {
 530         return '';
 531     }
 532
 533     // no grade yet?
 534     if (is_null($value)) {
 535         return '-';
 536     }
 537
 538     if ($grade_item->gradetype != GRADE_TYPE_VALUE and $grade_item->gradetype != GRADE_TYPE_SCALE) {
 539         //unknown type??
 540         return '';
 541     }
 542
 543     if (is_null($displaytype)) {
 544         $displaytype = $grade_item->get_displaytype();
 545     }
 546
 547     if (is_null($decimals)) {
 548         $decimals = $grade_item->get_decimals();
 549     }
 550
 551     switch ($displaytype) {
 552         case GRADE_DISPLAY_TYPE_REAL:
 553             if ($grade_item->gradetype == GRADE_TYPE_SCALE) {
 554                 if (!$scale = $grade_item->load_scale()) {
 555                     return get_string('error');
 556                 }
 557
 558                 $value = (int)bounded_number($grade_item->grademin, $value, $grade_item->grademax);
 559                 return format_string($scale->scale_items[$value-1]);
 560
 561             } else {
 562                 return format_float($value, $decimals, $localized);
 563             }
 564
 565         case GRADE_DISPLAY_TYPE_PERCENTAGE:
 566             $min = $grade_item->grademin;
 567             $max = $grade_item->grademax;
 568             if ($min == $max) {
 569                 return '';
 570             }
 571             $value = bounded_number($min, $value, $max);
 572             $percentage = (($value-$min)*100)/($max-$min);
 573             return format_float($percentage, $decimals, $localized).' %';
 574
 575         case GRADE_DISPLAY_TYPE_LETTER:
 576             $context = get_context_instance(CONTEXT_COURSE, $grade_item->courseid);
 577             if (!$letters = grade_get_letters($context)) {
 578                 return ''; // no letters??
 579             }
 580
 581             $value = grade_grade::standardise_score($value, $grade_item->grademin, $grade_item->grademax, 0, 100);
 582             $value = bounded_number(0, $value, 100); // just in case
 583             foreach ($letters as $boundary => $letter) {
 584                 if ($value >= $boundary) {
 585                     return format_string($letter);
 586                 }
 587             }
 588             return '-'; // no match? maybe '' would be more correct
 589
 590         default:
 591             return '';
 592     }
 593 }
 594
 595 /**
 596  * Returns grade letters array used in context
 597  * @param object $context object or null for defaults
 598  * @return array of grade_boundary=>letter_string
 599  */
 600 function grade_get_letters($context=null) {
 601     if (empty($context)) {
 602         //default grading letters
 603         return array('93'=>'A', '90'=>'A-', '87'=>'B+', '83'=>'B', '80'=>'B-', '77'=>'C+', '73'=>'C', '70'=>'C-', '67'=>'D+', '60'=>'D', '0'=>'F');
 604     }
 605
 606     static $cache = array();
 607
 608     if (array_key_exists($context->id, $cache)) {
 609         return $cache[$context->id];
 610     }
 611
 612     if (count($cache) > 100) {
 613         $cache = array(); // cache size limit
 614     }
 615
 616     $letters = array();
 617
 618     $contexts = get_parent_contexts($context);
 619     array_unshift($contexts, $context->id);
 620
 621     foreach ($contexts as $ctxid) {
 622         if ($records = get_records('grade_letters', 'contextid', $ctxid, 'lowerboundary DESC')) {
 623             foreach ($records as $record) {
 624                 $letters[$record->lowerboundary] = $record->letter;
 625             }
 626         }
 627
 628         if (!empty($letters)) {
 629             $cache[$context->id] = $letters;
 630             return $letters;
 631         }
 632     }
 633
 634     $letters = grade_get_letters(null);
 635     $cache[$context->id] = $letters;
 636     return $letters;
 637 }
 638
 639
 640 /**
 641  * Verify new value of idnumber - checks for uniqueness of new idnumbers, old are kept intact
 642  * @param string idnumber string (with magic quotes)
 643  * @param object $cm used for course module idnumbers and items attached to modules
 644  * @param object $gradeitem is item idnumber
 645  * @return boolean true means idnumber ok
 646  */
 647 function grade_verify_idnumber($idnumber, $grade_item=null, $cm=null) {
 648     if ($idnumber == '') {
 649         //we allow empty idnumbers
 650         return true;
 651     }
 652
 653     // keep existing even when not unique
 654     if ($cm and $cm->idnumber == $idnumber) {
 655         return true;
 656     } else if ($grade_item and $grade_item->idnumber == $idnumber) {
 657         return true;
 658     }
 659
 660     if (get_records('course_modules', 'idnumber', $idnumber)) {
 661         return false;
 662     }
 663
 664     if (get_records('grade_items', 'idnumber', $idnumber)) {
 665         return false;
 666     }
 667
 668     return true;
 669 }
 670
 671 /**
 672  * Force final grade recalculation in all course items
 673  * @param int $courseid
 674  */
 675 function grade_force_full_regrading($courseid) {
 676     set_field('grade_items', 'needsupdate', 1, 'courseid', $courseid);
 677 }
 678
 679 /**
 680  * Updates all final grades in course.
 681  *
 682  * @param int $courseid
 683  * @param int $userid if specified, try to do a quick regrading of grades of this user only
 684  * @param object $updated_item the item in which
 685  * @return boolean true if ok, array of errors if problems found (item id is used as key)
 686  */
 687 function grade_regrade_final_grades($courseid, $userid=null, $updated_item=null) {
 688
 689     $course_item = grade_item::fetch_course_item($courseid);
 690
 691     if ($userid) {
 692         // one raw grade updated for one user
 693         if (empty($updated_item)) {
 694             error("updated_item_id can not be null!");
 695         }
 696         if ($course_item->needsupdate) {
 697             $updated_item->force_regrading();
 698             return 'Can not do fast regrading after updating of raw grades';
 699         }
 700
 701     } else {
 702         if (!$course_item->needsupdate) {
 703             // nothing to do :-)
 704             return true;
 705         }
 706     }
 707
 708     $grade_items = grade_item::fetch_all(array('courseid'=>$courseid));
 709     $depends_on = array();
 710
 711     // first mark all category and calculated items as needing regrading
 712     // this is slower, but 100% accurate
 713     foreach ($grade_items as $gid=>$gitem) {
 714         if (!empty($updated_item) and $updated_item->id == $gid) {
 715             $grade_items[$gid]->needsupdate = 1;
 716
 717         } else if ($gitem->is_course_item() or $gitem->is_category_item() or $gitem->is_calculated()) {
 718             $grade_items[$gid]->needsupdate = 1;
 719         }
 720
 721         // construct depends_on lookup array
 722         $depends_on[$gid] = $grade_items[$gid]->depends_on();
 723     }
 724
 725     $errors = array();
 726     $finalids = array();
 727     $gids     = array_keys($grade_items);
 728     $failed = 0;
 729
 730     while (count($finalids) < count($gids)) { // work until all grades are final or error found
 731         $count = 0;
 732         foreach ($gids as $gid) {
 733             if (in_array($gid, $finalids)) {
 734                 continue; // already final
 735             }
 736
 737             if (!$grade_items[$gid]->needsupdate) {
 738                 $finalids[] = $gid; // we can make it final - does not need update
 739                 continue;
 740             }
 741
 742             $doupdate = true;
 743             foreach ($depends_on[$gid] as $did) {
 744                 if (!in_array($did, $finalids)) {
 745                     $doupdate = false;
 746                     continue; // this item depends on something that is not yet in finals array
 747                 }
 748             }
 749
 750             //oki - let's update, calculate or aggregate :-)
 751             if ($doupdate) {
 752                 $result = $grade_items[$gid]->regrade_final_grades($userid);
 753
 754                 if ($result === true) {
 755                     $grade_items[$gid]->regrading_finished();
 756                     $grade_items[$gid]->check_locktime(); // do the locktime item locking
 757                     $count++;
 758                     $finalids[] = $gid;
 759
 760                 } else {
 761                     $grade_items[$gid]->force_regrading();
 762                     $errors[$gid] = $result;
 763                 }
 764             }
 765         }
 766
 767         if ($count == 0) {
 768             $failed++;
 769         } else {
 770             $failed = 0;
 771         }
 772
 773         if ($failed > 1) {
 774             foreach($gids as $gid) {
 775                 if (in_array($gid, $finalids)) {
 776                     continue; // this one is ok
 777                 }
 778                 $grade_items[$gid]->force_regrading();
 779                 $errors[$grade_items[$gid]->id] = 'Probably circular reference or broken calculation formula'; // TODO: localize
 780             }
 781             break; // oki, found error
 782         }
 783     }
 784
 785     if (count($errors) == 0) {
 786         if (empty($userid)) {
 787             // do the locktime locking of grades, but only when doing full regrading
 788             grade_grade::check_locktime_all($gids);
 789         }
 790         return true;
 791     } else {
 792         return $errors;
 793     }
 794 }
 795
 796 /**
 797  * For backwards compatibility with old third-party modules, this function can
 798  * be used to import all grades from activities with legacy grading.
 799  * @param int $courseid or null if all courses
 800  */
 801 function grade_grab_legacy_grades($courseid=null) {
 802
 803     global $CFG;
 804
 805     if (!$mods = get_list_of_plugins('mod') ) {
 806         error('No modules installed!');
 807     }
 808
 809     if ($courseid) {
 810         $course_sql = " AND cm.course=$courseid";
 811     } else {
 812         $course_sql = "";
 813     }
 814
 815     foreach ($mods as $mod) {
 816
 817         if ($mod == 'NEWMODULE') {   // Someone has unzipped the template, ignore it
 818             continue;
 819         }
 820
 821         if (!$module = get_record('modules', 'name', $mod)) {
 822             //not installed
 823             continue;
 824         }
 825
 826         if (!$module->visible) {
 827             //disabled module
 828             continue;
 829         }
 830
 831         $fullmod = $CFG->dirroot.'/mod/'.$mod;
 832
 833         // include the module lib once
 834         if (file_exists($fullmod.'/lib.php')) {
 835             include_once($fullmod.'/lib.php');
 836             // look for modname_grades() function - old gradebook pulling function
 837             // if present sync the grades with new grading system
 838             $gradefunc = $mod.'_grades';
 839             if (function_exists($gradefunc)) {
 840
 841                 // get all instance of the activity
 842                 $sql = "SELECT a.*, cm.idnumber as cmidnumber, m.name as modname
 843                           FROM {$CFG->prefix}$mod a, {$CFG->prefix}course_modules cm, {$CFG->prefix}modules m
 844                          WHERE m.name='$mod' AND m.id=cm.module AND cm.instance=a.id $course_sql";
 845
 846                 if ($modinstances = get_records_sql($sql)) {
 847                     foreach ($modinstances as $modinstance) {
 848                         grade_update_mod_grades($modinstance);
 849                     }
 850                 }
 851             }
 852         }
 853     }
 854 }
 855
 856 /**
 857  * For testing purposes mainly, reloads grades from all non legacy modules into gradebook.
 858  */
 859 function grade_grab_grades() {
 860
 861     global $CFG;
 862
 863     if (!$mods = get_list_of_plugins('mod') ) {
 864         error('No modules installed!');
 865     }
 866
 867     foreach ($mods as $mod) {
 868
 869         if ($mod == 'NEWMODULE') {   // Someone has unzipped the template, ignore it
 870             continue;
 871         }
 872
 873         if (!$module = get_record('modules', 'name', $mod)) {
 874             //not installed
 875             continue;
 876         }
 877
 878         if (!$module->visible) {
 879             //disabled module
 880             continue;
 881         }
 882
 883         $fullmod = $CFG->dirroot.'/mod/'.$mod;
 884
 885         // include the module lib once
 886         if (file_exists($fullmod.'/lib.php')) {
 887             include_once($fullmod.'/lib.php');
 888             // look for modname_grades() function - old gradebook pulling function
 889             // if present sync the grades with new grading system
 890             $gradefunc = $mod.'_update_grades';
 891             if (function_exists($gradefunc)) {
 892                 $gradefunc();
 893             }
 894         }
 895     }
 896 }
 897
 898 /**
 899  * Force full update of module grades in central gradebook - works for both legacy and converted activities.
 900  * @param object $modinstance object with extra cmidnumber and modname property
 901  * @return boolean success
 902  */
 903 function grade_update_mod_grades($modinstance, $userid=0) {
 904     global $CFG;
 905
 906     $fullmod = $CFG->dirroot.'/mod/'.$modinstance->modname;
 907     if (!file_exists($fullmod.'/lib.php')) {
 908         debugging('missing lib.php file in module');
 909         return false;
 910     }
 911     include_once($fullmod.'/lib.php');
 912
 913     // does it use legacy grading?
 914     $gradefunc        = $modinstance->modname.'_grades';
 915     $updategradesfunc = $modinstance->modname.'_update_grades';
 916     $updateitemfunc   = $modinstance->modname.'_grade_item_update';
 917
 918     if (function_exists($gradefunc)) {
 919
 920         // legacy module - not yet converted
 921         if ($oldgrades = $gradefunc($modinstance->id)) {
 922
 923             $grademax = $oldgrades->maxgrade;
 924             $scaleid = NULL;
 925             if (!is_numeric($grademax)) {
 926                 // scale name is provided as a string, try to find it
 927                 if (!$scale = get_record('scale', 'name', $grademax)) {
 928                     debugging('Incorrect scale name! name:'.$grademax);
 929                     return false;
 930                 }
 931                 $scaleid = $scale->id;
 932             }
 933
 934             if (!$grade_item = grade_get_legacy_grade_item($modinstance, $grademax, $scaleid)) {
 935                 debugging('Can not get/create legacy grade item!');
 936                 return false;
 937             }
 938
 939             $grades = array();
 940             foreach ($oldgrades->grades as $uid=>$usergrade) {
 941                 if ($userid and $uid != $userid) {
 942                     continue;
 943                 }
 944                 $grade = new object();
 945                 $grade->userid = $uid;
 946
 947                 if ($usergrade == '-') {
 948                     // no grade
 949                     $grade->rawgrade = null;
 950
 951                 } else if ($scaleid) {
 952                     // scale in use, words used
 953                     $gradescale = explode(",", $scale->scale);
 954                     $grade->rawgrade = array_search($usergrade, $gradescale) + 1;
 955
 956                 } else {
 957                     // good old numeric value
 958                     $grade->rawgrade = $usergrade;
 959                 }
 960                 $grades[] = $grade;
 961             }
 962
 963             grade_update('legacygrab', $grade_item->courseid, $grade_item->itemtype, $grade_item->itemmodule,
 964                          $grade_item->iteminstance, $grade_item->itemnumber, $grades);
 965         }
 966
 967     } else if (function_exists($updategradesfunc) and function_exists($updateitemfunc)) {
 968         //new grading supported, force updating of grades
 969         $updateitemfunc($modinstance);
 970         $updategradesfunc($modinstance, $userid);
 971
 972     } else {
 973         // mudule does not support grading??
 974     }
 975
 976     return true;
 977 }
 978
 979 /**
 980  * Get and update/create grade item for legacy modules.
 981  */
 982 function grade_get_legacy_grade_item($modinstance, $grademax, $scaleid) {
 983
 984     // does it already exist?
 985     if ($grade_items = grade_item::fetch_all(array('courseid'=>$modinstance->course, 'itemtype'=>'mod', 'itemmodule'=>$modinstance->modname, 'iteminstance'=>$modinstance->id, 'itemnumber'=>0))) {
 986         if (count($grade_items) > 1) {
 987             debugging('Multiple legacy grade_items found.');
 988             return false;
 989         }
 990
 991         $grade_item = reset($grade_items);
 992
 993         if (is_null($grademax) and is_null($scaleid)) {
 994            $grade_item->gradetype  = GRADE_TYPE_NONE;
 995
 996         } else if ($scaleid) {
 997             $grade_item->gradetype = GRADE_TYPE_SCALE;
 998             $grade_item->scaleid   = $scaleid;
 999             $grade_item->grademin  = 1;
1000
1001         } else {
1002             $grade_item->gradetype  = GRADE_TYPE_VALUE;
1003             $grade_item->grademax   = $grademax;
1004             $grade_item->grademin   = 0;
1005         }
1006
1007         $grade_item->itemname = $modinstance->name;
1008         $grade_item->idnumber = $modinstance->cmidnumber;
1009
1010         $grade_item->update();
1011
1012         return $grade_item;
1013     }
1014
1015     // create new one
1016     $params = array('courseid'    =>$modinstance->course,
1017                     'itemtype'    =>'mod',
1018                     'itemmodule'  =>$modinstance->modname,
1019                     'iteminstance'=>$modinstance->id,
1020                     'itemnumber'  =>0,
1021                     'itemname'    =>$modinstance->name,
1022                     'idnumber'    =>$modinstance->cmidnumber);
1023
1024     if (is_null($grademax) and is_null($scaleid)) {
1025         $params['gradetype'] = GRADE_TYPE_NONE;
1026
1027     } else if ($scaleid) {
1028         $params['gradetype'] = GRADE_TYPE_SCALE;
1029         $params['scaleid']   = $scaleid;
1030         $grade_item->grademin  = 1;
1031     } else {
1032         $params['gradetype'] = GRADE_TYPE_VALUE;
1033         $params['grademax']  = $grademax;
1034         $params['grademin']  = 0;
1035     }
1036
1037     $grade_item = new grade_item($params);
1038     $grade_item->insert();
1039
1040     return $grade_item;
1041 }
1042
1043 /**
1044  * Remove grade letters for given context
1045  * @param object $context
1046  */
1047 function remove_grade_letters($context, $showfeedback) {
1048     $strdeleted = get_string('deleted');
1049
1050     delete_records('grade_letters', 'contextid', $context->id);
1051     if ($showfeedback) {
1052         notify($strdeleted.' - '.get_string('letters', 'grades'));
1053     }
1054 }
1055 /**
1056  * Remove all grade related course data - history is kept
1057  * @param int $courseid
1058  * @param bool @showfeedback print feedback
1059  */
1060 function remove_course_grades($courseid, $showfeedback) {
1061     $strdeleted = get_string('deleted');
1062
1063     $course_category = grade_category::fetch_course_category($courseid);
1064     $course_category->delete('coursedelete');
1065     if ($showfeedback) {
1066         notify($strdeleted.' - '.get_string('grades', 'grades').', '.get_string('items', 'grades').', '.get_string('categories', 'grades'));
1067     }
1068
1069     if ($outcomes = grade_outcome::fetch_all(array('courseid'=>$courseid))) {
1070         foreach ($outcomes as $outcome) {
1071             $outcome->delete('coursedelete');
1072         }
1073     }
1074     delete_records('grade_outcomes_courses', 'courseid', $courseid);
1075     if ($showfeedback) {
1076         notify($strdeleted.' - '.get_string('outcomes', 'grades'));
1077     }
1078
1079     if ($scales = grade_scale::fetch_all(array('courseid'=>$courseid))) {
1080         foreach ($scales as $scale) {
1081             $scale->delete('coursedelete');
1082         }
1083     }
1084     if ($showfeedback) {
1085         notify($strdeleted.' - '.get_string('scales'));
1086     }
1087
1088     delete_records('grade_settings', 'courseid', $courseid);
1089     if ($showfeedback) {
1090         notify($strdeleted.' - '.get_string('settings', 'grades'));
1091     }
1092 }
1093
1094 /**
1095  * Builds an array of percentages indexed by integers for the purpose of building a select drop-down element.
1096  * @param int $steps The value between each level.
1097  * @param string $order 'asc' for 0-100 and 'desc' for 100-0
1098  * @param int $lowest The lowest value to include
1099  * @param int $highest The highest value to include
1100  */
1101 function build_percentages_array($steps=1, $order='desc', $lowest=0, $highest=100) {
1102     // TODO reject or implement
1103 }
1104
1105 /**
1106  * Grading cron job
1107  */
1108 function grade_cron() {
1109     global $CFG;
1110
1111     $now = time();
1112
1113     $sql = "SELECT i.*
1114               FROM {$CFG->prefix}grade_items i
1115              WHERE i.locked = 0 AND i.locktime > 0 AND i.locktime < $now AND EXISTS (
1116                 SELECT 'x' FROM {$CFG->prefix}grade_items c WHERE c.itemtype='course' AND c.needsupdate=0 AND c.courseid=i.courseid)";
1117
1118     // go through all courses that have proper final grades and lock them if needed
1119     if ($rs = get_recordset_sql($sql)) {
1120         while ($item = rs_fetch_next_record($rs)) {
1121             $grade_item = new grade_item($item, false);
1122             $grade_item->locked = $now;
1123             $grade_item->update('locktime');
1124         }
1125         rs_close($rs);
1126     }
1127
1128     $grade_inst = new grade_grade();
1129     $fields = 'g.'.implode(',g.', $grade_inst->required_fields);
1130
1131     $sql = "SELECT $fields
1132               FROM {$CFG->prefix}grade_grades g, {$CFG->prefix}grade_items i
1133              WHERE g.locked = 0 AND g.locktime > 0 AND g.locktime < $now AND g.itemid=i.id AND EXISTS (
1134                 SELECT 'x' FROM {$CFG->prefix}grade_items c WHERE c.itemtype='course' AND c.needsupdate=0 AND c.courseid=i.courseid)";
1135
1136     // go through all courses that have proper final grades and lock them if needed
1137     if ($rs = get_recordset_sql($sql)) {
1138         while ($grade = rs_fetch_next_record($rs)) {
1139             $grade_grade = new grade_grade($grade, false);
1140             $grade_grade->locked = $now;
1141             $grade_grade->update('locktime');
1142         }
1143         rs_close($rs);
1144     }
1145
1146 }
1147
1148 ?>