Changed Ojective Rollup Process
[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
42bbccd7 43
3058964f 44require_once($CFG->libdir . '/grade/grade_category.php');
45require_once($CFG->libdir . '/grade/grade_item.php');
46require_once($CFG->libdir . '/grade/grade_calculation.php');
a8995b34 47require_once($CFG->libdir . '/grade/grade_grades_raw.php');
869807d8 48require_once($CFG->libdir . '/grade/grade_grades_final.php');
d5bdb228 49require_once($CFG->libdir . '/grade/grade_scale.php');
5501446d 50require_once($CFG->libdir . '/grade/grade_outcome.php');
46566dd8 51require_once($CFG->libdir . '/grade/grade_history.php');
52require_once($CFG->libdir . '/grade/grade_grades_text.php');
60cf7430 53
5834dcdb 54/**
42bbccd7 55* Extracts from the gradebook all the grade items attached to the calling object.
5834dcdb 56* For example, an assignment may want to retrieve all the grade_items for itself,
57* and get three outcome scales in return. This will affect the grading interface.
58*
59* Note: Each parameter refines the search. So if you only give the courseid,
60* all the grade_items for this course will be returned. If you add the
61* itemtype 'mod', all grade_items for this courseif AND for the 'mod'
62* type will be returned, etc...
63*
42bbccd7 64* @param int $courseid The id of the course to which the grade items belong
5834dcdb 65* @param string $itemname The name of the grade item
66* @param string $itemtype 'mod', 'blocks', 'import', 'calculated' etc
67* @param string $itemmodule 'forum, 'quiz', 'csv' etc
68* @param int $iteminstance id of the item module
69* @param int $itemnumber Can be used to distinguish multiple grades for an activity
42bbccd7 70* @param int $idnumber grade item Primary Key
71* @return array An array of grade items
5834dcdb 72*/
3058964f 73function grade_get_items($courseid, $itemname=NULL, $itemtype=NULL, $itemmodule=NULL, $iteminstance=NULL, $itemnumber=NULL, $idnumber=NULL) {
74 $grade_item = new grade_item(compact('courseid', 'itemname', 'itemtype', 'itemmodule', 'iteminstance', 'itemnumber', 'idnumber'), false);
75 $grade_items = $grade_item->fetch_all_using_this();
42bbccd7 76 return $grade_items;
5834dcdb 77}
78
79
80/**
81* Creates a new grade_item in case it doesn't exist. This function would be called when a module
82* is created or updates, for example, to ensure grade_item entries exist.
83* It's not essential though--if grades are being added later and a matching grade_item doesn't
84* yet exist, the gradebook will create them on the fly.
85*
86* @param
87* @return mixed New grade_item id if successful
88*/
3058964f 89function grade_create_item($params) {
42bbccd7 90 $grade_item = new grade_item($params);
91 return $grade_item->insert();
5834dcdb 92}
93
94/**
95* For a given set of items, create a category to group them together (if one doesn't yet exist).
96* Modules may want to do this when they are created. However, the ultimate control is in the gradebook interface itself.
619a59a7 97*
98* @param int $courseid
42bbccd7 99* @param string $fullname The name of the new category
100* @param array $items An array of grade_items to group under the new category
5834dcdb 101* @param string $aggregation
102* @return mixed New grade_category id if successful
103*/
3058964f 104function grade_create_category($courseid, $fullname, $items, $aggregation=GRADE_AGGREGATE_MEAN) {
105 $grade_category = new grade_category(compact('courseid', 'fullname', 'items', 'aggregation'));
42bbccd7 106 return $grade_category->insert();
5834dcdb 107}
108
109
110/**
111* Tells a module whether a grade (or grade_item if $userid is not given) is currently locked or not.
112* This is a combination of the actual settings in the grade tables and a check on moodle/course:editgradeswhenlocked.
113* If it's locked to the current use then the module can print a nice message or prevent editing in the module.
3058964f 114* If no $userid is given, the method will always return the grade_item's locked state.
115* If a $userid is given, the method will first check the grade_item's locked state (the column). If it is locked,
116* the method will return true no matter the locked state of the specific grade being checked. If unlocked, it will
117* return the locked state of the specific grade.
118*
5834dcdb 119* @param string $itemtype 'mod', 'blocks', 'import', 'calculated' etc
120* @param string $itemmodule 'forum, 'quiz', 'csv' etc
121* @param int $iteminstance id of the item module
3058964f 122* @param int $itemnumber Optional number of the item to check
5834dcdb 123* @param int $userid ID of the user who owns the grade
124* @return boolean Whether the grade is locked or not
125*/
3058964f 126function grade_is_locked($itemtype, $itemmodule, $iteminstance, $itemnumber=NULL, $userid=NULL) {
127 $grade_item = new grade_item(compact('itemtype', 'itemmodule', 'iteminstance', 'itemnumber'));
128 return $grade_item->is_locked($userid);
5834dcdb 129}
130
a8995b34 131/**
132 * Updates all grade_grades_final for each grade_item matching the given attributes.
133 * The search is further restricted, so that only grade_items that have needs_update == TRUE
134 * or that use calculation are retrieved.
135 *
136 * @param int $courseid
137 * @param int $gradeitemid
138 * @return int Number of grade_items updated
139 */
140function grade_update_final_grades($courseid=NULL, $gradeitemid=NULL) {
141 $grade_item = new grade_item();
142 $grade_item->courseid = $courseid;
143 $grade_item->id = $gradeitemid;
144 $grade_items = $grade_item->fetch_all_using_this();
145
146 $count = 0;
147
148 foreach ($grade_items as $gi) {
149 $calculation = $gi->get_calculation();
150 if (!empty($calculation) || $gi->needsupdate) {
151 if ($gi->update_final_grade()) {
152 $count++;
153 }
154 }
155 }
156
157 return $count;
158}
967f222f 159
160/*
161 * For backward compatibility with old third-party modules, this function is called
162 * via to admin/cron.php to search all mod/xxx/lib.php files for functions named xxx_grades(),
163 * if the current modules does not have grade events registered with the grade book.
164 * Once the data is extracted, the event_trigger() function can be called to initiate
165 * an event as usual and copy/ *upgrade the data in the gradebook tables.
166 */
167function grades_grab_grades() {
168
169 global $CFG, $db;
170
171 if (!$mods = get_list_of_plugins('mod') ) {
172 error('No modules installed!');
173 }
174
175 foreach ($mods as $mod) {
176
177 if ($mod == 'NEWMODULE') { // Someone has unzipped the template, ignore it
178 continue;
179 }
180
181 $fullmod = $CFG->dirroot .'/mod/'. $mod;
182
183 // include the module lib once
184 if (file_exists($fullmod.'/lib.php')) {
185 include_once($fullmod.'/lib.php');
186 // look for mod_grades() function - old grade book pulling function
187 // to see if module supports grades, and check for event registration status
188 $gradefunc = $mod.'_grades';
189 // if this mod has grades, but grade_added event is not registered
190 // then we need to pull grades into the new gradebook
191 if (function_exists($gradefunc) && !event_is_registered($mod, $gradefunc)) {
192 // get all instance of the mod
193 $module = get_record('modules', 'name', $mod);
194 if ($module && $modinstances = get_records('course_modules', 'module', $module->id)) {
195 foreach ($modinstances as $modinstance) {
196 // for each instance, call the xxx_grades() function
197 if ($grades = $gradefunc($modinstance->instance)) {
198 foreach ($grades->grades as $userid=>$usergrade) {
199 // make the grade_added eventdata
200 // missing grade event trigger
201 // trigger_event('grade_added', $eventdata);
202 }
203 }
204 }
205 }
206 }
207 }
208 }
209}
210
60cf7430 211?>