changing 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/**
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);
39
60cf7430 40require_once($CFG->libdir . '/gradebook/grade_category.php');
41require_once($CFG->libdir . '/gradebook/grade_item.php');
42require_once($CFG->libdir . '/gradebook/grade_calculation.php');
43
5834dcdb 44/**
42bbccd7 45* Extracts from the gradebook all the grade items attached to the calling object.
5834dcdb 46* For example, an assignment may want to retrieve all the grade_items for itself,
47* and get three outcome scales in return. This will affect the grading interface.
48*
49* Note: Each parameter refines the search. So if you only give the courseid,
50* all the grade_items for this course will be returned. If you add the
51* itemtype 'mod', all grade_items for this courseif AND for the 'mod'
52* type will be returned, etc...
53*
42bbccd7 54* @param int $courseid The id of the course to which the grade items belong
5834dcdb 55* @param string $itemname The name of the grade item
56* @param string $itemtype 'mod', 'blocks', 'import', 'calculated' etc
57* @param string $itemmodule 'forum, 'quiz', 'csv' etc
58* @param int $iteminstance id of the item module
59* @param int $itemnumber Can be used to distinguish multiple grades for an activity
42bbccd7 60* @param int $idnumber grade item Primary Key
61* @return array An array of grade items
5834dcdb 62*/
63function grade_get_items($courseid, $itemname=NULL, $itemtype=NULL, $itemmodule=NULL, $iteminstance=NULL, $itemnumber=NULL, $idnumber=NULL)
64{
42bbccd7 65 $grade_item = new grade_item();
66 $grade_item->courseid = $courseid;
67 $grade_item->itemname = $itemname;
68 $grade_item->itemtype = $itemtype;
69 $grade_item->itemmodule = $itemmodule;
70 $grade_item->iteminstance = $iteminstance;
71 $grade_item->itemnumber = $itemnumber;
72 $grade_item->id = $idnumber;
5834dcdb 73
42bbccd7 74 $grade_items = $grade_item->get_records_select();
75 return $grade_items;
5834dcdb 76}
77
78
79/**
80* Creates a new grade_item in case it doesn't exist. This function would be called when a module
81* is created or updates, for example, to ensure grade_item entries exist.
82* It's not essential though--if grades are being added later and a matching grade_item doesn't
83* yet exist, the gradebook will create them on the fly.
84*
85* @param
86* @return mixed New grade_item id if successful
87*/
88function grade_create_item($params)
89{
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*/
619a59a7 104function grade_create_category($courseid, $fullname, $items, $aggregation=GRADE_AGGREGATE_MEAN)
5834dcdb 105{
42bbccd7 106 $params = new stdClass();
619a59a7 107 $params->courseid = $courseid;
42bbccd7 108 $params->fullname = $fullname;
109 $params->items = $items;
110 $params->aggregation = $aggregation;
5834dcdb 111
42bbccd7 112 $grade_category = new grade_category($params);
113 return $grade_category->insert();
5834dcdb 114}
115
116
117/**
118* Tells a module whether a grade (or grade_item if $userid is not given) is currently locked or not.
119* This is a combination of the actual settings in the grade tables and a check on moodle/course:editgradeswhenlocked.
120* If it's locked to the current use then the module can print a nice message or prevent editing in the module.
121*
122* @param string $itemtype 'mod', 'blocks', 'import', 'calculated' etc
123* @param string $itemmodule 'forum, 'quiz', 'csv' etc
124* @param int $iteminstance id of the item module
125* @param int $userid ID of the user who owns the grade
126* @return boolean Whether the grade is locked or not
127*/
128function grade_is_locked($itemtype, $itemmodule, $iteminstance, $userid=NULL)
129{
42bbccd7 130 $grade_item = grade_item::get_record(true, 'itemtype', $itemtype, 'itemmodule', $itemmodule, 'iteminstance', $iteminstance);
131 if ($grade_item) {
132 return $grade_item->locked;
133 } else {
134 return null;
135 }
5834dcdb 136}
137
60cf7430 138?>