eliminate this nasty JavaScript that prints the button.
[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);
27f95e9b 39define('GRADE_CHILDTYPE_ITEM', 0);
40define('GRADE_CHILDTYPE_CAT', 1);
41define('GRADE_ITEM', 0); // Used to compare class names with CHILDTYPE values
42define('GRADE_CATEGORY', 1); // Used to compare class names with CHILDTYPE values
210611f6 43define('GRADE_TYPE_NONE', 0);
44define('GRADE_TYPE_VALUE', 1);
45define('GRADE_TYPE_SCALE', 2);
46define('GRADE_TYPE_TEXT', 3);
42bbccd7 47
3058964f 48require_once($CFG->libdir . '/grade/grade_category.php');
49require_once($CFG->libdir . '/grade/grade_item.php');
50require_once($CFG->libdir . '/grade/grade_calculation.php');
a8995b34 51require_once($CFG->libdir . '/grade/grade_grades_raw.php');
869807d8 52require_once($CFG->libdir . '/grade/grade_grades_final.php');
d5bdb228 53require_once($CFG->libdir . '/grade/grade_scale.php');
5501446d 54require_once($CFG->libdir . '/grade/grade_outcome.php');
46566dd8 55require_once($CFG->libdir . '/grade/grade_history.php');
56require_once($CFG->libdir . '/grade/grade_grades_text.php');
8ff4550a 57require_once($CFG->libdir . '/grade/grade_tree.php');
60cf7430 58
5834dcdb 59/**
42bbccd7 60* Extracts from the gradebook all the grade items attached to the calling object.
5834dcdb 61* For example, an assignment may want to retrieve all the grade_items for itself,
62* and get three outcome scales in return. This will affect the grading interface.
63*
64* Note: Each parameter refines the search. So if you only give the courseid,
65* all the grade_items for this course will be returned. If you add the
66* itemtype 'mod', all grade_items for this courseif AND for the 'mod'
67* type will be returned, etc...
68*
42bbccd7 69* @param int $courseid The id of the course to which the grade items belong
5834dcdb 70* @param string $itemtype 'mod', 'blocks', 'import', 'calculated' etc
71* @param string $itemmodule 'forum, 'quiz', 'csv' etc
72* @param int $iteminstance id of the item module
de420c11 73* @param string $itemname The name of the grade item
5834dcdb 74* @param int $itemnumber Can be used to distinguish multiple grades for an activity
42bbccd7 75* @param int $idnumber grade item Primary Key
76* @return array An array of grade items
5834dcdb 77*/
de420c11 78function grade_get_items($courseid, $itemtype=NULL, $itemmodule=NULL, $iteminstance=NULL, $itemname=NULL, $itemnumber=NULL, $idnumber=NULL) {
79 $grade_item = new grade_item(compact('courseid', 'itemtype', 'itemmodule', 'iteminstance', 'itemname', 'itemnumber', 'idnumber'), false);
3058964f 80 $grade_items = $grade_item->fetch_all_using_this();
42bbccd7 81 return $grade_items;
5834dcdb 82}
83
84
85/**
de420c11 86* Creates a new grade_item in case it doesn't exist.
87* This function is called when a new module is created.
88*
89* @param mixed $params array or object
5834dcdb 90* @return mixed New grade_item id if successful
91*/
3058964f 92function grade_create_item($params) {
42bbccd7 93 $grade_item = new grade_item($params);
d9907766 94
95 if (empty($grade_item->id)) {
96 return $grade_item->insert();
97 } else {
de420c11 98 debugging('Grade item already exists - id:'.$grade_item->id);
d9907766 99 return $grade_item->id;
100 }
5834dcdb 101}
102
103/**
104* For a given set of items, create a category to group them together (if one doesn't yet exist).
105* Modules may want to do this when they are created. However, the ultimate control is in the gradebook interface itself.
619a59a7 106*
107* @param int $courseid
42bbccd7 108* @param string $fullname The name of the new category
109* @param array $items An array of grade_items to group under the new category
5834dcdb 110* @param string $aggregation
111* @return mixed New grade_category id if successful
112*/
3058964f 113function grade_create_category($courseid, $fullname, $items, $aggregation=GRADE_AGGREGATE_MEAN) {
114 $grade_category = new grade_category(compact('courseid', 'fullname', 'items', 'aggregation'));
d9907766 115
116 if (empty($grade_category->id)) {
117 return $grade_category->insert();
118 } else {
119 return $grade_category->id;
120 }
5834dcdb 121}
122
123
124/**
125* Tells a module whether a grade (or grade_item if $userid is not given) is currently locked or not.
126* This is a combination of the actual settings in the grade tables and a check on moodle/course:editgradeswhenlocked.
127* If it's locked to the current use then the module can print a nice message or prevent editing in the module.
3058964f 128* If no $userid is given, the method will always return the grade_item's locked state.
129* If a $userid is given, the method will first check the grade_item's locked state (the column). If it is locked,
130* the method will return true no matter the locked state of the specific grade being checked. If unlocked, it will
131* return the locked state of the specific grade.
132*
5834dcdb 133* @param string $itemtype 'mod', 'blocks', 'import', 'calculated' etc
134* @param string $itemmodule 'forum, 'quiz', 'csv' etc
135* @param int $iteminstance id of the item module
3058964f 136* @param int $itemnumber Optional number of the item to check
5834dcdb 137* @param int $userid ID of the user who owns the grade
138* @return boolean Whether the grade is locked or not
139*/
3058964f 140function grade_is_locked($itemtype, $itemmodule, $iteminstance, $itemnumber=NULL, $userid=NULL) {
141 $grade_item = new grade_item(compact('itemtype', 'itemmodule', 'iteminstance', 'itemnumber'));
142 return $grade_item->is_locked($userid);
5834dcdb 143}
144
a8995b34 145/**
146 * Updates all grade_grades_final for each grade_item matching the given attributes.
147 * The search is further restricted, so that only grade_items that have needs_update == TRUE
148 * or that use calculation are retrieved.
149 *
150 * @param int $courseid
151 * @param int $gradeitemid
152 * @return int Number of grade_items updated
153 */
154function grade_update_final_grades($courseid=NULL, $gradeitemid=NULL) {
155 $grade_item = new grade_item();
156 $grade_item->courseid = $courseid;
157 $grade_item->id = $gradeitemid;
158 $grade_items = $grade_item->fetch_all_using_this();
159
160 $count = 0;
161
162 foreach ($grade_items as $gi) {
163 $calculation = $gi->get_calculation();
164 if (!empty($calculation) || $gi->needsupdate) {
165 if ($gi->update_final_grade()) {
166 $count++;
167 }
168 }
169 }
170
171 return $count;
172}
967f222f 173
de420c11 174/**
967f222f 175 * For backward compatibility with old third-party modules, this function is called
176 * via to admin/cron.php to search all mod/xxx/lib.php files for functions named xxx_grades(),
177 * if the current modules does not have grade events registered with the grade book.
d46306de 178 * Once the data is extracted, the events_trigger() function can be called to initiate
967f222f 179 * an event as usual and copy/ *upgrade the data in the gradebook tables.
180 */
de420c11 181function grade_grab_legacy_grades() {
967f222f 182
183 global $CFG, $db;
184
185 if (!$mods = get_list_of_plugins('mod') ) {
186 error('No modules installed!');
187 }
188
189 foreach ($mods as $mod) {
190
191 if ($mod == 'NEWMODULE') { // Someone has unzipped the template, ignore it
192 continue;
193 }
194
195 $fullmod = $CFG->dirroot .'/mod/'. $mod;
196
197 // include the module lib once
198 if (file_exists($fullmod.'/lib.php')) {
199 include_once($fullmod.'/lib.php');
de420c11 200 // look for modname_grades() function - old gradebook pulling function
201 // if present sync the grades with new grading system
967f222f 202 $gradefunc = $mod.'_grades';
de420c11 203 if (function_exists($gradefunc)) {
204
205 // get all instance of the activity
206 $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
207 WHERE m.name='$mod' AND m.id=cm.module AND cm.instance=a.id";
208
209 if ($modinstances = get_records_sql($sql)) {
967f222f 210 foreach ($modinstances as $modinstance) {
211 // for each instance, call the xxx_grades() function
de420c11 212 if ($grades = $gradefunc($modinstance->id)) {
213
214 $grademax = $grades->maxgrade;
215 $scaleid = 0;
216 if (!is_numeric($grademax)) {
5283e959 217 // scale name is provided as a string, try to find it
de420c11 218 if (!$scale = get_record('scale', 'name', $grademax)) {
219 debugging('Incorrect scale name! name:'.$grademax);
220 continue;
221 }
5283e959 222 $scaleid = $scale->id;
de420c11 223 }
224
225 if (!$grade_item = grade_get_legacy_grade_item($modinstance, $grademax, $scaleid)) {
226 debugging('Can not get/create legacy grade item!');
227 continue;
9d5c91b1 228 }
229
967f222f 230 foreach ($grades->grades as $userid=>$usergrade) {
231 // make the grade_added eventdata
d46306de 232 $eventdata = new object();
de420c11 233 $eventdata->itemid = $grade_item->id;
9492291c 234 $eventdata->userid = $userid;
de420c11 235
236 if ($usergrade == '-') {
237 // no grade
238 $eventdata->gradevalue = null;
239
240 } else if ($scaleid) {
5283e959 241 // scale in use, words used
242 $gradescale = explode(",", $scale->scale);
243 $eventdata->gradevalue = array_search($usergrade, $gradescale) + 1;
de420c11 244
5283e959 245 } else {
246 // good old numeric value
247 $eventdata->gradevalue = $usergrade;
248 }
249
de420c11 250 events_trigger('grade_updated', $eventdata);
967f222f 251 }
252 }
253 }
254 }
255 }
256 }
257 }
258}
259
de420c11 260
261/**
262 * Get (create if needed) grade item for legacy modules.
263 */
264function grade_get_legacy_grade_item($modinstance, $grademax, $scaleid) {
265
266 // does it already exist?
267 if ($grade_items = grade_get_items($modinstances->courseid, 'mod', $modinstance->modname, $modinstances->id)) {
268 if (count($grade_items) > 1) {
269 return false;
270 }
271
272 $grade_item = reset($grade_items);
273 $updated = false;
274
275 if ($scaleid) {
276 if ($grade_item->scaleid != $scaleid) {
277 $grade_item->gradetype = GRADE_TYPE_SCALE;
278 $grade_item->scaleid = $scaleid;
279 $updated = true;;
280 }
281
282 } else if ($grade_item->scaleid != $scaleid or $grade_item->grademax != $grademax) {
283 $grade_item->gradetype = GRADE_TYPE_VALUE;
284 $grade_item->scaleid = 0;
285 $grade_item->grademax = $grademax;
286 $grade_item->grademin = 0;
287 $updated = true;;
288 }
289
290 if ($grade_item->itemname != $modinstance->name) {
291 $grade_item->itemname = $modinstance->name;
292 $updated = true;;
293 }
294
295 if ($grade_item->idnumber != $modinstance->cmidnumber) {
296 $grade_item->idnumber = $modinstance->cmidnumber;
297 $updated = true;;
298 }
299
300 if ($updated) {
301 $grade_item->update();
302 }
303
304 return $grade_item;
305 }
306
307 // create new one
308 $params = array('courseid' =>$modinstance->courseid,
309 'itemtype' =>'mod',
310 'itemmodule' =>$modinstance->modname,
311 'iteminstance'=>$modinstance->id,
312 'itemname' =>$modinstance->name,
313 'idnumber' =>$modinstance->cmidnumber);
314
315 if ($scaleid) {
316 $params['gradetype'] = GRADE_TYPE_SCALE;
317 $params['scaleid'] = $scaleid;
318
319 } else {
320 $params['gradetype'] = GRADE_TYPE_VALUE;
321 $params['grademax'] = $grademax;
322 $params['grademin'] = 0;
323 }
324
325 if (!$itemid = grade_create_item($params)) {
326 return false;
327 }
328
329 return grade_item::fetch('id', $itemid);
330}
331
2c72af1f 332/**
333 * Given a float value situated between a source minimum and a source maximum, converts it to the
334 * corresponding value situated between a target minimum and a target maximum. Thanks to Darlene
335 * for the formula :-)
336 * @param float $gradevalue
337 * @param float $source_min
338 * @param float $source_max
339 * @param float $target_min
340 * @param float $target_max
341 * @return float Converted value
342 */
2df71235 343function standardise_score($gradevalue, $source_min, $source_max, $target_min, $target_max, $debug=false) {
096858ff 344 $factor = ($gradevalue - $source_min) / ($source_max - $source_min);
345 $diff = $target_max - $target_min;
346 $standardised_value = $factor * $diff + $target_min;
2df71235 347 if ($debug) {
348 echo 'standardise_score debug info: (lib/gradelib.php)';
349 print_object(array('gradevalue' => $gradevalue,
350 'source_min' => $source_min,
351 'source_max' => $source_max,
352 'target_min' => $target_min,
096858ff 353 'target_max' => $target_max,
354 'result' => $standardised_value));
2df71235 355 }
096858ff 356 return $standardised_value;
2c72af1f 357}
bfe7297e 358
359
7bddd4b7 360/**
de420c11 361 * Handles all grade_updated and grade_updated_external events,
362 * see lib/db/events.php for description of $eventdata format.
bfe7297e 363 *
bfe7297e 364 * @param object $eventdata contains all the data for the event
365 * @return boolean success
366 *
367 */
368function grade_handler($eventdata) {
7bddd4b7 369 $eventdata = (array)$eventdata;
370
de420c11 371 // each grade must belong to some user
7bddd4b7 372 if (empty($eventdata['userid'])) {
373 debugging('Missing user id in event data!');
374 return true;
375 }
bfe7297e 376
de420c11 377 // grade item must be specified or else it could be accidentally duplicated,
378 if (empty($eventdata['itemid'])) {
379 debugging('Missing grade item id in event!');
380 return true;
bfe7297e 381 }
382
de420c11 383 // get the grade item from db
384 if (!$gradeitem = grade_item::fetch('id', $eventdata['itemid'])) {
385 debugging('Incorrect grade item id in event! id:'.$eventdata['itemid']);
386 return true;
387 }
388
389 // get the raw grade if it exist
7bddd4b7 390 $rawgrade = new grade_grades_raw(array('itemid'=>$gradeitem->id, 'userid'=>$eventdata['userid']));
391 $rawgrade->grade_item = &$gradeitem; // we already have it, so let's use it
bfe7297e 392
7bddd4b7 393 // store these to keep track of original grade item settings
394 $rawgrade->grademax = $gradeitem->grademax;
395 $rawgrade->grademin = $gradeitem->grademin;
396 $rawgrade->scaleid = $gradeitem->scaleid;
bfe7297e 397
7bddd4b7 398 if (isset($eventdata['feedback'])) {
399 $rawgrade->feedback = $eventdata['feedback'];
400 if (isset($eventdata['feedbackformat'])) {
401 $rawgrade->feedbackformat = $eventdata['feedbackformat'];
402 } else {
403 $rawgrade->feedbackformat = FORMAT_PLAIN;
404 }
bfe7297e 405
7bddd4b7 406 }
407 if (!isset($eventdata['gradevalue'])) {
408 $eventdata['gradevalue'] = null; // means no grade yet
409 }
bfe7297e 410 if ($rawgrade->id) {
7bddd4b7 411 $rawgrade->update($eventdata['gradevalue'], 'event');
bfe7297e 412 } else {
7bddd4b7 413 $rawgrade->gradevalue = $eventdata['gradevalue'];
bfe7297e 414 $rawgrade->insert();
415 }
bfe7297e 416
7bddd4b7 417 // everything ok :-)
bfe7297e 418 return true;
419
420}
421
422
60cf7430 423?>