2 // This file is part of Moodle - http://moodle.org/
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.
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.
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/>.
18 * Definition of grade scale class
20 * @package core_grades
22 * @copyright 2006 Nicolas Connault
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26 defined('MOODLE_INTERNAL') ||
die();
28 require_once('grade_object.php');
31 * Class representing a grade scale.
33 * It is responsible for handling its DB representation, modifying and returning its metadata.
35 * @package core_grades
37 * @copyright 2006 Nicolas Connault
38 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
40 class grade_scale
extends grade_object
{
42 * DB Table (used by grade_object).
45 public $table = 'scale';
48 * Array of required table fields, must start with 'id'.
49 * @var array $required_fields
51 public $required_fields = array('id', 'courseid', 'userid', 'name', 'scale', 'description', 'descriptionformat', 'timemodified');
54 * The course this scale belongs to.
60 * The ID of the user who created the scale
66 * The name of the scale.
72 * The items in this scale.
73 * @var array $scale_items
75 public $scale_items = array();
78 * A string representation of the scale items (a comma-separated list).
84 * A description for this scale.
85 * @var string $description
96 * Identifier of the text format to be used.
97 * @var int $descriptionformat
99 public int $descriptionformat;
102 * Finds and returns a grade_scale instance based on params.
105 * @param array $params associative arrays varname=>value
106 * @return object grade_scale instance or false if none found.
108 public static function fetch($params) {
109 return grade_object
::fetch_helper('scale', 'grade_scale', $params);
113 * Finds and returns all grade_scale instances based on params.
116 * @param array $params associative arrays varname=>value
117 * @return array array of grade_scale instances or false if none found.
119 public static function fetch_all($params) {
120 return grade_object
::fetch_all_helper('scale', 'grade_scale', $params);
124 * Records this object in the Database, sets its id to the returned value, and returns that value.
125 * If successful this function also fetches the new object data from database and stores it
126 * in object properties.
128 * @param string $source from where was the object inserted (mod/forum, manual, etc.)
129 * @param bool $isbulkupdate If bulk grade update is happening.
130 * @return int PK ID if successful, false otherwise
132 public function insert($source = null, $isbulkupdate = false) {
133 $this->timecreated
= time();
134 $this->timemodified
= time();
136 $result = parent
::insert($source);
138 // Trigger the scale created event.
139 if (!empty($this->standard
)) {
140 $eventcontext = context_system
::instance();
142 if (!empty($this->courseid
)) {
143 $eventcontext = context_course
::instance($this->courseid
);
145 $eventcontext = context_system
::instance();
148 $event = \core\event\scale_created
::create(array(
149 'objectid' => $result,
150 'context' => $eventcontext
158 * In addition to update() it also updates grade_outcomes_courses if needed
160 * @param string $source from where was the object inserted
161 * @param bool $isbulkupdate If bulk grade update is happening.
162 * @return bool success
164 public function update($source = null, $isbulkupdate = false) {
165 $this->timemodified
= time();
167 $result = parent
::update($source);
169 // Trigger the scale updated event.
170 if (!empty($this->standard
)) {
171 $eventcontext = context_system
::instance();
173 if (!empty($this->courseid
)) {
174 $eventcontext = context_course
::instance($this->courseid
);
176 $eventcontext = context_system
::instance();
179 $event = \core\event\scale_updated
::create(array(
180 'objectid' => $this->id
,
181 'context' => $eventcontext
189 * Deletes this scale from the database.
191 * @param string $source from where was the object deleted (mod/forum, manual, etc.)
192 * @return bool success
194 public function delete($source=null) {
197 // Trigger the scale deleted event.
198 if (!empty($this->standard
)) {
199 $eventcontext = context_system
::instance();
201 if (!empty($this->courseid
)) {
202 $eventcontext = context_course
::instance($this->courseid
);
204 $eventcontext = context_system
::instance();
207 $event = \core\event\scale_deleted
::create(array(
208 'objectid' => $this->id
,
209 'context' => $eventcontext
212 if (parent
::delete($source)) {
213 $context = context_system
::instance();
214 $fs = get_file_storage();
215 $files = $fs->get_area_files($context->id
, 'grade', 'scale', $this->id
);
216 foreach ($files as $file) {
225 * Returns the most descriptive field for this object. This is a standard method used
226 * when we do not know the exact type of an object.
228 * @return string name
230 public function get_name() {
231 // Grade scales can be created at site or course context, so set the filter context appropriately.
232 $context = empty($this->courseid
) ? context_system
::instance() : context_course
::instance($this->courseid
);
233 return format_string($this->name
, false, ['context' => $context]);
237 * Loads the scale's items into the $scale_items array.
238 * There are three ways to achieve this:
239 * 1. No argument given: The $scale string is already loaded and exploded to an array of items.
240 * 2. A string is given: A comma-separated list of items is exploded into an array of items.
241 * 3. An array of items is given and saved directly as the array of items for this scale.
243 * @param mixed $items Could be null, a string or an array. The method behaves differently for each case.
244 * @return array The resulting array of scale items or null if the method failed to produce one.
246 public function load_items($items=NULL) {
248 $this->scale_items
= explode(',', $this->scale
);
249 } elseif (is_array($items)) {
250 $this->scale_items
= $items;
252 $this->scale_items
= explode(',', $items);
255 // Trim whitespace around each value
256 foreach ($this->scale_items
as $key => $val) {
257 $this->scale_items
[$key] = trim($val);
260 return $this->scale_items
;
264 * Compacts (implodes) the array of items in $scale_items into a comma-separated string, $scale.
265 * There are three ways to achieve this:
266 * 1. No argument given: The $scale_items array is already loaded and imploded to a string of items.
267 * 2. An array is given and is imploded into a string of items.
268 * 3. A string of items is given and saved directly as the $scale variable.
269 * NOTE: This method is the exact reverse of load_items, and their input/output should be interchangeable. However,
270 * because load_items() trims the whitespace around the items, when the string is reconstructed these whitespaces will
271 * be missing. This is not an issue, but should be kept in mind when comparing the two strings.
273 * @param mixed $items Could be null, a string or an array. The method behaves differently for each case.
274 * @return array The resulting string of scale items or null if the method failed to produce one.
276 public function compact_items($items=NULL) {
278 $this->scale
= implode(',', $this->scale_items
);
279 } elseif (is_array($items)) {
280 $this->scale
= implode(',', $items);
282 $this->scale
= $items;
289 * When called on a loaded scale object (with a valid id) and given a float grade between
290 * the grademin and grademax, this method returns the scale item that falls closest to the
291 * float given (which is usually an average of several grades on a scale). If the float falls
292 * below 1 but above 0, it will be rounded up to 1.
294 * @param float $grade
297 public function get_nearest_item($grade) {
299 // Obtain nearest scale item from average
300 $scales_array = $DB->get_records('scale', array('id' => $this->id
));
301 $scale = $scales_array[$this->id
];
302 $scales = explode(",", $scale->scale
);
304 // this could be a 0 when summed and rounded, e.g, 1, no grade, no grade, no grade
309 return $scales[$grade-1];
313 * Static function returning all global scales
317 public static function fetch_all_global() {
318 return grade_scale
::fetch_all(array('courseid'=>0));
322 * Static function returning all local course scales
324 * @param int $courseid The course ID
325 * @return array Returns an array of grade_scale instances
327 public static function fetch_all_local($courseid) {
328 return grade_scale
::fetch_all(array('courseid'=>$courseid));
332 * Checks if this is the last scale on the site.
336 public function is_last_global_scale() {
337 return ($this->courseid
== 0) && (count(self
::fetch_all_global()) == 1);
341 * Checks if scale can be deleted.
345 public function can_delete() {
346 return !$this->is_used() && !$this->is_last_global_scale();
350 * Returns if scale used anywhere - activities, grade items, outcomes, etc.
354 public function is_used() {
358 // count grade items excluding the
359 $params = array($this->id
);
360 $sql = "SELECT COUNT(id) FROM {grade_items} WHERE scaleid = ? AND outcomeid IS NULL";
361 if ($DB->count_records_sql($sql, $params)) {
366 $sql = "SELECT COUNT(id) FROM {grade_outcomes} WHERE scaleid = ?";
367 if ($DB->count_records_sql($sql, $params)) {
371 // Ask the competency subsystem.
372 if (\core_competency\api
::is_scale_used_anywhere($this->id
)) {
376 // Ask all plugins if the scale is used anywhere.
377 $pluginsfunction = get_plugins_with_function('scale_used_anywhere');
378 foreach ($pluginsfunction as $plugintype => $plugins) {
379 foreach ($plugins as $pluginfunction) {
380 if ($pluginfunction($this->id
)) {
390 * Returns the formatted grade description with URLs converted
394 public function get_description() {
396 require_once($CFG->libdir
. '/filelib.php');
398 $systemcontext = context_system
::instance();
399 $options = new stdClass
;
400 $options->noclean
= true;
401 $description = file_rewrite_pluginfile_urls($this->description
, 'pluginfile.php', $systemcontext->id
, 'grade', 'scale', $this->id
);
402 return format_text($description, $this->descriptionformat
, $options);