lib/grade/grade_scale.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 scale. It is responsible for handling its DB representation,
  30  * modifying and returning its metadata.
  31  */
  32 class grade_scale extends grade_object {
  33     /**
  34      * DB Table (used by grade_object).
  35      * @var string $table
  36      */
  37     var $table = 'scale';
  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', 'userid', 'name', 'scale', 'description', 'timemodified');
  44
  45     /**
  46      * The course this scale belongs to.
  47      * @var int $courseid
  48      */
  49     var $courseid;
  50
  51     var $userid;
  52
  53     /**
  54      * The name of the scale.
  55      * @var string $name
  56      */
  57     var $name;
  58
  59     /**
  60      * The items in this scale.
  61      * @var array $scale_items
  62      */
  63     var $scale_items = array();
  64
  65     /**
  66      * A string representatin of the scale items (a comma-separated list).
  67      * @var string $scale
  68      */
  69     var $scale;
  70
  71     /**
  72      * A description for this scale.
  73      * @var string $description
  74      */
  75     var $description;
  76
  77     /**
  78      * Finds and returns a grade_scale instance based on params.
  79      * @static
  80      *
  81      * @param array $params associative arrays varname=>value
  82      * @return object grade_scale instance or false if none found.
  83      */
  84     function fetch($params) {
  85         return grade_object::fetch_helper('scale', 'grade_scale', $params);
  86     }
  87
  88     /**
  89      * Finds and returns all grade_scale instances based on params.
  90      * @static
  91      *
  92      * @param array $params associative arrays varname=>value
  93      * @return array array of grade_scale insatnces or false if none found.
  94      */
  95     function fetch_all($params) {
  96         return grade_object::fetch_all_helper('scale', 'grade_scale', $params);
  97     }
  98
  99     /**
 100      * Returns the most descriptive field for this object. This is a standard method used
 101      * when we do not know the exact type of an object.
 102      * @return string name
 103      */
 104     function get_name() {
 105         return format_string($this->name);
 106     }
 107
 108     /**
 109      * Loads the scale's items into the $scale_items array.
 110      * There are three ways to achieve this:
 111      * 1. No argument given: The $scale string is already loaded and exploded to an array of items.
 112      * 2. A string is given: A comma-separated list of items is exploded into an array of items.
 113      * 3. An array of items is given and saved directly as the array of items for this scale.
 114      *
 115      * @param mixed $items Could be null, a string or an array. The method behaves differently for each case.
 116      * @return array The resulting array of scale items or null if the method failed to produce one.
 117      */
 118     function load_items($items=NULL) {
 119         if (empty($items)) {
 120             $this->scale_items = explode(',', $this->scale);
 121         } elseif (is_array($items)) {
 122             $this->scale_items = $items;
 123         } else {
 124             $this->scale_items = explode(',', $items);
 125         }
 126
 127         // Trim whitespace around each value
 128         foreach ($this->scale_items as $key => $val) {
 129             $this->scale_items[$key] = trim($val);
 130         }
 131
 132         return $this->scale_items;
 133     }
 134
 135     /**
 136      * Compacts (implodes) the array of items in $scale_items into a comma-separated string, $scale.
 137      * There are three ways to achieve this:
 138      * 1. No argument given: The $scale_items array is already loaded and imploded to a string of items.
 139      * 2. An array is given and is imploded into a string of items.
 140      * 3. A string of items is given and saved directly as the $scale variable.
 141      * NOTE: This method is the exact reverse of load_items, and their input/output should be interchangeable. However,
 142      * because load_items() trims the whitespace around the items, when the string is reconstructed these whitespaces will
 143      * be missing. This is not an issue, but should be kept in mind when comparing the two strings.
 144      *
 145      * @param mixed $items Could be null, a string or an array. The method behaves differently for each case.
 146      * @return array The resulting string of scale items or null if the method failed to produce one.
 147      */
 148     function compact_items($items=NULL) {
 149         if (empty($items)) {
 150             $this->scale = implode(',', $this->scale_items);
 151         } elseif (is_array($items)) {
 152             $this->scale = implode(',', $items);
 153         } else {
 154             $this->scale = $items;
 155         }
 156
 157         return $this->scale;
 158     }
 159
 160     /**
 161      * When called on a loaded scale object (with a valid id) and given a float grade between
 162      * the grademin and grademax, this method returns the scale item that falls closest to the
 163      * float given (which is usually an average of several grades on a scale). If the float falls
 164      * below 1 but above 0, it will be rounded up to 1.
 165      * @param float $grade
 166      * @return string
 167      */
 168     function get_nearest_item($grade) {
 169         // Obtain nearest scale item from average
 170         $scales_array = get_records_list('scale', 'id', $this->id);
 171         $scale = $scales_array[$this->id];
 172         $scales = explode(",", $scale->scale);
 173
 174         // this could be a 0 when summed and rounded, e.g, 1, no grade, no grade, no grade
 175         if ($grade < 1) {
 176             $grade = 1;
 177         }
 178
 179         return $scales[$grade-1];
 180     }
 181
 182     /**
 183      * Static function returning all global scales
 184      * @return object
 185      */
 186     function fetch_all_global() {
 187         return grade_scale::fetch_all(array('courseid'=>0));
 188     }
 189
 190     /**
 191      * Static function returning all local course scales
 192      * @return object
 193      */
 194     function fetch_all_local($courseid) {
 195         return grade_scale::fetch_all(array('courseid'=>$courseid));
 196     }
 197
 198     /**
 199      * Checks if scale can be deleted.
 200      * @return boolean
 201      */
 202     function can_delete() {
 203         return !$this->is_used();
 204     }
 205
 206     /**
 207      * Returns if scale used anywhere - activities, grade items, outcomes, etc.
 208      * @return bool
 209      */
 210     function is_used() {
 211         global $CFG;
 212
 213         // count grade items excluding the
 214         $sql = "SELECT COUNT(id) FROM {$CFG->prefix}grade_items WHERE scaleid = {$this->id} AND outcomeid IS NULL";
 215         if (count_records_sql($sql)) {
 216             return true;
 217         }
 218
 219         // count outcomes
 220         $sql = "SELECT COUNT(id) FROM {$CFG->prefix}grade_outcomes WHERE scaleid = {$this->id}";
 221         if (count_records_sql($sql)) {
 222             return true;
 223         }
 224
 225         $legacy_mods = false;
 226         if ($mods = get_records('modules', 'visible', 1)) {
 227             foreach ($mods as $mod) {
 228                 //Check cm->name/lib.php exists
 229                 if (file_exists($CFG->dirroot.'/mod/'.$mod->name.'/lib.php')) {
 230                     include_once($CFG->dirroot.'/mod/'.$mod->name.'/lib.php');
 231                     $function_name = $mod->name.'_scale_used_anywhere';
 232                     $old_function_name = $mod->name.'_scale_used';
 233                     if (function_exists($function_name)) {
 234                         if ($function_name($this->id)) {
 235                             return true;
 236                         }
 237
 238                     } else if (function_exists($old_function_name)) {
 239                         $legacy_mods = true;
 240                         debugging('Please notify the developer of module "'.$mod->name.'" that new function module_scale_used_anywhere() should be implemented.', DEBUG_DEVELOPER);
 241                         break;
 242                     }
 243                 }
 244             }
 245         }
 246
 247         // some mods are missing the new xxx_scale_used_anywhere() - use the really slow old way
 248         if ($legacy_mods) {
 249             if (!empty($this->courseid)) {
 250                 if (course_scale_used($this->courseid,$this->id)) {
 251                     return true;
 252                 }
 253             } else {
 254                 $courses = array();
 255                 if (site_scale_used($this->id,$courses)) {
 256                     return true;
 257                 }
 258             }
 259         }
 260
 261         return false;
 262     }
 263 }
 264 ?>