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 class variables that are not part of the DB table fields
  41      * @var array $nonfields
  42      */
  43     var $nonfields = array('table', 'nonfields', 'required_fields', 'scale');
  44
  45     /**
  46      * The course this outcome belongs to.
  47      * @var int $courseid
  48      */
  49     var $courseid;
  50
  51     /**
  52      * The shortname of the outcome.
  53      * @var string $shortname
  54      */
  55     var $shortname;
  56
  57     /**
  58      * The fullname of the outcome.
  59      * @var string $fullname
  60      */
  61     var $fullname;
  62
  63     /**
  64      * A full grade_scale object referenced by $this->scaleid.
  65      * @var object $scale
  66      */
  67     var $scale;
  68
  69     /**
  70      * The id of the scale referenced by this outcome.
  71      * @var int $scaleid
  72      */
  73     var $scaleid;
  74
  75     /**
  76      * The userid of the person who last modified this outcome.
  77      * @var int $usermodified
  78      */
  79     var $usermodified;
  80
  81     /**
  82      * Finds and returns a grade_outcome instance based on params.
  83      * @static
  84      *
  85      * @param array $params associative arrays varname=>value
  86      * @return object grade_outcome instance or false if none found.
  87      */
  88     function fetch($params) {
  89         if ($outcome = grade_object::fetch_helper('grade_outcomes', 'grade_outcome', $params)) {
  90             if (!empty($outcome->scaleid)) {
  91                 $outcome->scale = new grade_scale(array('id'=>$outcome->scaleid));
  92                 $outcome->scale->load_items();
  93             }
  94             return $outcome;
  95
  96         } else {
  97             return false;
  98         }
  99     }
 100
 101     /**
 102      * Finds and returns all grade_outcome instances based on params.
 103      * @static
 104      *
 105      * @param array $params associative arrays varname=>value
 106      * @param bool $fetch_sitewide_outcomes Whether or not to also fetch all sitewide outcomes (with no courseid)
 107      * @return array array of grade_outcome insatnces or false if none found.
 108      */
 109     function fetch_all($params, $fetch_sitewide_outcomes=false) {
 110         global $CFG;
 111
 112         if ($outcomes = grade_object::fetch_all_helper('grade_outcomes', 'grade_outcome', $params)) {
 113             // Fetch sitewide outcomes if requested
 114             if ($fetch_sitewide_outcomes) {
 115                 $sitewide_outcomes = array();
 116                 $records = get_records_sql("SELECT * FROM {$CFG->prefix}grade_outcomes WHERE courseid IS NULL");
 117                 foreach ($records as $outcomeid => $outcome) {
 118                     $sitewide_outcomes[$outcomeid] = new grade_outcome($outcome, false);
 119                 }
 120                 $outcomes = array_merge($sitewide_outcomes, $outcomes);
 121             }
 122
 123             foreach ($outcomes as $key=>$value) {
 124                 if (!empty($outcomes[$key]->scaleid)) {
 125                     $outcomes[$key]->scale = new grade_scale(array('id'=>$outcomes[$key]->scaleid));
 126                     $outcomes[$key]->scale->load_items();
 127                 }
 128             }
 129             return $outcomes;
 130
 131         } else {
 132             return false;
 133         }
 134     }
 135
 136     /**
 137      * Returns the most descriptive field for this object. This is a standard method used
 138      * when we do not know the exact type of an object.
 139      * @return string name
 140      */
 141     function get_name() {
 142         return $this->shortname;
 143     }
 144
 145     /**
 146      * Computes then returns extra information about this outcome and other objects that are linked to it.
 147      * The average of all grades that use this outcome, for all courses (or 1 course if courseid is given) can
 148      * be requested, and is returned as a float if requested alone. If the list of items that use this outcome
 149      * is also requested, then a single array is returned, which contains the grade_items AND the average grade
 150      * if such is still requested (array('items' => array(...), 'avg' => 2.30)). This combining of two
 151      * methods into one is to save on DB queries, since both queries are similar and can be performed together.
 152      * @param int $courseid An optional courseid to narrow down the average to 1 course only
 153      * @param bool $average Whether or not to return the average grade for this outcome
 154      * @param bool $items Whether or not to return the list of items using this outcome
 155      * @return float
 156      */
 157     function get_grade_info($courseid=null, $average=true, $items=false) {
 158         if (!isset($this->id)) {
 159             debugging("You must setup the outcome's id before calling its get_grade_info() method!");
 160             return false; // id must be defined for this to work
 161         }
 162
 163         if ($average === false && $items === false) {
 164             debugging('Either the 1st or 2nd param of grade_outcome::get_grade_info() must be true, or both, but not both false!');
 165             return false;
 166         }
 167
 168         $wheresql = '';
 169         if (!is_null($courseid)) {
 170             $wheresql = " AND mdl_grade_items.courseid = $courseid ";
 171         }
 172
 173         $selectadd = '';
 174         if ($items !== false) {
 175             $selectadd = ', mdl_grade_items.* ';
 176         }
 177
 178         $sql = "SELECT finalgrade $selectadd
 179                   FROM mdl_grade_grades, mdl_grade_items, mdl_grade_outcomes
 180                  WHERE mdl_grade_outcomes.id = mdl_grade_items.outcomeid
 181                    AND mdl_grade_items.id = mdl_grade_grades.itemid
 182                    AND mdl_grade_outcomes.id = $this->id
 183                    $wheresql";
 184
 185         $grades = get_records_sql($sql);
 186         $retval = array();
 187
 188         if ($average !== false && count($grades) > 0) {
 189             $count = 0;
 190             $total = 0;
 191
 192             foreach ($grades as $k => $grade) {
 193                 // Skip null finalgrades
 194                 if (!is_null($grade->finalgrade)) {
 195                     $total += $grade->finalgrade;
 196                     $count++;
 197                 }
 198                 unset($grades[$k]->finalgrade);
 199             }
 200
 201             $retval['avg'] = $total / $count;
 202         }
 203
 204         if ($items !== false) {
 205             foreach ($grades as $grade) {
 206                 $retval['items'][$grade->id] = new grade_item($grade);
 207             }
 208         }
 209
 210         return $retval;
 211     }
 212 }
 213 ?>