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