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) 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 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      * Records this object in the Database, sets its id to the returned value, and returns that value.
 101      * If successful this function also fetches the new object data from database and stores it
 102      * in object properties.
 103      * @param string $source from where was the object inserted (mod/forum, manual, etc.)
 104      * @return int PK ID if successful, false otherwise
 105      */
 106     function insert($source=null) {
 107         $this->timecreated = time();
 108         $this->timemodified = time();
 109         return parent::insert($source);
 110     }
 111
 112     /**
 113      * In addition to update() it also updates grade_outcomes_courses if needed
 114      * @param string $source from where was the object inserted
 115      * @return boolean success
 116      */
 117     function update($source=null) {
 118         $this->timemodified = time();
 119         return parent::update($source);
 120     }
 121
 122     /**
 123      * Returns the most descriptive field for this object. This is a standard method used
 124      * when we do not know the exact type of an object.
 125      * @return string name
 126      */
 127     function get_name() {
 128         return format_string($this->name);
 129     }
 130
 131     /**
 132      * Loads the scale's items into the $scale_items array.
 133      * There are three ways to achieve this:
 134      * 1. No argument given: The $scale string is already loaded and exploded to an array of items.
 135      * 2. A string is given: A comma-separated list of items is exploded into an array of items.
 136      * 3. An array of items is given and saved directly as the array of items for this scale.
 137      *
 138      * @param mixed $items Could be null, a string or an array. The method behaves differently for each case.
 139      * @return array The resulting array of scale items or null if the method failed to produce one.
 140      */
 141     function load_items($items=NULL) {
 142         if (empty($items)) {
 143             $this->scale_items = explode(',', $this->scale);
 144         } elseif (is_array($items)) {
 145             $this->scale_items = $items;
 146         } else {
 147             $this->scale_items = explode(',', $items);
 148         }
 149
 150         // Trim whitespace around each value
 151         foreach ($this->scale_items as $key => $val) {
 152             $this->scale_items[$key] = trim($val);
 153         }
 154
 155         return $this->scale_items;
 156     }
 157
 158     /**
 159      * Compacts (implodes) the array of items in $scale_items into a comma-separated string, $scale.
 160      * There are three ways to achieve this:
 161      * 1. No argument given: The $scale_items array is already loaded and imploded to a string of items.
 162      * 2. An array is given and is imploded into a string of items.
 163      * 3. A string of items is given and saved directly as the $scale variable.
 164      * NOTE: This method is the exact reverse of load_items, and their input/output should be interchangeable. However,
 165      * because load_items() trims the whitespace around the items, when the string is reconstructed these whitespaces will
 166      * be missing. This is not an issue, but should be kept in mind when comparing the two strings.
 167      *
 168      * @param mixed $items Could be null, a string or an array. The method behaves differently for each case.
 169      * @return array The resulting string of scale items or null if the method failed to produce one.
 170      */
 171     function compact_items($items=NULL) {
 172         if (empty($items)) {
 173             $this->scale = implode(',', $this->scale_items);
 174         } elseif (is_array($items)) {
 175             $this->scale = implode(',', $items);
 176         } else {
 177             $this->scale = $items;
 178         }
 179
 180         return $this->scale;
 181     }
 182
 183     /**
 184      * When called on a loaded scale object (with a valid id) and given a float grade between
 185      * the grademin and grademax, this method returns the scale item that falls closest to the
 186      * float given (which is usually an average of several grades on a scale). If the float falls
 187      * below 1 but above 0, it will be rounded up to 1.
 188      * @param float $grade
 189      * @return string
 190      */
 191     function get_nearest_item($grade) {
 192         // Obtain nearest scale item from average
 193         $scales_array = get_records_list('scale', 'id', $this->id);
 194         $scale = $scales_array[$this->id];
 195         $scales = explode(",", $scale->scale);
 196
 197         // this could be a 0 when summed and rounded, e.g, 1, no grade, no grade, no grade
 198         if ($grade < 1) {
 199             $grade = 1;
 200         }
 201
 202         return $scales[$grade-1];
 203     }
 204
 205     /**
 206      * Static function returning all global scales
 207      * @return object
 208      */
 209     function fetch_all_global() {
 210         return grade_scale::fetch_all(array('courseid'=>0));
 211     }
 212
 213     /**
 214      * Static function returning all local course scales
 215      * @return object
 216      */
 217     function fetch_all_local($courseid) {
 218         return grade_scale::fetch_all(array('courseid'=>$courseid));
 219     }
 220
 221     /**
 222      * Checks if scale can be deleted.
 223      * @return boolean
 224      */
 225     function can_delete() {
 226         return !$this->is_used();
 227     }
 228
 229     /**
 230      * Returns if scale used anywhere - activities, grade items, outcomes, etc.
 231      * @return bool
 232      */
 233     function is_used() {
 234         global $CFG;
 235
 236         // count grade items excluding the
 237         $sql = "SELECT COUNT(id) FROM {$CFG->prefix}grade_items WHERE scaleid = {$this->id} AND outcomeid IS NULL";
 238         if (count_records_sql($sql)) {
 239             return true;
 240         }
 241
 242         // count outcomes
 243         $sql = "SELECT COUNT(id) FROM {$CFG->prefix}grade_outcomes WHERE scaleid = {$this->id}";
 244         if (count_records_sql($sql)) {
 245             return true;
 246         }
 247
 248         $legacy_mods = false;
 249         if ($mods = get_records('modules', 'visible', 1)) {
 250             foreach ($mods as $mod) {
 251                 //Check cm->name/lib.php exists
 252                 if (file_exists($CFG->dirroot.'/mod/'.$mod->name.'/lib.php')) {
 253                     include_once($CFG->dirroot.'/mod/'.$mod->name.'/lib.php');
 254                     $function_name = $mod->name.'_scale_used_anywhere';
 255                     $old_function_name = $mod->name.'_scale_used';
 256                     if (function_exists($function_name)) {
 257                         if ($function_name($this->id)) {
 258                             return true;
 259                         }
 260
 261                     } else if (function_exists($old_function_name)) {
 262                         $legacy_mods = true;
 263                         debugging('Please notify the developer of module "'.$mod->name.'" that new function module_scale_used_anywhere() should be implemented.', DEBUG_DEVELOPER);
 264                         break;
 265                     }
 266                 }
 267             }
 268         }
 269
 270         // some mods are missing the new xxx_scale_used_anywhere() - use the really slow old way
 271         if ($legacy_mods) {
 272             if (!empty($this->courseid)) {
 273                 if (course_scale_used($this->courseid,$this->id)) {
 274                     return true;
 275                 }
 276             } else {
 277                 $courses = array();
 278                 if (site_scale_used($this->id,$courses)) {
 279                     return true;
 280                 }
 281             }
 282         }
 283
 284         return false;
 285     }
 286 }
 287 ?>