Added two recent installer langs to CVS
[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
42bbccd7 35define('GRADE_AGGREGATE_MEAN', 0);
36define('GRADE_AGGREGATE_MEDIAN', 1);
37define('GRADE_AGGREGATE_SUM', 2);
38define('GRADE_AGGREGATE_MODE', 3);
612607bd 39
27f95e9b 40define('GRADE_CHILDTYPE_ITEM', 0);
41define('GRADE_CHILDTYPE_CAT', 1);
612607bd 42
27f95e9b 43define('GRADE_ITEM', 0); // Used to compare class names with CHILDTYPE values
44define('GRADE_CATEGORY', 1); // Used to compare class names with CHILDTYPE values
612607bd 45
210611f6 46define('GRADE_TYPE_NONE', 0);
47define('GRADE_TYPE_VALUE', 1);
48define('GRADE_TYPE_SCALE', 2);
49define('GRADE_TYPE_TEXT', 3);
42bbccd7 50
612607bd 51define('GRADE_UPDATE_OK', 0);
52define('GRADE_UPDATE_FAILED', 1);
53define('GRADE_UPDATE_MULTIPLE', 2);
54define('GRADE_UPDATE_ITEM_DELETED', 3);
55define('GRADE_UPDATE_INVALID_GRADE', 4);
56define('GRADE_UPDATE_LOCKED', 5);
57
58
3058964f 59require_once($CFG->libdir . '/grade/grade_category.php');
60require_once($CFG->libdir . '/grade/grade_item.php');
61require_once($CFG->libdir . '/grade/grade_calculation.php');
a8995b34 62require_once($CFG->libdir . '/grade/grade_grades_raw.php');
869807d8 63require_once($CFG->libdir . '/grade/grade_grades_final.php');
d5bdb228 64require_once($CFG->libdir . '/grade/grade_scale.php');
5501446d 65require_once($CFG->libdir . '/grade/grade_outcome.php');
46566dd8 66require_once($CFG->libdir . '/grade/grade_history.php');
67require_once($CFG->libdir . '/grade/grade_grades_text.php');
8ff4550a 68require_once($CFG->libdir . '/grade/grade_tree.php');
60cf7430 69
612607bd 70/***** PUBLIC GRADE API *****/
71
c5b5f18d 72/**
73 * Submit new or update grade; update/create grade_item definition. Grade must have userid specified,
74 * gradevalue and feedback with format are optional. gradevalue NULL means 'Not graded', missing property
75 * or key means do not change existing.
76 *
77 * Only following grade item properties can be changed 'itemname', 'idnumber', 'gradetype', 'grademax',
78 * 'grademin', 'scaleid', 'deleted'.
79 *
80 * @param string $source source of the grade such as 'mod/assignment', often used to prevent infinite loops when processing grade_updated events
81 * @param int $courseid id of course
82 * @param string $itemtype type of grade item - mod, block, gradecategory, calculated
83 * @param string $itemmodule more specific then $itemtype - assignment, forum, etc.; maybe NULL for some item types
84 * @param int $iteminstance instance it of graded subject
85 * @param int $itemnumber most probably 0, modules can use other numbers when having more than one grades for each user
86 * @param mixed $grades grade (object, array) or several grades (arrays of arrays or objects), NULL if updating rgade_item definition only\
87 * @param mixed $itemdetails object or array describing the grading item, NULL if no change
88 */
b67ec72f 89function grade_update($source, $courseid, $itemtype, $itemmodule, $iteminstance, $itemnumber, $grades=NULL, $itemdetails=NULL) {
612607bd 90
c5b5f18d 91 // only following grade_item properties can be changed in this function
612607bd 92 $allowed = array('itemname', 'idnumber', 'gradetype', 'grademax', 'grademin', 'scaleid', 'deleted');
93
94 if (is_null($courseid) or is_null($itemtype)) {
95 debugging('Missing courseid or itemtype');
96 return GRADE_UPDATE_FAILED;
97 }
98
99 $grade_item = new grade_item(compact('courseid', 'itemtype', 'itemmodule', 'iteminstance', 'itemnumber'), false);
100 if (!$grade_items = $grade_item->fetch_all_using_this()) {
101 // create a new one
102 $grade_item = false;
103
104 } else if (count($grade_items) == 1){
105 $grade_item = reset($grade_items);
106 unset($grade_items); //release memory
107
108 } else {
109
110 debugging('Found more than one grading item');
111 return GRADE_UPDATE_MULTIPLE;
112 }
113
114/// Create or update the grade_item if needed
115 if (!$grade_item) {
116 $params = compact('courseid', 'itemtype', 'itemmodule', 'iteminstance', 'itemnumber');
117 if ($itemdetails) {
118 $itemdetails = (array)$itemdetails;
119 foreach ($itemdetails as $k=>$v) {
120 if (!in_array($k, $allowed)) {
121 // ignore it
122 continue;
123 }
124 if ($k == 'gradetype' and $v == GRADE_TYPE_NONE) {
125 // no grade item needed!
126 return GRADE_UPDATE_OK;
127 }
128 $params[$k] = $v;
129 }
130 }
131 $itemid = grade_create_item($params);
132 $grade_item = grade_item::fetch('id', $itemid);
133
134 } else {
135 if ($grade_item->locked) {
136 debugging('Grading item is locked!');
137 return GRADE_UPDATE_LOCKED;
138 }
139
140 if ($itemdetails) {
141 $itemdetails = (array)$itemdetails;
142 $update = false;
143 foreach ($itemdetails as $k=>$v) {
144 if (!in_array($k, $allowed)) {
145 // ignore it
146 continue;
147 }
148 if ($grade_item->{$k} != $v) {
149 $grade_item->{$k} = $v;
150 $update = true;
151 }
152 }
153 if ($update) {
154 $grade_item->update();
155 }
156 }
157 }
158
159/// Some extra checks
160 // do we use grading?
161 if ($grade_item->gradetype == GRADE_TYPE_NONE) {
162 return GRADE_UPDATE_OK;
163 }
164
165 // no grade submitted
b67ec72f 166 if (empty($grades)) {
612607bd 167 return GRADE_UPDATE_OK;
168 }
169
170 // no grading in deleted items
171 if ($grade_item->deleted) {
172 debugging('Grade item was already deleted!');
173 return GRADE_UPDATE_ITEM_DELETED;
174 }
175
176/// Finally start processing of grades
b67ec72f 177 if (is_object($grades)) {
178 $grades = array($grades);
612607bd 179 } else {
b67ec72f 180 if (array_key_exists('userid', $grades)) {
181 $grades = array($grades);
612607bd 182 }
183 }
184
612607bd 185 foreach ($grades as $grade) {
186 $grade = (array)$grade;
187 if (empty($grade['userid'])) {
188 debugging('Invalid grade submitted');
189 return GRADE_UPDATE_INVALID_GRADE;
190 }
191
192 // get the raw grade if it exist
193 $rawgrade = new grade_grades_raw(array('itemid'=>$grade_item->id, 'userid'=>$grade['userid']));
194 $rawgrade->grade_item = &$grade_item; // we already have it, so let's use it
195
196 // store these to keep track of original grade item settings
197 $rawgrade->grademax = $grade_item->grademax;
198 $rawgrade->grademin = $grade_item->grademin;
199 $rawgrade->scaleid = $grade_item->scaleid;
200
201 if (isset($grade['feedback'])) {
202 $rawgrade->feedback = $grade['feedback'];
203 if (isset($grade['feedbackformat'])) {
204 $rawgrade->feedbackformat = $grade['feedbackformat'];
205 } else {
206 $rawgrade->feedbackformat = FORMAT_PLAIN;
207 }
208 }
209
210 if (!isset($grade['gradevalue'])) {
211 $grade['gradevalue'] = null; // means no grade yet
212 }
213
214 if ($rawgrade->id) {
215 $rawgrade->update($grade['gradevalue'], 'event');
216 } else {
217 $rawgrade->gradevalue = $grade['gradevalue'];
218 $rawgrade->insert();
219 }
220
b67ec72f 221 // trigger grade_updated event notification
612607bd 222 $eventdata = new object();
b67ec72f 223 $eventdata->source = $source;
224 $eventdata->itemid = $grade_item->id;
225 $eventdata->courseid = $grade_item->courseid;
226 $eventdata->itemtype = $grade_item->itemtype;
227 $eventdata->itemmodule = $grade_item->itemmodule;
228 $eventdata->iteminstance = $grade_item->iteminstance;
c5b5f18d 229 $eventdata->itemnumber = $grade_item->itemnumber;
b67ec72f 230 $eventdata->idnumber = $grade_item->idnumber;
231 $eventdata->grade = $grade;
612607bd 232 events_trigger('grade_updated', $eventdata);
233 }
234
235 return GRADE_UPDATE_OK;
236}
237
b67ec72f 238
239/**
240* Tells a module whether a grade (or grade_item if $userid is not given) is currently locked or not.
241* This is a combination of the actual settings in the grade tables and a check on moodle/course:editgradeswhenlocked.
242* If it's locked to the current use then the module can print a nice message or prevent editing in the module.
243* If no $userid is given, the method will always return the grade_item's locked state.
244* If a $userid is given, the method will first check the grade_item's locked state (the column). If it is locked,
245* the method will return true no matter the locked state of the specific grade being checked. If unlocked, it will
246* return the locked state of the specific grade.
247*
248* @param string $itemtype 'mod', 'blocks', 'import', 'calculated' etc
249* @param string $itemmodule 'forum, 'quiz', 'csv' etc
250* @param int $iteminstance id of the item module
251* @param int $itemnumber Optional number of the item to check
252* @param int $userid ID of the user who owns the grade
253* @return boolean Whether the grade is locked or not
254*/
255function grade_is_locked($itemtype, $itemmodule, $iteminstance, $itemnumber=NULL, $userid=NULL) {
256 $grade_item = new grade_item(compact('itemtype', 'itemmodule', 'iteminstance', 'itemnumber'));
257 return $grade_item->is_locked($userid);
258}
259
260
612607bd 261/***** END OF PUBLIC API *****/
262
5834dcdb 263/**
612607bd 264* Extracts from the gradebook all the grade items attached to the calling object.
265* For example, an assignment may want to retrieve all the grade_items for itself,
5834dcdb 266* and get three outcome scales in return. This will affect the grading interface.
267*
268* Note: Each parameter refines the search. So if you only give the courseid,
269* all the grade_items for this course will be returned. If you add the
270* itemtype 'mod', all grade_items for this courseif AND for the 'mod'
271* type will be returned, etc...
612607bd 272*
42bbccd7 273* @param int $courseid The id of the course to which the grade items belong
5834dcdb 274* @param string $itemtype 'mod', 'blocks', 'import', 'calculated' etc
275* @param string $itemmodule 'forum, 'quiz', 'csv' etc
276* @param int $iteminstance id of the item module
de420c11 277* @param string $itemname The name of the grade item
5834dcdb 278* @param int $itemnumber Can be used to distinguish multiple grades for an activity
42bbccd7 279* @param int $idnumber grade item Primary Key
280* @return array An array of grade items
5834dcdb 281*/
de420c11 282function grade_get_items($courseid, $itemtype=NULL, $itemmodule=NULL, $iteminstance=NULL, $itemname=NULL, $itemnumber=NULL, $idnumber=NULL) {
283 $grade_item = new grade_item(compact('courseid', 'itemtype', 'itemmodule', 'iteminstance', 'itemname', 'itemnumber', 'idnumber'), false);
3058964f 284 $grade_items = $grade_item->fetch_all_using_this();
42bbccd7 285 return $grade_items;
5834dcdb 286}
287
288
289/**
de420c11 290* Creates a new grade_item in case it doesn't exist.
291* This function is called when a new module is created.
292*
293* @param mixed $params array or object
5834dcdb 294* @return mixed New grade_item id if successful
295*/
3058964f 296function grade_create_item($params) {
42bbccd7 297 $grade_item = new grade_item($params);
612607bd 298
d9907766 299 if (empty($grade_item->id)) {
300 return $grade_item->insert();
301 } else {
de420c11 302 debugging('Grade item already exists - id:'.$grade_item->id);
d9907766 303 return $grade_item->id;
304 }
5834dcdb 305}
306
307/**
308* For a given set of items, create a category to group them together (if one doesn't yet exist).
309* Modules may want to do this when they are created. However, the ultimate control is in the gradebook interface itself.
619a59a7 310*
311* @param int $courseid
42bbccd7 312* @param string $fullname The name of the new category
313* @param array $items An array of grade_items to group under the new category
5834dcdb 314* @param string $aggregation
315* @return mixed New grade_category id if successful
316*/
3058964f 317function grade_create_category($courseid, $fullname, $items, $aggregation=GRADE_AGGREGATE_MEAN) {
318 $grade_category = new grade_category(compact('courseid', 'fullname', 'items', 'aggregation'));
612607bd 319
d9907766 320 if (empty($grade_category->id)) {
321 return $grade_category->insert();
322 } else {
323 return $grade_category->id;
324 }
5834dcdb 325}
326
a8995b34 327/**
328 * Updates all grade_grades_final for each grade_item matching the given attributes.
329 * The search is further restricted, so that only grade_items that have needs_update == TRUE
330 * or that use calculation are retrieved.
331 *
332 * @param int $courseid
333 * @param int $gradeitemid
334 * @return int Number of grade_items updated
335 */
336function grade_update_final_grades($courseid=NULL, $gradeitemid=NULL) {
337 $grade_item = new grade_item();
338 $grade_item->courseid = $courseid;
339 $grade_item->id = $gradeitemid;
340 $grade_items = $grade_item->fetch_all_using_this();
612607bd 341
a8995b34 342 $count = 0;
343
344 foreach ($grade_items as $gi) {
345 $calculation = $gi->get_calculation();
346 if (!empty($calculation) || $gi->needsupdate) {
347 if ($gi->update_final_grade()) {
348 $count++;
349 }
350 }
351 }
352
353 return $count;
354}
967f222f 355
de420c11 356/**
967f222f 357 * For backward compatibility with old third-party modules, this function is called
358 * via to admin/cron.php to search all mod/xxx/lib.php files for functions named xxx_grades(),
359 * if the current modules does not have grade events registered with the grade book.
612607bd 360 * Once the data is extracted, the events_trigger() function can be called to initiate
361 * an event as usual and copy/ *upgrade the data in the gradebook tables.
967f222f 362 */
de420c11 363function grade_grab_legacy_grades() {
612607bd 364
967f222f 365 global $CFG, $db;
366
367 if (!$mods = get_list_of_plugins('mod') ) {
368 error('No modules installed!');
369 }
370
371 foreach ($mods as $mod) {
372
373 if ($mod == 'NEWMODULE') { // Someone has unzipped the template, ignore it
374 continue;
375 }
376
377 $fullmod = $CFG->dirroot .'/mod/'. $mod;
378
379 // include the module lib once
380 if (file_exists($fullmod.'/lib.php')) {
381 include_once($fullmod.'/lib.php');
de420c11 382 // look for modname_grades() function - old gradebook pulling function
383 // if present sync the grades with new grading system
967f222f 384 $gradefunc = $mod.'_grades';
de420c11 385 if (function_exists($gradefunc)) {
386
387 // get all instance of the activity
388 $sql = "SELECT a.*, cm.idnumber as cmidnumber, a.course as courseid, m.name as modname FROM {$CFG->prefix}$mod a, {$CFG->prefix}course_modules cm, {$CFG->prefix}modules m
389 WHERE m.name='$mod' AND m.id=cm.module AND cm.instance=a.id";
390
391 if ($modinstances = get_records_sql($sql)) {
967f222f 392 foreach ($modinstances as $modinstance) {
393 // for each instance, call the xxx_grades() function
de420c11 394 if ($grades = $gradefunc($modinstance->id)) {
395
396 $grademax = $grades->maxgrade;
397 $scaleid = 0;
612607bd 398 if (!is_numeric($grademax)) {
5283e959 399 // scale name is provided as a string, try to find it
de420c11 400 if (!$scale = get_record('scale', 'name', $grademax)) {
401 debugging('Incorrect scale name! name:'.$grademax);
402 continue;
403 }
5283e959 404 $scaleid = $scale->id;
de420c11 405 }
406
407 if (!$grade_item = grade_get_legacy_grade_item($modinstance, $grademax, $scaleid)) {
408 debugging('Can not get/create legacy grade item!');
409 continue;
9d5c91b1 410 }
411
612607bd 412 foreach ($grades->grades as $userid=>$usergrade) {
967f222f 413 // make the grade_added eventdata
d46306de 414 $eventdata = new object();
de420c11 415 $eventdata->itemid = $grade_item->id;
9492291c 416 $eventdata->userid = $userid;
de420c11 417
418 if ($usergrade == '-') {
419 // no grade
420 $eventdata->gradevalue = null;
421
422 } else if ($scaleid) {
5283e959 423 // scale in use, words used
424 $gradescale = explode(",", $scale->scale);
425 $eventdata->gradevalue = array_search($usergrade, $gradescale) + 1;
de420c11 426
5283e959 427 } else {
428 // good old numeric value
429 $eventdata->gradevalue = $usergrade;
430 }
431
de420c11 432 events_trigger('grade_updated', $eventdata);
967f222f 433 }
434 }
435 }
436 }
437 }
438 }
439 }
440}
441
de420c11 442
443/**
444 * Get (create if needed) grade item for legacy modules.
445 */
446function grade_get_legacy_grade_item($modinstance, $grademax, $scaleid) {
447
448 // does it already exist?
449 if ($grade_items = grade_get_items($modinstances->courseid, 'mod', $modinstance->modname, $modinstances->id)) {
450 if (count($grade_items) > 1) {
451 return false;
452 }
453
454 $grade_item = reset($grade_items);
455 $updated = false;
456
457 if ($scaleid) {
458 if ($grade_item->scaleid != $scaleid) {
459 $grade_item->gradetype = GRADE_TYPE_SCALE;
460 $grade_item->scaleid = $scaleid;
461 $updated = true;;
462 }
463
464 } else if ($grade_item->scaleid != $scaleid or $grade_item->grademax != $grademax) {
465 $grade_item->gradetype = GRADE_TYPE_VALUE;
466 $grade_item->scaleid = 0;
467 $grade_item->grademax = $grademax;
468 $grade_item->grademin = 0;
469 $updated = true;;
470 }
471
472 if ($grade_item->itemname != $modinstance->name) {
473 $grade_item->itemname = $modinstance->name;
474 $updated = true;;
475 }
476
477 if ($grade_item->idnumber != $modinstance->cmidnumber) {
478 $grade_item->idnumber = $modinstance->cmidnumber;
479 $updated = true;;
480 }
481
482 if ($updated) {
483 $grade_item->update();
484 }
485
486 return $grade_item;
487 }
612607bd 488
de420c11 489 // create new one
490 $params = array('courseid' =>$modinstance->courseid,
491 'itemtype' =>'mod',
492 'itemmodule' =>$modinstance->modname,
493 'iteminstance'=>$modinstance->id,
494 'itemname' =>$modinstance->name,
495 'idnumber' =>$modinstance->cmidnumber);
496
497 if ($scaleid) {
612607bd 498 $params['gradetype'] = GRADE_TYPE_SCALE;
de420c11 499 $params['scaleid'] = $scaleid;
500
501 } else {
612607bd 502 $params['gradetype'] = GRADE_TYPE_VALUE;
de420c11 503 $params['grademax'] = $grademax;
504 $params['grademin'] = 0;
505 }
506
507 if (!$itemid = grade_create_item($params)) {
508 return false;
509 }
510
511 return grade_item::fetch('id', $itemid);
512}
513
2c72af1f 514/**
515 * Given a float value situated between a source minimum and a source maximum, converts it to the
516 * corresponding value situated between a target minimum and a target maximum. Thanks to Darlene
517 * for the formula :-)
518 * @param float $gradevalue
519 * @param float $source_min
520 * @param float $source_max
521 * @param float $target_min
522 * @param float $target_max
523 * @return float Converted value
524 */
2df71235 525function standardise_score($gradevalue, $source_min, $source_max, $target_min, $target_max, $debug=false) {
096858ff 526 $factor = ($gradevalue - $source_min) / ($source_max - $source_min);
527 $diff = $target_max - $target_min;
528 $standardised_value = $factor * $diff + $target_min;
2df71235 529 if ($debug) {
530 echo 'standardise_score debug info: (lib/gradelib.php)';
531 print_object(array('gradevalue' => $gradevalue,
532 'source_min' => $source_min,
533 'source_max' => $source_max,
534 'target_min' => $target_min,
096858ff 535 'target_max' => $target_max,
536 'result' => $standardised_value));
2df71235 537 }
612607bd 538 return $standardised_value;
2c72af1f 539}
bfe7297e 540
541
60cf7430 542?>