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'.
  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');
  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
 191         if (array_key_exists('rawgrade', $grade)) {
 192             $rawgrade = $grade['rawgrade'];
 193         }
 194
 195         if (array_key_exists('feedback', $grade)) {
 196             $feedback = $grade['feedback'];
 197         }
 198
 199         if (array_key_exists('feedbackformat', $grade)) {
 200             $feedbackformat = $grade['feedbackformat'];
 201         }
 202
 203         if (array_key_exists('usermodified', $grade)) {
 204             $usermodified = $grade['usermodified'];
 205         } else {
 206             $usermodified = $USER->id;
 207         }
 208
 209         // update or insert the grade
 210         if (!$grade_item->update_raw_grade($userid, $rawgrade, $source, null, $feedback, $feedbackformat, $usermodified)) {
 211             $failed = true;
 212         }
 213     }
 214
 215     if (!$failed) {
 216         return GRADE_UPDATE_OK;
 217     } else {
 218         return GRADE_UPDATE_FAILED;
 219     }
 220 }
 221
 222 /**
 223  * Updates outcomes of user
 224  * Manual outcomes can not be updated.
 225  * @param string $source source of the grade such as 'mod/assignment'
 226  * @param int $courseid id of course
 227  * @param string $itemtype 'mod', 'block'
 228  * @param string $itemmodule 'forum, 'quiz', etc.
 229  * @param int $iteminstance id of the item module
 230  * @param int $userid ID of the graded user
 231  * @param array $data array itemnumber=>outcomegrade
 232  */
 233 function grade_update_outcomes($source, $courseid, $itemtype, $itemmodule, $iteminstance, $userid, $data) {
 234     if ($items = grade_item::fetch_all(array('itemtype'=>$itemtype, 'itemmodule'=>$itemmodule, 'iteminstance'=>$iteminstance, 'courseid'=>$courseid))) {
 235         foreach ($items as $item) {
 236             if (!array_key_exists($item->itemnumber, $data)) {
 237                 continue;
 238             }
 239             $grade = $data[$item->itemnumber] < 1 ? null : $data[$item->itemnumber];
 240             $item->update_final_grade($userid, $grade, $source);
 241         }
 242     }
 243 }
 244
 245 /**
 246  * Returns grading information for given activity - optionally with users grades
 247  * Manual, course or category items can not be queried.
 248  * @param int $courseid id of course
 249  * @param string $itemtype 'mod', 'block'
 250  * @param string $itemmodule 'forum, 'quiz', etc.
 251  * @param int $iteminstance id of the item module
 252  * @param int $userid optional id of the graded user; if userid not used, returns only information about grade_item
 253  * @return array of grade information objects (scaleid, name, grade and locked status, etc.) indexed with itemnumbers
 254  */
 255 function grade_get_grades($courseid, $itemtype, $itemmodule, $iteminstance, $userid_or_ids=0) {
 256     global $CFG;
 257
 258     $return = new object();
 259     $return->items    = array();
 260     $return->outcomes = array();
 261
 262     $course_item = grade_item::fetch_course_item($courseid);
 263     $needsupdate = array();
 264     if ($course_item->needsupdate) {
 265         $result = grade_regrade_final_grades($courseid);
 266         if ($result !== true) {
 267             $needsupdate = array_keys($result);
 268         }
 269     }
 270
 271     if ($grade_items = grade_item::fetch_all(array('itemtype'=>$itemtype, 'itemmodule'=>$itemmodule, 'iteminstance'=>$iteminstance, 'courseid'=>$courseid))) {
 272         foreach ($grade_items as $grade_item) {
 273             $decimalpoints = null;
 274
 275             if (empty($grade_item->outcomeid)) {
 276                 // prepare information about grade item
 277                 $item = new object();
 278                 $item->itemnumber = $grade_item->itemnumber;
 279                 $item->scaleid    = $grade_item->scaleid;
 280                 $item->name       = $grade_item->get_name();
 281                 $item->grademin   = $grade_item->grademin;
 282                 $item->grademax   = $grade_item->grademax;
 283                 $item->gradepass  = $grade_item->gradepass;
 284                 $item->locked     = $grade_item->is_locked();
 285                 $item->hidden     = $grade_item->is_hidden();
 286                 $item->grades     = array();
 287
 288                 switch ($grade_item->gradetype) {
 289                     case GRADE_TYPE_NONE:
 290                         continue;
 291
 292                     case GRADE_TYPE_VALUE:
 293                         $item->scaleid = 0;
 294                         break;
 295
 296                     case GRADE_TYPE_TEXT:
 297                         $item->scaleid   = 0;
 298                         $item->grademin   = 0;
 299                         $item->grademax   = 0;
 300                         $item->gradepass  = 0;
 301                         break;
 302                 }
 303
 304                 if (empty($userid_or_ids)) {
 305                     $userids = array();
 306
 307                 } else if (is_array($userid_or_ids)) {
 308                     $userids = $userid_or_ids;
 309
 310                 } else {
 311                     $userids = array($userid_or_ids);
 312                 }
 313
 314                 if ($userids) {
 315                     $grade_grades = grade_grade::fetch_users_grades($grade_item, $userids, true);
 316                     foreach ($userids as $userid) {
 317                         $grade_grades[$userid]->grade_item =& $grade_item;
 318
 319                         $grade = new object();
 320                         $grade->grade          = $grade_grades[$userid]->finalgrade;
 321                         $grade->locked         = $grade_grades[$userid]->is_locked();
 322                         $grade->hidden         = $grade_grades[$userid]->is_hidden();
 323                         $grade->overridden     = $grade_grades[$userid]->overridden;
 324                         $grade->feedback       = $grade_grades[$userid]->feedback;
 325                         $grade->feedbackformat = $grade_grades[$userid]->feedbackformat;
 326                         $grade->usermodified   = $grade_grades[$userid]->usermodified;
 327
 328                         // create text representation of grade
 329                         if (in_array($grade_item->id, $needsupdate)) {
 330                             $grade->grade     = false;
 331                             $grade->str_grade = get_string('error');
 332
 333                         } else if (is_null($grade->grade)) {
 334                             $grade->str_grade = '-';
 335
 336                         } else {
 337                             $grade->str_grade = grade_format_gradevalue($grade->grade, $grade_item);
 338                         }
 339
 340                         // create html representation of feedback
 341                         if (is_null($grade->feedback)) {
 342                             $grade->str_feedback = '';
 343                         } else {
 344                             $grade->str_feedback = format_text($grade->feedback, $grade->feedbackformat);
 345                         }
 346
 347                         $item->grades[$userid] = $grade;
 348                     }
 349                 }
 350                 $return->items[$grade_item->itemnumber] = $item;
 351
 352             } else {
 353                 if (!$grade_outcome = grade_outcome::fetch(array('id'=>$grade_item->outcomeid))) {
 354                     debugging('Incorect outcomeid found');
 355                     continue;
 356                 }
 357
 358                 // outcome info
 359                 $outcome = new object();
 360                 $outcome->itemnumber = $grade_item->itemnumber;
 361                 $outcome->scaleid    = $grade_outcome->scaleid;
 362                 $outcome->name       = $grade_outcome->get_name();
 363                 $outcome->locked     = $grade_item->is_locked();
 364                 $outcome->hidden     = $grade_item->is_hidden();
 365
 366                 if (empty($userid_or_ids)) {
 367                     $userids = array();
 368                 } else if (is_array($userid_or_ids)) {
 369                     $userids = $userid_or_ids;
 370                 } else {
 371                     $userids = array($userid_or_ids);
 372                 }
 373
 374                 if ($userids) {
 375                     $grade_grades = grade_grade::fetch_users_grades($grade_item, $userids, true);
 376                     foreach ($userids as $userid) {
 377                         $grade_grades[$userid]->grade_item =& $grade_item;
 378
 379                         $grade = new object();
 380                         $grade->grade          = $grade_grades[$userid]->finalgrade;
 381                         $grade->locked         = $grade_grades[$userid]->is_locked();
 382                         $grade->hidden         = $grade_grades[$userid]->is_hidden();
 383                         $grade->feedback       = $grade_grades[$userid]->feedback;
 384                         $grade->feedbackformat = $grade_grades[$userid]->feedbackformat;
 385                         $grade->usermodified   = $grade_grades[$userid]->usermodified;
 386
 387                         // create text representation of grade
 388                         if (in_array($grade_item->id, $needsupdate)) {
 389                             $grade->grade     = false;
 390                             $grade->str_grade = get_string('error');
 391
 392                         } else if (is_null($grade->grade)) {
 393                             $grade->grade = 0;
 394                             $grade->str_grade = get_string('nooutcome', 'grades');
 395
 396                         } else {
 397                             $grade->grade = (int)$grade->grade;
 398                             $scale = $grade_item->load_scale();
 399                             $grade->str_grade = format_string($scale->scale_items[(int)$grade->grade-1]);
 400                         }
 401
 402                         // create html representation of feedback
 403                         if (is_null($grade->feedback)) {
 404                             $grade->str_feedback = '';
 405                         } else {
 406                             $grade->str_feedback = format_text($grade->feedback, $grade->feedbackformat);
 407                         }
 408
 409                         $outcome->grades[$userid] = $grade;
 410                     }
 411                 }
 412                 $return->outcomes[$grade_item->itemnumber] = $outcome;
 413
 414             }
 415         }
 416     }
 417
 418     // sort results using itemnumbers
 419     ksort($return->items, SORT_NUMERIC);
 420     ksort($return->outcomes, SORT_NUMERIC);
 421
 422     return $return;
 423 }
 424
 425 /***** END OF PUBLIC API *****/
 426
 427 /**
 428  * Returns string representation of grade value
 429  * @param float $value grade value
 430  * @param object $grade_item - by reference to prevent scale reloading
 431  * @param bool $localized use localised decimal separator
 432  * @param int $display type of display - raw, letter, percentage
 433  * @param int $decimalplaces number of decimal places when displaying float values
 434  * @return string
 435  */
 436 function grade_format_gradevalue($value, &$grade_item, $localized=true, $displaytype=null, $decimals=null) {
 437     if ($grade_item->gradetype == GRADE_TYPE_NONE or $grade_item->gradetype == GRADE_TYPE_TEXT) {
 438         return '';
 439     }
 440
 441     // no grade yet?
 442     if (is_null($value)) {
 443         return '-';
 444     }
 445
 446     if ($grade_item->gradetype != GRADE_TYPE_VALUE and $grade_item->gradetype != GRADE_TYPE_SCALE) {
 447         //unknown type??
 448         return '';
 449     }
 450
 451     if (is_null($displaytype)) {
 452         $displaytype = $grade_item->get_displaytype();
 453     }
 454
 455     if (is_null($decimals)) {
 456         $decimals = $grade_item->get_decimals();
 457     }
 458
 459     switch ($displaytype) {
 460         case GRADE_DISPLAY_TYPE_REAL:
 461             if ($grade_item->gradetype == GRADE_TYPE_SCALE) {
 462                 $scale = $grade_item->load_scale();
 463                 $value = (int)bounded_number($grade_item->grademin, $value, $grade_item->grademax);
 464                 return format_string($scale->scale_items[$value-1]);
 465
 466             } else {
 467                 return format_float($value, $decimals, $localized);
 468             }
 469
 470         case GRADE_DISPLAY_TYPE_PERCENTAGE:
 471             $min = $grade_item->grademin;
 472             $max = $grade_item->grademax;
 473             if ($min == $max) {
 474                 return '';
 475             }
 476             $value = bounded_number($min, $value, $max);
 477             $percentage = (($value-$min)*100)/($max-$min);
 478             return format_float($percentage, $decimals, $localized).' %';
 479
 480         case GRADE_DISPLAY_TYPE_LETTER:
 481             $context = get_context_instance(CONTEXT_COURSE, $grade_item->courseid);
 482             if (!$letters = grade_get_letters($context)) {
 483                 return ''; // no letters??
 484             }
 485
 486             $value = grade_grade::standardise_score($value, $grade_item->grademin, $grade_item->grademax, 0, 100);
 487             $value = bounded_number(0, $value, 100); // just in case
 488             foreach ($letters as $boundary => $letter) {
 489                 if ($value >= $boundary) {
 490                     return format_string($letter);
 491                 }
 492             }
 493             return '-'; // no match? maybe '' would be more correct
 494
 495         default:
 496             return '';
 497     }
 498 }
 499
 500 /**
 501  * Returns grade letters array used in context
 502  * @param object $context object or null for defaults
 503  * @return array of grade_boundary=>letter_string
 504  */
 505 function grade_get_letters($context=null) {
 506     if (empty($context)) {
 507         //default grading letters
 508         return array('93'=>'A', '90'=>'A-', '87'=>'B+', '83'=>'B', '80'=>'B-', '77'=>'C+', '73'=>'C', '70'=>'C-', '67'=>'D+', '60'=>'D', '0'=>'F');
 509     }
 510
 511     static $cache = array();
 512
 513     if (array_key_exists($context->id, $cache)) {
 514         return $cache[$context->id];
 515     }
 516
 517     if (count($cache) > 100) {
 518         $cache = array(); // cache size limit
 519     }
 520
 521     $letters = array();
 522
 523     $contexts = get_parent_contexts($context);
 524     array_unshift($contexts, $context->id);
 525
 526     foreach ($contexts as $ctxid) {
 527         if ($records = get_records('grade_letters', 'contextid', $ctxid, 'lowerboundary DESC')) {
 528             foreach ($records as $record) {
 529                 $letters[$record->lowerboundary] = $record->letter;
 530             }
 531         }
 532
 533         if (!empty($letters)) {
 534             $cache[$context->id] = $letters;
 535             return $letters;
 536         }
 537     }
 538
 539     $letters = grade_get_letters(null);
 540     $cache[$context->id] = $letters;
 541     return $letters;
 542 }
 543
 544
 545 /**
 546  * Verify new value of idnumber - checks for uniqueness of new idnumbers, old are kept intact
 547  * @param string idnumber string (with magic quotes)
 548  * @param object $cm used for course module idnumbers and items attached to modules
 549  * @param object $gradeitem is item idnumber
 550  * @return boolean true means idnumber ok
 551  */
 552 function grade_verify_idnumber($idnumber, $grade_item=null, $cm=null) {
 553     if ($idnumber == '') {
 554         //we allow empty idnumbers
 555         return true;
 556     }
 557
 558     // keep existing even when not unique
 559     if ($cm and $cm->idnumber == $idnumber) {
 560         return true;
 561     } else if ($grade_item and $grade_item->idnumber == $idnumber) {
 562         return true;
 563     }
 564
 565     if (get_records('course_modules', 'idnumber', $idnumber)) {
 566         return false;
 567     }
 568
 569     if (get_records('grade_items', 'idnumber', $idnumber)) {
 570         return false;
 571     }
 572
 573     return true;
 574 }
 575
 576 /**
 577  * Force final grade recalculation in all course items
 578  * @param int $courseid
 579  */
 580 function grade_force_full_regrading($courseid) {
 581     set_field('grade_items', 'needsupdate', 1, 'courseid', $courseid);
 582 }
 583
 584 /**
 585  * Updates all final grades in course.
 586  *
 587  * @param int $courseid
 588  * @param int $userid if specified, try to do a quick regrading of grades of this user only
 589  * @param object $updated_item the item in which
 590  * @return boolean true if ok, array of errors if problems found (item id is used as key)
 591  */
 592 function grade_regrade_final_grades($courseid, $userid=null, $updated_item=null) {
 593
 594     $course_item = grade_item::fetch_course_item($courseid);
 595
 596     if ($userid) {
 597         // one raw grade updated for one user
 598         if (empty($updated_item)) {
 599             error("updated_item_id can not be null!");
 600         }
 601         if ($course_item->needsupdate) {
 602             $updated_item->force_regrading();
 603             return 'Can not do fast regrading after updating of raw grades';
 604         }
 605
 606     } else {
 607         if (!$course_item->needsupdate) {
 608             // nothing to do :-)
 609             return true;
 610         }
 611     }
 612
 613     $grade_items = grade_item::fetch_all(array('courseid'=>$courseid));
 614     $depends_on = array();
 615
 616     // first mark all category and calculated items as needing regrading
 617     // this is slower, but 100% accurate
 618     foreach ($grade_items as $gid=>$gitem) {
 619         if (!empty($updated_item) and $updated_item->id == $gid) {
 620             $grade_items[$gid]->needsupdate = 1;
 621
 622         } else if ($gitem->is_course_item() or $gitem->is_category_item() or $gitem->is_calculated()) {
 623             $grade_items[$gid]->needsupdate = 1;
 624         }
 625
 626         // construct depends_on lookup array
 627         $depends_on[$gid] = $grade_items[$gid]->depends_on();
 628     }
 629
 630     $errors = array();
 631     $finalids = array();
 632     $gids     = array_keys($grade_items);
 633     $failed = 0;
 634
 635     while (count($finalids) < count($gids)) { // work until all grades are final or error found
 636         $count = 0;
 637         foreach ($gids as $gid) {
 638             if (in_array($gid, $finalids)) {
 639                 continue; // already final
 640             }
 641
 642             if (!$grade_items[$gid]->needsupdate) {
 643                 $finalids[] = $gid; // we can make it final - does not need update
 644                 continue;
 645             }
 646
 647             $doupdate = true;
 648             foreach ($depends_on[$gid] as $did) {
 649                 if (!in_array($did, $finalids)) {
 650                     $doupdate = false;
 651                     continue; // this item depends on something that is not yet in finals array
 652                 }
 653             }
 654
 655             //oki - let's update, calculate or aggregate :-)
 656             if ($doupdate) {
 657                 $result = $grade_items[$gid]->regrade_final_grades($userid);
 658
 659                 if ($result === true) {
 660                     $grade_items[$gid]->regrading_finished();
 661                     $grade_items[$gid]->check_locktime(); // do the locktime item locking
 662                     $count++;
 663                     $finalids[] = $gid;
 664
 665                 } else {
 666                     $grade_items[$gid]->force_regrading();
 667                     $errors[$gid] = $result;
 668                 }
 669             }
 670         }
 671
 672         if ($count == 0) {
 673             $failed++;
 674         } else {
 675             $failed = 0;
 676         }
 677
 678         if ($failed > 1) {
 679             foreach($gids as $gid) {
 680                 if (in_array($gid, $finalids)) {
 681                     continue; // this one is ok
 682                 }
 683                 $grade_items[$gid]->force_regrading();
 684                 $errors[$grade_items[$gid]->id] = 'Probably circular reference or broken calculation formula'; // TODO: localize
 685             }
 686             break; // oki, found error
 687         }
 688     }
 689
 690     if (count($errors) == 0) {
 691         if (empty($userid)) {
 692             // do the locktime locking of grades, but only when doing full regrading
 693             grade_grade::check_locktime_all($gids);
 694         }
 695         return true;
 696     } else {
 697         return $errors;
 698     }
 699 }
 700
 701 /**
 702  * For backwards compatibility with old third-party modules, this function can
 703  * be used to import all grades from activities with legacy grading.
 704  * @param int $courseid or null if all courses
 705  */
 706 function grade_grab_legacy_grades($courseid=null) {
 707
 708     global $CFG;
 709
 710     if (!$mods = get_list_of_plugins('mod') ) {
 711         error('No modules installed!');
 712     }
 713
 714     if ($courseid) {
 715         $course_sql = " AND cm.course=$courseid";
 716     } else {
 717         $course_sql = "";
 718     }
 719
 720     foreach ($mods as $mod) {
 721
 722         if ($mod == 'NEWMODULE') {   // Someone has unzipped the template, ignore it
 723             continue;
 724         }
 725
 726         if (!$module = get_record('modules', 'name', $mod)) {
 727             //not installed
 728             continue;
 729         }
 730
 731         if (!$module->visible) {
 732             //disabled module
 733             continue;
 734         }
 735
 736         $fullmod = $CFG->dirroot.'/mod/'.$mod;
 737
 738         // include the module lib once
 739         if (file_exists($fullmod.'/lib.php')) {
 740             include_once($fullmod.'/lib.php');
 741             // look for modname_grades() function - old gradebook pulling function
 742             // if present sync the grades with new grading system
 743             $gradefunc = $mod.'_grades';
 744             if (function_exists($gradefunc)) {
 745
 746                 // get all instance of the activity
 747                 $sql = "SELECT a.*, cm.idnumber as cmidnumber, m.name as modname
 748                           FROM {$CFG->prefix}$mod a, {$CFG->prefix}course_modules cm, {$CFG->prefix}modules m
 749                          WHERE m.name='$mod' AND m.id=cm.module AND cm.instance=a.id $course_sql";
 750
 751                 if ($modinstances = get_records_sql($sql)) {
 752                     foreach ($modinstances as $modinstance) {
 753                         grade_update_mod_grades($modinstance);
 754                     }
 755                 }
 756             }
 757         }
 758     }
 759 }
 760
 761 /**
 762  * For testing purposes mainly, reloads grades from all non legacy modules into gradebook.
 763  */
 764 function grade_grab_grades() {
 765
 766     global $CFG;
 767
 768     if (!$mods = get_list_of_plugins('mod') ) {
 769         error('No modules installed!');
 770     }
 771
 772     foreach ($mods as $mod) {
 773
 774         if ($mod == 'NEWMODULE') {   // Someone has unzipped the template, ignore it
 775             continue;
 776         }
 777
 778         if (!$module = get_record('modules', 'name', $mod)) {
 779             //not installed
 780             continue;
 781         }
 782
 783         if (!$module->visible) {
 784             //disabled module
 785             continue;
 786         }
 787
 788         $fullmod = $CFG->dirroot.'/mod/'.$mod;
 789
 790         // include the module lib once
 791         if (file_exists($fullmod.'/lib.php')) {
 792             include_once($fullmod.'/lib.php');
 793             // look for modname_grades() function - old gradebook pulling function
 794             // if present sync the grades with new grading system
 795             $gradefunc = $mod.'_update_grades';
 796             if (function_exists($gradefunc)) {
 797                 $gradefunc();
 798             }
 799         }
 800     }
 801 }
 802
 803 /**
 804  * Force full update of module grades in central gradebook - works for both legacy and converted activities.
 805  * @param object $modinstance object with extra cmidnumber and modname property
 806  * @return boolean success
 807  */
 808 function grade_update_mod_grades($modinstance, $userid=0) {
 809     global $CFG;
 810
 811     $fullmod = $CFG->dirroot.'/mod/'.$modinstance->modname;
 812     if (!file_exists($fullmod.'/lib.php')) {
 813         debugging('missing lib.php file in module');
 814         return false;
 815     }
 816     include_once($fullmod.'/lib.php');
 817
 818     // does it use legacy grading?
 819     $gradefunc        = $modinstance->modname.'_grades';
 820     $updategradesfunc = $modinstance->modname.'_update_grades';
 821     $updateitemfunc   = $modinstance->modname.'_grade_item_update';
 822
 823     if (function_exists($gradefunc)) {
 824
 825         // legacy module - not yet converted
 826         if ($oldgrades = $gradefunc($modinstance->id)) {
 827
 828             $grademax = $oldgrades->maxgrade;
 829             $scaleid = NULL;
 830             if (!is_numeric($grademax)) {
 831                 // scale name is provided as a string, try to find it
 832                 if (!$scale = get_record('scale', 'name', $grademax)) {
 833                     debugging('Incorrect scale name! name:'.$grademax);
 834                     return false;
 835                 }
 836                 $scaleid = $scale->id;
 837             }
 838
 839             if (!$grade_item = grade_get_legacy_grade_item($modinstance, $grademax, $scaleid)) {
 840                 debugging('Can not get/create legacy grade item!');
 841                 return false;
 842             }
 843
 844             $grades = array();
 845             foreach ($oldgrades->grades as $uid=>$usergrade) {
 846                 if ($userid and $uid != $userid) {
 847                     continue;
 848                 }
 849                 $grade = new object();
 850                 $grade->userid = $uid;
 851
 852                 if ($usergrade == '-') {
 853                     // no grade
 854                     $grade->rawgrade = null;
 855
 856                 } else if ($scaleid) {
 857                     // scale in use, words used
 858                     $gradescale = explode(",", $scale->scale);
 859                     $grade->rawgrade = array_search($usergrade, $gradescale) + 1;
 860
 861                 } else {
 862                     // good old numeric value
 863                     $grade->rawgrade = $usergrade;
 864                 }
 865                 $grades[] = $grade;
 866             }
 867
 868             grade_update('legacygrab', $grade_item->courseid, $grade_item->itemtype, $grade_item->itemmodule,
 869                          $grade_item->iteminstance, $grade_item->itemnumber, $grades);
 870         }
 871
 872     } else if (function_exists($updategradesfunc) and function_exists($updateitemfunc)) {
 873         //new grading supported, force updating of grades
 874         $updateitemfunc($modinstance);
 875         $updategradesfunc($modinstance, $userid);
 876
 877     } else {
 878         // mudule does not support grading??
 879     }
 880
 881     return true;
 882 }
 883
 884 /**
 885  * Get and update/create grade item for legacy modules.
 886  */
 887 function grade_get_legacy_grade_item($modinstance, $grademax, $scaleid) {
 888
 889     // does it already exist?
 890     if ($grade_items = grade_item::fetch_all(array('courseid'=>$modinstance->course, 'itemtype'=>'mod', 'itemmodule'=>$modinstance->modname, 'iteminstance'=>$modinstance->id, 'itemnumber'=>0))) {
 891         if (count($grade_items) > 1) {
 892             debugging('Multiple legacy grade_items found.');
 893             return false;
 894         }
 895
 896         $grade_item = reset($grade_items);
 897
 898         if (is_null($grademax) and is_null($scaleid)) {
 899            $grade_item->gradetype  = GRADE_TYPE_NONE;
 900
 901         } else if ($scaleid) {
 902             $grade_item->gradetype = GRADE_TYPE_SCALE;
 903             $grade_item->scaleid   = $scaleid;
 904             $grade_item->grademin  = 1;
 905
 906         } else {
 907             $grade_item->gradetype  = GRADE_TYPE_VALUE;
 908             $grade_item->grademax   = $grademax;
 909             $grade_item->grademin   = 0;
 910         }
 911
 912         $grade_item->itemname = $modinstance->name;
 913         $grade_item->idnumber = $modinstance->cmidnumber;
 914
 915         $grade_item->update();
 916
 917         return $grade_item;
 918     }
 919
 920     // create new one
 921     $params = array('courseid'    =>$modinstance->course,
 922                     'itemtype'    =>'mod',
 923                     'itemmodule'  =>$modinstance->modname,
 924                     'iteminstance'=>$modinstance->id,
 925                     'itemnumber'  =>0,
 926                     'itemname'    =>$modinstance->name,
 927                     'idnumber'    =>$modinstance->cmidnumber);
 928
 929     if (is_null($grademax) and is_null($scaleid)) {
 930         $params['gradetype'] = GRADE_TYPE_NONE;
 931
 932     } else if ($scaleid) {
 933         $params['gradetype'] = GRADE_TYPE_SCALE;
 934         $params['scaleid']   = $scaleid;
 935         $grade_item->grademin  = 1;
 936     } else {
 937         $params['gradetype'] = GRADE_TYPE_VALUE;
 938         $params['grademax']  = $grademax;
 939         $params['grademin']  = 0;
 940     }
 941
 942     $grade_item = new grade_item($params);
 943     $grade_item->insert();
 944
 945     return $grade_item;
 946 }
 947
 948 /**
 949  * Remove all grade related course data - history is kept
 950  * @param int $courseid
 951  * @param bool @showfeedback print feedback
 952  */
 953 function remove_course_grades($courseid, $showfeedback) {
 954     $strdeleted = get_string('deleted');
 955
 956     $course_category = grade_category::fetch_course_category($courseid);
 957     $course_category->delete('coursedelete');
 958     if ($showfeedback) {
 959         notify($strdeleted.' - '.get_string('grades', 'grades').', '.get_string('items', 'grades').', '.get_string('categories', 'grades'));
 960     }
 961
 962     if ($outcomes = grade_outcome::fetch_all(array('courseid'=>$courseid))) {
 963         foreach ($outcomes as $outcome) {
 964             $outcome->delete('coursedelete');
 965         }
 966     }
 967     delete_records('grade_outcomes_courses', 'courseid', $courseid);
 968     if ($showfeedback) {
 969         notify($strdeleted.' - '.get_string('outcomes', 'grades'));
 970     }
 971
 972     if ($scales = grade_scale::fetch_all(array('courseid'=>$courseid))) {
 973         foreach ($scales as $scale) {
 974             $scale->delete('coursedelete');
 975         }
 976     }
 977     if ($showfeedback) {
 978         notify($strdeleted.' - '.get_string('scales'));
 979     }
 980 }
 981
 982 /**
 983  * Builds an array of percentages indexed by integers for the purpose of building a select drop-down element.
 984  * @param int $steps The value between each level.
 985  * @param string $order 'asc' for 0-100 and 'desc' for 100-0
 986  * @param int $lowest The lowest value to include
 987  * @param int $highest The highest value to include
 988  */
 989 function build_percentages_array($steps=1, $order='desc', $lowest=0, $highest=100) {
 990     // TODO reject or implement
 991 }
 992
 993 /**
 994  * Grading cron job
 995  */
 996 function grade_cron() {
 997     global $CFG;
 998
 999     $now = time();
1000
1001     $sql = "SELECT i.*
1002               FROM {$CFG->prefix}grade_items i
1003              WHERE i.locked = 0 AND i.locktime > 0 AND i.locktime < $now AND EXISTS (
1004                 SELECT 'x' FROM {$CFG->prefix}grade_items c WHERE c.itemtype='course' AND c.needsupdate=0 AND c.courseid=i.courseid)";
1005
1006     // go through all courses that have proper final grades and lock them if needed
1007     if ($rs = get_recordset_sql($sql)) {
1008         if ($rs->RecordCount() > 0) {
1009             while ($item = rs_fetch_next_record($rs)) {
1010                 $grade_item = new grade_item($item, false);
1011                 $grade_item->locked = $now;
1012                 $grade_item->update('locktime');
1013             }
1014         }
1015         rs_close($rs);
1016     }
1017
1018     $grade_inst = new grade_grade();
1019     $fields = 'g.'.implode(',g.', $grade_inst->required_fields);
1020
1021     $sql = "SELECT $fields
1022               FROM {$CFG->prefix}grade_grades g, {$CFG->prefix}grade_items i
1023              WHERE g.locked = 0 AND g.locktime > 0 AND g.locktime < $now AND g.itemid=i.id AND EXISTS (
1024                 SELECT 'x' FROM {$CFG->prefix}grade_items c WHERE c.itemtype='course' AND c.needsupdate=0 AND c.courseid=i.courseid)";
1025
1026     // go through all courses that have proper final grades and lock them if needed
1027     if ($rs = get_recordset_sql($sql)) {
1028         if ($rs->RecordCount() > 0) {
1029             while ($grade = rs_fetch_next_record($rs)) {
1030                 $grade_grade = new grade_grade($grade, false);
1031                 $grade_grade->locked = $now;
1032                 $grade_grade->update('locktime');
1033             }
1034         }
1035         rs_close($rs);
1036     }
1037
1038 }
1039
1040 ?>