grades tables
[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/**
27 * Library of functions for Gradebook
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
35/**
36* Extracts from the Gradebook all the Grade Items attached to the calling object.
37* For example, an assignment may want to retrieve all the grade_items for itself,
38* and get three outcome scales in return. This will affect the grading interface.
39*
40* Note: Each parameter refines the search. So if you only give the courseid,
41* all the grade_items for this course will be returned. If you add the
42* itemtype 'mod', all grade_items for this courseif AND for the 'mod'
43* type will be returned, etc...
44*
45* @param int $courseid The id of the course to which the Grade Items belong
46* @param string $itemname The name of the grade item
47* @param string $itemtype 'mod', 'blocks', 'import', 'calculated' etc
48* @param string $itemmodule 'forum, 'quiz', 'csv' etc
49* @param int $iteminstance id of the item module
50* @param int $itemnumber Can be used to distinguish multiple grades for an activity
51* @param int $idnumber Grade Item Primary Key
52* @return array An array of Grade Items
53*/
54function grade_get_items($courseid, $itemname=NULL, $itemtype=NULL, $itemmodule=NULL, $iteminstance=NULL, $itemnumber=NULL, $idnumber=NULL)
55{
56
57}
58
59
60/**
61* Creates a new grade_item in case it doesn't exist. This function would be called when a module
62* is created or updates, for example, to ensure grade_item entries exist.
63* It's not essential though--if grades are being added later and a matching grade_item doesn't
64* yet exist, the gradebook will create them on the fly.
65*
66* @param
67* @return mixed New grade_item id if successful
68*/
69function grade_create_item($params)
70{
71 $grade_item = new Grade_Item($params);
72 return $grade_item->record();
73}
74
75/**
76* For a given set of items, create a category to group them together (if one doesn't yet exist).
77* Modules may want to do this when they are created. However, the ultimate control is in the gradebook interface itself.
78*
79* @param string $fullname The name of the new Category
80* @param array $items An array of grade_items to group under the new Category
81* @param string $aggregation
82* @return mixed New grade_category id if successful
83*/
84function grade_create_category()
85{
86
87}
88
89
90/**
91* Tells a module whether a grade (or grade_item if $userid is not given) is currently locked or not.
92* This is a combination of the actual settings in the grade tables and a check on moodle/course:editgradeswhenlocked.
93* If it's locked to the current use then the module can print a nice message or prevent editing in the module.
94*
95* @param string $itemtype 'mod', 'blocks', 'import', 'calculated' etc
96* @param string $itemmodule 'forum, 'quiz', 'csv' etc
97* @param int $iteminstance id of the item module
98* @param int $userid ID of the user who owns the grade
99* @return boolean Whether the grade is locked or not
100*/
101function grade_is_locked($itemtype, $itemmodule, $iteminstance, $userid=NULL)
102{
103
104}
105
106/**
107 * Class representing a Grade Item. It is responsible for handling its DB representation,
108 * modifying and returning its metadata.
109 */
110class Grade_Item
111{
112 /**
113 * The table name
114 * @var string $tablename
115 */
116 var $tablename = 'grade_items';
117
118 /**
119 * The Grade_Item PK.
120 * @var int $id The Grade_Item PK
121 */
122 var $id;
123
124 /**
125 * The course this Grade_Item belongs to.
126 * @var int $courseid
127 */
128 var $courseid;
129
130 /**
131 * The Category this Grade_Item belongs to (optional).
132 * @var int $categoryid
133 */
134 var $categoryid;
135
136 /**
137 * The name of this Grade_Item (pushed by the module).
138 * @var string $itemname
139 */
140 var $itemname;
141
142 /**
143 * e.g. 'mod', 'blocks', 'import', 'calculate' etc...
144 * @var string $itemtype
145 */
146 var $itemtype;
147
148 /**
149 * The module pushing this grade (e.g. 'forum', 'quiz', 'assignment' etc).
150 * @var string $itemmodule
151 */
152 var $itemmodule;
153
154 /**
155 * ID of the item module
156 * @var int $iteminstance
157 */
158 var $iteminstance;
159
160 /**
161 * Number of the item in a series of multiple grades pushed by an activity.
162 * @var int $itemnumber
163 */
164 var $itemnumber;
165
166 /**
167 * The type of grade (0 = value, 1 = scale, 2 = text)
168 * @var int $gradetype
169 */
170 var $gradetype;
171
172 /**
173 * Maximum allowable grade.
174 * @var float $grademax
175 */
176 var $grademax;
177
178 /**
179 * Minimum allowable grade.
180 * @var float $grademin
181 */
182 var $grademin;
183
184 /**
185 * The scale this grade is based on, if applicable.
186 * @var object $scale
187 */
188 var $scale;
189
190 /**
191 * The Outcome this grade is associated with, if applicable.
192 * @var object $outcome
193 */
194 var $outcome;
195
196 /**
197 * Grade required to pass. (grademin < gradepass <= grademax)
198 * @var float $gradepass
199 */
200 var $gradepass;
201
202 /**
203 * Multiply all grades by this number.
204 * @var float $multfactor
205 */
206 var $multfactor;
207
208 /**
209 * Add this to all grades.
210 * @var float $plusfactor
211 */
212 var $plusfactor;
213
214 /**
215 * Sorting order of the columns.
216 * @var int $sortorder
217 */
218 var $sortorder;
219
220 /**
221 * Date until which to hide this Grade_Item. If null, 0 or false, Grade_Item is not hidden. Hiding prevents viewing.
222 * @var int $hidden
223 */
224 var $hidden;
225
226 /**
227 * Date until which to lock this Grade_Item. If null, 0 or false, Grade_Item is not locked. Locking prevents updating.
228 * @var int $locked
229 */
230 var $locked;
231
232 /**
233 * If set, the whole column will be recalculated, then this flag will be switched off.
234 * @var boolean $needsupdate
235 */
236 var $needsupdate;
237
238 /**
239 * The first time this Grade_Item was created
240 * @var int $timecreated
241 */
242 var $timecreated;
243
244 /**
245 * The last time this Grade_Item was modified
246 * @var int $timemodified
247 */
248 var $timemodified;
249
250 /**
251 * Constructor
252 */
253 function Grade_Item()
254 {
255 global $CFG;
256 $this->tablename = $CFG->prefix . $this->tablename;
257 }
258
259 /**
260 * Inserts the Grade Item object as a new record in the grade_items table.
261 */
262 function record()
263 {
264
265 }
266
267 function get_raw()
268 {
269 $grade_raw = get_record('grade_grades_raw', 'itemid', $this->id);
270 return $grade_raw;
271 }
272
273 /**
274 * Returns the raw value for this grade item (as imported by module or other source).
275 *
276 * @return mixed Grades_Raw object if found, or false.
277 */
278 function get_final()
279 {
280
281 }
282
283 /**
284 * Returns this object's calculation.
285 * @return mixed $calculation A string if found, false otherwise.
286 */
287 function get_calculation()
288 {
289 $grade_calculation = get_record('grade_calculations', 'itemid', $this->id);
290 if ($grade_calculation) {
291 return $grade_calculation->calculation;
292 } else {
293 return $grade_calculation;
294 }
295 }
296
297 /**
298 * Returns the Grade_Category object this Grade_Item belongs to (if any).
299 *
300 * @return mixed Grade_Category object if applicable, NULL otherwise
301 */
302 function get_category()
303 {
304 if (!empty($this->categoryid)) {
305 $grade_category = new Grade_Category($this->category_id);
306 return $grade_category;
307 } else {
308 return null;
309 }
310 }
311}
312
313class Grade_Category
314{
315 /**
316 * The table name
317 * @var string $tablename
318 */
319 var $tablename = 'grade_categories';
320 /**
321 * The Grade_Category PK.
322 * @var int $id The Grade_Category PK
323 */
324 var $id;
325 /**
326 * The course this Category belongs to.
327 * @var int $courseid
328 */
329 var $courseid;
330 /**
331 * The Category this Category belongs to (optional).
332 * @var int $categoryid
333 */
334 var $categoryid;
335 /**
336 * The name of this Category.
337 * @var string $fullname
338 */
339 var $fullname;
340 /**
341 * A constant pointing to one of the predefined aggregation strategies (none, mean, median, sum etc) .
342 * @var int $aggregation
343 */
344 var $aggregation;
345 /**
346 * Keep only the X highest items.
347 * @var int $keephigh
348 */
349 var $keephigh;
350 /**
351 * Drop the X lowest items.
352 * @var int $droplow
353 */
354 var $droplow;
355 /**
356 * Multiply total grade by this number.
357 * @var float $multfactor
358 */
359 var $multfactor;
360 /**
361 * Add this to total grade.
362 * @var float $plusfactor
363 */
364 var $plusfactor;
365 /**
366 * What final grade needs to be achieved to pass this item?
367 * @var float $gradepass
368 */
369 var $gradepass;
370 /**
371 * Date until which to hide this Category. If null, 0 or false, Category is not hidden.
372 * @var int $hidden
373 */
374 var $hidden;
375
376
377 /**
378 * Constructor
379 * @param object $params an object with named parameters for this category.
380 */
381 function Grade_Category($params=NULL)
382 {
383 if (!empty($params) && (is_array($params) || is_object($params))) {
384 foreach ($params as $param => $value) {
385 if (method_exists($this, $param)) {
386 $this->$param = $value;
387 }
388 }
389 }
390 }
391
392 /**
393 * Finds and returns a Grade_Category object based on its ID number.
394 *
395 * @param int $id
396 * @param boolean $static Unless set to true, this method will also set $this object with the returned values.
397 * @return object Grade_Category object or false if none found.
398 */
399 function get_by_id($id, $static=false)
400 {
401 if ($static) {
402 return Grade_Category::get_record(true, 'id', $id);
403 } else {
404 return $this->get_record(false, 'id', $id);
405 }
406 }
407
408
409 /**
410 * Finds and returns a Grade_Category object based on 1-3 field values.
411 *
412 * @param boolean $static Unless set to true, this method will also set $this object with the returned values.
413 * @param string $field1
414 * @param string $value1
415 * @param string $field2
416 * @param string $value2
417 * @param string $field3
418 * @param string $value3
419 * @param string $fields
420 * @return object Grade_Category object or false if none found.
421 */
422 function get_record($static=false, $field1, $value1, $field2='', $value2='', $field3='', $value3='', $fields="*")
423 {
424 if ($grade_category = get_record('grade_categories', $field1, $value1, $field2, $value2, $field3, $value3, $fields)) {
425 if ($static) {
426 return $grade_category;
427 } else {
428 foreach ($grade_category as $param => $value) {
429 $this->$param = $value;
430 }
431 return $this;
432 }
433 } else {
434 return false;
435 }
436 }
437
438}