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) 1999 onwards 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
 109         $this->timecreated = $this->timemodified = time();
 110
 111         if ($result = parent::insert($source)) {
 112             if (!empty($this->courseid)) {
 113                 $goc = new object();
 114                 $goc->courseid = $this->courseid;
 115                 $goc->outcomeid = $this->id;
 116                 insert_record('grade_outcomes_courses', $goc);
 117             }
 118         }
 119         return $result;
 120     }
 121
 122     /**
 123      * In addition to update() it also updates grade_outcomes_courses if needed
 124      * @param string $source from where was the object inserted
 125      * @return boolean success
 126      */
 127     function update($source=null) {
 128         $this->timemodified = time();
 129
 130         if ($result = parent::update($source)) {
 131             if (!empty($this->courseid)) {
 132                 $this->use_in($this->courseid);
 133             }
 134         }
 135         return $result;
 136     }
 137
 138     /**
 139      * Mark outcome as used in course
 140      * @param int $courseid
 141      * @return succes - false if incorrect courseid requested
 142      */
 143     function use_in($courseid) {
 144         if (!empty($this->courseid) and $courseid != $this->courseid) {
 145             return false;
 146         }
 147
 148         if (!record_exists('grade_outcomes_courses', 'courseid', $courseid, 'outcomeid', $this->id)) {
 149             $goc = new object();
 150             $goc->courseid  = $courseid;
 151             $goc->outcomeid = $this->id;
 152             return (bool)insert_record('grade_outcomes_courses', $goc);
 153         }
 154         return true;
 155     }
 156
 157     /**
 158      * Finds and returns a grade_outcome instance based on params.
 159      * @static
 160      *
 161      * @param array $params associative arrays varname=>value
 162      * @return object grade_outcome instance or false if none found.
 163      */
 164     function fetch($params) {
 165         return grade_object::fetch_helper('grade_outcomes', 'grade_outcome', $params);
 166     }
 167
 168     /**
 169      * Finds and returns all grade_outcome instances based on params.
 170      * @static
 171      *
 172      * @param array $params associative arrays varname=>value
 173      * @return array array of grade_outcome insatnces or false if none found.
 174      */
 175     function fetch_all($params) {
 176         return grade_object::fetch_all_helper('grade_outcomes', 'grade_outcome', $params);
 177     }
 178
 179     /**
 180      * Instantiates a grade_scale object whose data is retrieved from the
 181      * @return object grade_scale
 182      */
 183     function load_scale() {
 184         if (empty($this->scale->id) or $this->scale->id != $this->scaleid) {
 185             $this->scale = grade_scale::fetch(array('id'=>$this->scaleid));
 186             $this->scale->load_items();
 187         }
 188         return $this->scale;
 189     }
 190
 191     /**
 192      * Static function returning all global outcomes
 193      * @static
 194      * @return object
 195      */
 196     function fetch_all_global() {
 197         if (!$outcomes = grade_outcome::fetch_all(array('courseid'=>null))) {
 198             $outcomes = array();
 199         }
 200         return $outcomes;
 201     }
 202
 203     /**
 204      * Static function returning all local course outcomes
 205      * @static
 206      * @param int $courseid
 207      * @return object
 208      */
 209     function fetch_all_local($courseid) {
 210         if (!$outcomes =grade_outcome::fetch_all(array('courseid'=>$courseid))) {
 211             $outcomes = array();
 212         }
 213         return $outcomes;
 214     }
 215
 216     /**
 217      * Static method - returns all outcomes available in course
 218      * @static
 219      * @param int $courseid
 220      * @return array
 221      */
 222     function fetch_all_available($courseid) {
 223         global $CFG;
 224
 225         $result = array();
 226         $sql = "SELECT go.*
 227                   FROM {$CFG->prefix}grade_outcomes go, {$CFG->prefix}grade_outcomes_courses goc
 228                  WHERE go.id = goc.outcomeid AND goc.courseid = {$courseid}
 229               ORDER BY go.id ASC";
 230
 231         if ($datas = get_records_sql($sql)) {
 232             foreach($datas as $data) {
 233                 $instance = new grade_outcome();
 234                 grade_object::set_properties($instance, $data);
 235                 $result[$instance->id] = $instance;
 236             }
 237         }
 238         return $result;
 239     }
 240
 241
 242     /**
 243      * Returns the most descriptive field for this object. This is a standard method used
 244      * when we do not know the exact type of an object.
 245      * @return string name
 246      */
 247     function get_name() {
 248         return format_string($this->fullname);
 249     }
 250
 251     /**
 252      * Returns unique outcome short name.
 253      * @return string name
 254      */
 255     function get_shortname() {
 256         return $this->shortname;
 257     }
 258
 259     /**
 260      * Checks if outcome can be deleted.
 261      * @return boolean
 262      */
 263     function can_delete() {
 264         if ($this->get_item_uses_count()) {
 265             return false;
 266         }
 267         if (empty($this->courseid)) {
 268             if ($this->get_course_uses_count()) {
 269                 return false;
 270             }
 271         }
 272         return true;
 273     }
 274
 275     /**
 276      * Returns the number of places where outcome is used.
 277      * @return int
 278      */
 279     function get_course_uses_count() {
 280         global $CFG;
 281
 282         if (!empty($this->courseid)) {
 283             return 1;
 284         }
 285
 286         return count_records('grade_outcomes_courses', 'outcomeid', $this->id);
 287     }
 288
 289     /**
 290      * Returns the number of places where outcome is used.
 291      * @return int
 292      */
 293     function get_item_uses_count() {
 294         return count_records('grade_items', 'outcomeid', $this->id);
 295     }
 296
 297     /**
 298      * Computes then returns extra information about this outcome and other objects that are linked to it.
 299      * The average of all grades that use this outcome, for all courses (or 1 course if courseid is given) can
 300      * be requested, and is returned as a float if requested alone. If the list of items that use this outcome
 301      * is also requested, then a single array is returned, which contains the grade_items AND the average grade
 302      * if such is still requested (array('items' => array(...), 'avg' => 2.30)). This combining of two
 303      * methods into one is to save on DB queries, since both queries are similar and can be performed together.
 304      * @param int $courseid An optional courseid to narrow down the average to 1 course only
 305      * @param bool $average Whether or not to return the average grade for this outcome
 306      * @param bool $items Whether or not to return the list of items using this outcome
 307      * @return float
 308      */
 309     function get_grade_info($courseid=null, $average=true, $items=false) {
 310         global $CFG;
 311
 312         if (!isset($this->id)) {
 313             debugging("You must setup the outcome's id before calling its get_grade_info() method!");
 314             return false; // id must be defined for this to work
 315         }
 316
 317         if ($average === false && $items === false) {
 318             debugging('Either the 1st or 2nd param of grade_outcome::get_grade_info() must be true, or both, but not both false!');
 319             return false;
 320         }
 321
 322         $wheresql = '';
 323         if (!is_null($courseid)) {
 324             $wheresql = " AND {$CFG->prefix}grade_items.courseid = $courseid ";
 325         }
 326
 327         $selectadd = '';
 328         if ($items !== false) {
 329             $selectadd = ", {$CFG->prefix}grade_items.* ";
 330         }
 331
 332         $sql = "SELECT finalgrade $selectadd
 333                   FROM {$CFG->prefix}grade_grades, {$CFG->prefix}grade_items, {$CFG->prefix}grade_outcomes
 334                  WHERE {$CFG->prefix}grade_outcomes.id = {$CFG->prefix}grade_items.outcomeid
 335                    AND {$CFG->prefix}grade_items.id = {$CFG->prefix}grade_grades.itemid
 336                    AND {$CFG->prefix}grade_outcomes.id = $this->id
 337                    $wheresql";
 338
 339         $grades = get_records_sql($sql);
 340         $retval = array();
 341
 342         if ($average !== false && count($grades) > 0) {
 343             $count = 0;
 344             $total = 0;
 345
 346             foreach ($grades as $k => $grade) {
 347                 // Skip null finalgrades
 348                 if (!is_null($grade->finalgrade)) {
 349                     $total += $grade->finalgrade;
 350                     $count++;
 351                 }
 352                 unset($grades[$k]->finalgrade);
 353             }
 354
 355             $retval['avg'] = $total / $count;
 356         }
 357
 358         if ($items !== false) {
 359             foreach ($grades as $grade) {
 360                 $retval['items'][$grade->id] = new grade_item($grade);
 361             }
 362         }
 363
 364         return $retval;
 365     }
 366 }
 367 ?>