lib/gradelib.php

   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 define('GRADE_AGGREGATE_MEAN', 0);
  36 define('GRADE_AGGREGATE_MEDIAN', 1);
  37 define('GRADE_AGGREGATE_SUM', 2);
  38 define('GRADE_AGGREGATE_MODE', 3);
  39
  40 require_once($CFG->libdir . '/grade/grade_category.php');
  41 require_once($CFG->libdir . '/grade/grade_item.php');
  42 require_once($CFG->libdir . '/grade/grade_calculation.php');
  43
  44 /**
  45 * Extracts from the gradebook all the grade items attached to the calling object.
  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 *
  54 * @param int $courseid The id of the course to which the grade items belong
  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
  60 * @param int $idnumber grade item Primary Key
  61 * @return array An array of grade items
  62 */
  63 function grade_get_items($courseid, $itemname=NULL, $itemtype=NULL, $itemmodule=NULL, $iteminstance=NULL, $itemnumber=NULL, $idnumber=NULL) {
  64     $grade_item = new grade_item(compact('courseid', 'itemname', 'itemtype', 'itemmodule', 'iteminstance', 'itemnumber', 'idnumber'), false);
  65     $grade_items = $grade_item->fetch_all_using_this();
  66     return $grade_items;
  67 }
  68
  69
  70 /**
  71 * Creates a new grade_item in case it doesn't exist. This function would be called when a module
  72 * is created or updates, for example, to ensure grade_item entries exist.
  73 * It's not essential though--if grades are being added later and a matching grade_item doesn't
  74 * yet exist, the gradebook will create them on the fly.
  75 *
  76 * @param
  77 * @return mixed New grade_item id if successful
  78 */
  79 function grade_create_item($params) {
  80     $grade_item = new grade_item($params);
  81     return $grade_item->insert();
  82 }
  83
  84 /**
  85 * For a given set of items, create a category to group them together (if one doesn't yet exist).
  86 * Modules may want to do this when they are created. However, the ultimate control is in the gradebook interface itself.
  87 *
  88 * @param int $courseid
  89 * @param string $fullname The name of the new category
  90 * @param array $items An array of grade_items to group under the new category
  91 * @param string $aggregation
  92 * @return mixed New grade_category id if successful
  93 */
  94 function grade_create_category($courseid, $fullname, $items, $aggregation=GRADE_AGGREGATE_MEAN) {
  95     $grade_category = new grade_category(compact('courseid', 'fullname', 'items', 'aggregation'));
  96     return $grade_category->insert();
  97 }
  98
  99
 100 /**
 101 * Tells a module whether a grade (or grade_item if $userid is not given) is currently locked or not.
 102 * This is a combination of the actual settings in the grade tables and a check on moodle/course:editgradeswhenlocked.
 103 * If it's locked to the current use then the module can print a nice message or prevent editing in the module.
 104 * If no $userid is given, the method will always return the grade_item's locked state.
 105 * If a $userid is given, the method will first check the grade_item's locked state (the column). If it is locked,
 106 * the method will return true no matter the locked state of the specific grade being checked. If unlocked, it will
 107 * return the locked state of the specific grade.
 108 *
 109 * @param string $itemtype 'mod', 'blocks', 'import', 'calculated' etc
 110 * @param string $itemmodule 'forum, 'quiz', 'csv' etc
 111 * @param int $iteminstance id of the item module
 112 * @param int $itemnumber Optional number of the item to check
 113 * @param int $userid ID of the user who owns the grade
 114 * @return boolean Whether the grade is locked or not
 115 */
 116 function grade_is_locked($itemtype, $itemmodule, $iteminstance, $itemnumber=NULL, $userid=NULL) {
 117     $grade_item = new grade_item(compact('itemtype', 'itemmodule', 'iteminstance', 'itemnumber'));
 118     return $grade_item->is_locked($userid);
 119 }
 120
 121 ?>