lib/grade/grade_outcome.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 require_once('grade_object.php');
  27
  28 /**
  29  * Class representing a grade outcome. It is responsible for handling its DB representation,
  30  * modifying and returning its metadata.
  31  */
  32 class grade_outcome extends grade_object {
  33     /**
  34      * DB Table (used by grade_object).
  35      * @var string $table
  36      */
  37     var $table = 'grade_outcomes';
  38
  39     /**
  40      * Array of required table fields, must start with 'id'.
  41      * @var array $required_fields
  42      */
  43     var $required_fields = array('id', 'courseid', 'shortname', 'fullname', 'scaleid',
  44                                  'description', 'timecreated', 'timemodified', 'usermodified');
  45
  46     /**
  47      * The course this outcome belongs to.
  48      * @var int $courseid
  49      */
  50     var $courseid;
  51
  52     /**
  53      * The shortname of the outcome.
  54      * @var string $shortname
  55      */
  56     var $shortname;
  57
  58     /**
  59      * The fullname of the outcome.
  60      * @var string $fullname
  61      */
  62     var $fullname;
  63
  64     /**
  65      * A full grade_scale object referenced by $this->scaleid.
  66      * @var object $scale
  67      */
  68     var $scale;
  69
  70     /**
  71      * The id of the scale referenced by this outcome.
  72      * @var int $scaleid
  73      */
  74     var $scaleid;
  75
  76     /**
  77      * The description of this outcome - FORMAT_MOODLE.
  78      * @var string $description
  79      */
  80     var $description;
  81
  82     /**
  83      * The userid of the person who last modified this outcome.
  84      * @var int $usermodified
  85      */
  86     var $usermodified;
  87
  88     /**
  89      * Deletes this outcome from the database.
  90      * @param string $source from where was the object deleted (mod/forum, manual, etc.)
  91      * @return boolean success
  92      */
  93     function delete($source=null) {
  94         if (!empty($this->courseid)) {
  95             delete_records('grade_outcomes_courses', 'outcomeid', $this->id, 'courseid', $this->courseid);
  96         }
  97         return parent::delete($source);
  98     }
  99
 100     /**
 101      * Records this object in the Database, sets its id to the returned value, and returns that value.
 102      * If successful this function also fetches the new object data from database and stores it
 103      * in object properties.
 104      * @param string $source from where was the object inserted (mod/forum, manual, etc.)
 105      * @return int PK ID if successful, false otherwise
 106      */
 107     function insert($source=null) {
 108         if ($result = parent::insert($source)) {
 109             if (!empty($this->courseid)) {
 110                 $goc = new object();
 111                 $goc->courseid = $this->courseid;
 112                 $goc->outcomeid = $this->id;
 113                 insert_record('grade_outcomes_courses', $goc);
 114             }
 115         }
 116         return $result;
 117     }
 118
 119     /**
 120      * In addition to update() it also updates grade_outcomes_courses if needed
 121      * @param string $source from where was the object inserted
 122      * @return boolean success
 123      */
 124     function update($source=null) {
 125         if ($result = parent::update($source)) {
 126             if (!empty($this->courseid)) {
 127                 if (!get_records('grade_outcomes_courses', 'courseid', $this->courseid, 'outcomeid', $this->id)) {
 128                     $goc = new object();
 129                     $goc->courseid = $this->courseid;
 130                     $goc->outcomeid = $this->id;
 131                     insert_record('grade_outcomes_courses', $goc);
 132                 }
 133             }
 134         }
 135         return $result;
 136     }
 137
 138     /**
 139      * Finds and returns a grade_outcome instance based on params.
 140      * @static
 141      *
 142      * @param array $params associative arrays varname=>value
 143      * @return object grade_outcome instance or false if none found.
 144      */
 145     function fetch($params) {
 146         return grade_object::fetch_helper('grade_outcomes', 'grade_outcome', $params);
 147     }
 148
 149     /**
 150      * Finds and returns all grade_outcome instances based on params.
 151      * @static
 152      *
 153      * @param array $params associative arrays varname=>value
 154      * @return array array of grade_outcome insatnces or false if none found.
 155      */
 156     function fetch_all($params) {
 157         return grade_object::fetch_all_helper('grade_outcomes', 'grade_outcome', $params);
 158     }
 159
 160     /**
 161      * Instantiates a grade_scale object whose data is retrieved from the
 162      * @return object grade_scale
 163      */
 164     function load_scale() {
 165         if (empty($this->scale->id) or $this->scale->id != $this->scaleid) {
 166             $this->scale = grade_scale::fetch(array('id'=>$this->scaleid));
 167             $this->scale->load_items();
 168         }
 169         return $this->scale;
 170     }
 171
 172     /**
 173      * Static function returning all global outcomes
 174      * @static
 175      * @return object
 176      */
 177     function fetch_all_global() {
 178         if (!$outcomes = grade_outcome::fetch_all(array('courseid'=>null))) {
 179             $outcomes = array();
 180         }
 181         return $outcomes;
 182     }
 183
 184     /**
 185      * Static function returning all local course outcomes
 186      * @static
 187      * @param int $courseid
 188      * @return object
 189      */
 190     function fetch_all_local($courseid) {
 191         if (!$outcomes =grade_outcome::fetch_all(array('courseid'=>$courseid))) {
 192             $outcomes = array();
 193         }
 194         return $outcomes;
 195     }
 196
 197     /**
 198      * Static method - returns all outcomes available in course
 199      * @static
 200      * @param int $courseid
 201      * @return array
 202      */
 203     function fetch_all_available($courseid) {
 204         global $CFG;
 205
 206         $result = array();
 207         $sql = "SELECT go.*
 208                   FROM {$CFG->prefix}grade_outcomes go, {$CFG->prefix}grade_outcomes_courses goc
 209                  WHERE go.id = goc.outcomeid AND goc.courseid = {$courseid}
 210               ORDER BY go.id ASC";
 211
 212         if ($datas = get_records_sql($sql)) {
 213             foreach($datas as $data) {
 214                 $instance = new grade_outcome();
 215                 grade_object::set_properties($instance, $data);
 216                 $result[$instance->id] = $instance;
 217             }
 218         }
 219         return $result;
 220     }
 221
 222
 223     /**
 224      * Returns the most descriptive field for this object. This is a standard method used
 225      * when we do not know the exact type of an object.
 226      * @return string name
 227      */
 228     function get_name() {
 229         return format_string($this->fullname);
 230     }
 231
 232     /**
 233      * Returns unique outcome short name.
 234      * @return string name
 235      */
 236     function get_shortname() {
 237         return $this->shortname;
 238     }
 239
 240     /**
 241      * Checks if outcome can be deleted.
 242      * @return boolean
 243      */
 244     function can_delete() {
 245         if ($this->get_item_uses_count()) {
 246             return false;
 247         }
 248         if (empty($this->courseid)) {
 249             if ($this->get_course_uses_count()) {
 250                 return false;
 251             }
 252         }
 253         return true;
 254     }
 255
 256     /**
 257      * Returns the number of places where outcome is used.
 258      * @return int
 259      */
 260     function get_course_uses_count() {
 261         global $CFG;
 262
 263         if (!empty($this->courseid)) {
 264             return 1;
 265         }
 266
 267         return count_records('grade_outcomes_courses', 'outcomeid', $this->id);
 268     }
 269
 270     /**
 271      * Returns the number of places where outcome is used.
 272      * @return int
 273      */
 274     function get_item_uses_count() {
 275         return count_records('grade_items', 'outcomeid', $this->id);
 276     }
 277
 278     /**
 279      * Computes then returns extra information about this outcome and other objects that are linked to it.
 280      * The average of all grades that use this outcome, for all courses (or 1 course if courseid is given) can
 281      * be requested, and is returned as a float if requested alone. If the list of items that use this outcome
 282      * is also requested, then a single array is returned, which contains the grade_items AND the average grade
 283      * if such is still requested (array('items' => array(...), 'avg' => 2.30)). This combining of two
 284      * methods into one is to save on DB queries, since both queries are similar and can be performed together.
 285      * @param int $courseid An optional courseid to narrow down the average to 1 course only
 286      * @param bool $average Whether or not to return the average grade for this outcome
 287      * @param bool $items Whether or not to return the list of items using this outcome
 288      * @return float
 289      */
 290     function get_grade_info($courseid=null, $average=true, $items=false) {
 291         global $CFG;
 292
 293         if (!isset($this->id)) {
 294             debugging("You must setup the outcome's id before calling its get_grade_info() method!");
 295             return false; // id must be defined for this to work
 296         }
 297
 298         if ($average === false && $items === false) {
 299             debugging('Either the 1st or 2nd param of grade_outcome::get_grade_info() must be true, or both, but not both false!');
 300             return false;
 301         }
 302
 303         $wheresql = '';
 304         if (!is_null($courseid)) {
 305             $wheresql = " AND {$CFG->prefix}grade_items.courseid = $courseid ";
 306         }
 307
 308         $selectadd = '';
 309         if ($items !== false) {
 310             $selectadd = ", {$CFG->prefix}grade_items.* ";
 311         }
 312
 313         $sql = "SELECT finalgrade $selectadd
 314                   FROM {$CFG->prefix}grade_grades, {$CFG->prefix}grade_items, {$CFG->prefix}grade_outcomes
 315                  WHERE {$CFG->prefix}grade_outcomes.id = {$CFG->prefix}grade_items.outcomeid
 316                    AND {$CFG->prefix}grade_items.id = {$CFG->prefix}grade_grades.itemid
 317                    AND {$CFG->prefix}grade_outcomes.id = $this->id
 318                    $wheresql";
 319
 320         $grades = get_records_sql($sql);
 321         $retval = array();
 322
 323         if ($average !== false && count($grades) > 0) {
 324             $count = 0;
 325             $total = 0;
 326
 327             foreach ($grades as $k => $grade) {
 328                 // Skip null finalgrades
 329                 if (!is_null($grade->finalgrade)) {
 330                     $total += $grade->finalgrade;
 331                     $count++;
 332                 }
 333                 unset($grades[$k]->finalgrade);
 334             }
 335
 336             $retval['avg'] = $total / $count;
 337         }
 338
 339         if ($items !== false) {
 340             foreach ($grades as $grade) {
 341                 $retval['items'][$grade->id] = new grade_item($grade);
 342             }
 343         }
 344
 345         return $retval;
 346     }
 347 }
 348 ?>