[Summary view] [Print] [Text view]

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