lib/grade/grade_scale.php

   1 <?php
   2
   3 // This file is part of Moodle - http://moodle.org/
   4 //
   5 // Moodle is free software: you can redistribute it and/or modify
   6 // it under the terms of the GNU General Public License as published by
   7 // the Free Software Foundation, either version 3 of the License, or
   8 // (at your option) any later version.
   9 //
  10 // Moodle is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 // GNU General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU General Public License
  16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  17 /**
  18  * Definitions of grade scale class
  19  *
  20  * @package    core
  21  * @subpackage grade
  22  * @copyright  2006 Nicolas Connault
  23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24  */
  25
  26 defined('MOODLE_INTERNAL') || die();
  27
  28 require_once('grade_object.php');
  29
  30 /**
  31  * Class representing a grade scale. It is responsible for handling its DB representation,
  32  * modifying and returning its metadata.
  33  */
  34 class grade_scale extends grade_object {
  35     /**
  36      * DB Table (used by grade_object).
  37      * @var string $table
  38      */
  39     public $table = 'scale';
  40
  41     /**
  42      * Array of required table fields, must start with 'id'.
  43      * @var array $required_fields
  44      */
  45     public $required_fields = array('id', 'courseid', 'userid', 'name', 'scale', 'description', 'descriptionformat', 'timemodified');
  46
  47     /**
  48      * The course this scale belongs to.
  49      * @var int $courseid
  50      */
  51     public $courseid;
  52
  53     public $userid;
  54
  55     /**
  56      * The name of the scale.
  57      * @var string $name
  58      */
  59     public $name;
  60
  61     /**
  62      * The items in this scale.
  63      * @var array $scale_items
  64      */
  65     public $scale_items = array();
  66
  67     /**
  68      * A string representation of the scale items (a comma-separated list).
  69      * @var string $scale
  70      */
  71     public $scale;
  72
  73     /**
  74      * A description for this scale.
  75      * @var string $description
  76      */
  77     public $description;
  78
  79     /**
  80      * Finds and returns a grade_scale instance based on params.
  81      * @static
  82      *
  83      * @param array $params associative arrays varname=>value
  84      * @return object grade_scale instance or false if none found.
  85      */
  86     public static function fetch($params) {
  87         return grade_object::fetch_helper('scale', 'grade_scale', $params);
  88     }
  89
  90     /**
  91      * Finds and returns all grade_scale instances based on params.
  92      * @static
  93      *
  94      * @param array $params associative arrays varname=>value
  95      * @return array array of grade_scale instances or false if none found.
  96      */
  97     public static function fetch_all($params) {
  98         return grade_object::fetch_all_helper('scale', 'grade_scale', $params);
  99     }
 100
 101     /**
 102      * Records this object in the Database, sets its id to the returned value, and returns that value.
 103      * If successful this function also fetches the new object data from database and stores it
 104      * in object properties.
 105      * @param string $source from where was the object inserted (mod/forum, manual, etc.)
 106      * @return int PK ID if successful, false otherwise
 107      */
 108     public function insert($source=null) {
 109         $this->timecreated = time();
 110         $this->timemodified = time();
 111         return parent::insert($source);
 112     }
 113
 114     /**
 115      * In addition to update() it also updates grade_outcomes_courses if needed
 116      * @param string $source from where was the object inserted
 117      * @return boolean success
 118      */
 119     public function update($source=null) {
 120         $this->timemodified = time();
 121         return parent::update($source);
 122     }
 123
 124     /**
 125      * Deletes this outcome from the database.
 126      * @param string $source from where was the object deleted (mod/forum, manual, etc.)
 127      * @return boolean success
 128      */
 129     public function delete($source=null) {
 130         global $DB;
 131         if (parent::delete($source)) {
 132             $context = get_context_instance(CONTEXT_SYSTEM);
 133             $fs = get_file_storage();
 134             $files = $fs->get_area_files($context->id, 'grade', 'scale', $this->id);
 135             foreach ($files as $file) {
 136                 $file->delete();
 137             }
 138             return true;
 139         }
 140         return false;
 141     }
 142
 143     /**
 144      * Returns the most descriptive field for this object. This is a standard method used
 145      * when we do not know the exact type of an object.
 146      * @return string name
 147      */
 148     public function get_name() {
 149         return format_string($this->name);
 150     }
 151
 152     /**
 153      * Loads the scale's items into the $scale_items array.
 154      * There are three ways to achieve this:
 155      * 1. No argument given: The $scale string is already loaded and exploded to an array of items.
 156      * 2. A string is given: A comma-separated list of items is exploded into an array of items.
 157      * 3. An array of items is given and saved directly as the array of items for this scale.
 158      *
 159      * @param mixed $items Could be null, a string or an array. The method behaves differently for each case.
 160      * @return array The resulting array of scale items or null if the method failed to produce one.
 161      */
 162     public function load_items($items=NULL) {
 163         if (empty($items)) {
 164             $this->scale_items = explode(',', $this->scale);
 165         } elseif (is_array($items)) {
 166             $this->scale_items = $items;
 167         } else {
 168             $this->scale_items = explode(',', $items);
 169         }
 170
 171         // Trim whitespace around each value
 172         foreach ($this->scale_items as $key => $val) {
 173             $this->scale_items[$key] = trim($val);
 174         }
 175
 176         return $this->scale_items;
 177     }
 178
 179     /**
 180      * Compacts (implodes) the array of items in $scale_items into a comma-separated string, $scale.
 181      * There are three ways to achieve this:
 182      * 1. No argument given: The $scale_items array is already loaded and imploded to a string of items.
 183      * 2. An array is given and is imploded into a string of items.
 184      * 3. A string of items is given and saved directly as the $scale variable.
 185      * NOTE: This method is the exact reverse of load_items, and their input/output should be interchangeable. However,
 186      * because load_items() trims the whitespace around the items, when the string is reconstructed these whitespaces will
 187      * be missing. This is not an issue, but should be kept in mind when comparing the two strings.
 188      *
 189      * @param mixed $items Could be null, a string or an array. The method behaves differently for each case.
 190      * @return array The resulting string of scale items or null if the method failed to produce one.
 191      */
 192     public function compact_items($items=NULL) {
 193         if (empty($items)) {
 194             $this->scale = implode(',', $this->scale_items);
 195         } elseif (is_array($items)) {
 196             $this->scale = implode(',', $items);
 197         } else {
 198             $this->scale = $items;
 199         }
 200
 201         return $this->scale;
 202     }
 203
 204     /**
 205      * When called on a loaded scale object (with a valid id) and given a float grade between
 206      * the grademin and grademax, this method returns the scale item that falls closest to the
 207      * float given (which is usually an average of several grades on a scale). If the float falls
 208      * below 1 but above 0, it will be rounded up to 1.
 209      * @param float $grade
 210      * @return string
 211      */
 212     public function get_nearest_item($grade) {
 213         global $DB;
 214         // Obtain nearest scale item from average
 215         $scales_array = $DB->get_records('scale', array('id' => $this->id));
 216         $scale = $scales_array[$this->id];
 217         $scales = explode(",", $scale->scale);
 218
 219         // this could be a 0 when summed and rounded, e.g, 1, no grade, no grade, no grade
 220         if ($grade < 1) {
 221             $grade = 1;
 222         }
 223
 224         return $scales[$grade-1];
 225     }
 226
 227     /**
 228      * Static function returning all global scales
 229      * @return object
 230      */
 231     public function fetch_all_global() {
 232         return grade_scale::fetch_all(array('courseid'=>0));
 233     }
 234
 235     /**
 236      * Static function returning all local course scales
 237      * @return object
 238      */
 239     public static function fetch_all_local($courseid) {
 240         return grade_scale::fetch_all(array('courseid'=>$courseid));
 241     }
 242
 243     /**
 244      * Checks if scale can be deleted.
 245      * @return boolean
 246      */
 247     public function can_delete() {
 248         return !$this->is_used();
 249     }
 250
 251     /**
 252      * Returns if scale used anywhere - activities, grade items, outcomes, etc.
 253      * @return bool
 254      */
 255     public function is_used() {
 256         global $DB;
 257         global $CFG;
 258
 259         // count grade items excluding the
 260         $params = array($this->id);
 261         $sql = "SELECT COUNT(id) FROM {grade_items} WHERE scaleid = ? AND outcomeid IS NULL";
 262         if ($DB->count_records_sql($sql, $params)) {
 263             return true;
 264         }
 265
 266         // count outcomes
 267         $sql = "SELECT COUNT(id) FROM {grade_outcomes} WHERE scaleid = ?";
 268         if ($DB->count_records_sql($sql, $params)) {
 269             return true;
 270         }
 271
 272         $legacy_mods = false;
 273         if ($mods = $DB->get_records('modules', array('visible' => 1))) {
 274             foreach ($mods as $mod) {
 275                 //Check cm->name/lib.php exists
 276                 if (file_exists($CFG->dirroot.'/mod/'.$mod->name.'/lib.php')) {
 277                     include_once($CFG->dirroot.'/mod/'.$mod->name.'/lib.php');
 278                     $function_name = $mod->name.'_scale_used_anywhere';
 279                     $old_function_name = $mod->name.'_scale_used';
 280                     if (function_exists($function_name)) {
 281                         if ($function_name($this->id)) {
 282                             return true;
 283                         }
 284
 285                     } else if (function_exists($old_function_name)) {
 286                         $legacy_mods = true;
 287                         debugging('Please notify the developer of module "'.$mod->name.'" that new function module_scale_used_anywhere() should be implemented.', DEBUG_DEVELOPER);
 288                         break;
 289                     }
 290                 }
 291             }
 292         }
 293
 294         // some mods are missing the new xxx_scale_used_anywhere() - use the really slow old way
 295         if ($legacy_mods) {
 296             if (!empty($this->courseid)) {
 297                 if (course_scale_used($this->courseid,$this->id)) {
 298                     return true;
 299                 }
 300             } else {
 301                 $courses = array();
 302                 if (site_scale_used($this->id,$courses)) {
 303                     return true;
 304                 }
 305             }
 306         }
 307
 308         return false;
 309     }
 310
 311     /**
 312      * Returns the formatted grade description with URLs converted
 313      * @return string
 314      */
 315     public function get_description() {
 316         global $CFG;
 317         require_once($CFG->libdir . '/filelib.php');
 318
 319         $systemcontext = get_context_instance(CONTEXT_SYSTEM);
 320         $options = new stdClass;
 321         $options->noclean = true;
 322         $description = file_rewrite_pluginfile_urls($this->description, 'pluginfile.php', $systemcontext->id, 'grade', 'scale', $this->id);
 323         return format_text($description, $this->descriptionformat, $options);
 324     }
 325 }