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 class variables that are not part of the DB table fields
  41      * @var array $nonfields
  42      */
  43     var $nonfields = array('table', 'nonfields', 'required_fields', 'scale_items');
  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      * Loads the scale's items into the $scale_items array.
 101      * There are three ways to achieve this:
 102      * 1. No argument given: The $scale string is already loaded and exploded to an array of items.
 103      * 2. A string is given: A comma-separated list of items is exploded into an array of items.
 104      * 3. An array of items is given and saved directly as the array of items for this scale.
 105      *
 106      * @param mixed $items Could be null, a string or an array. The method behaves differently for each case.
 107      * @return array The resulting array of scale items or null if the method failed to produce one.
 108      */
 109     function load_items($items=NULL) {
 110         if (empty($items)) {
 111             $this->scale_items = explode(',', $this->scale);
 112         } elseif (is_array($items)) {
 113             $this->scale_items = $items;
 114         } else {
 115             $this->scale_items = explode(',', $items);
 116         }
 117
 118         // Trim whitespace around each value
 119         foreach ($this->scale_items as $key => $val) {
 120             $this->scale_items[$key] = trim($val);
 121         }
 122
 123         return $this->scale_items;
 124     }
 125
 126     /**
 127      * Compacts (implodes) the array of items in $scale_items into a comma-separated string, $scale.
 128      * There are three ways to achieve this:
 129      * 1. No argument given: The $scale_items array is already loaded and imploded to a string of items.
 130      * 2. An array is given and is imploded into a string of items.
 131      * 3. A string of items is given and saved directly as the $scale variable.
 132      * NOTE: This method is the exact reverse of load_items, and their input/output should be interchangeable. However,
 133      * because load_items() trims the whitespace around the items, when the string is reconstructed these whitespaces will
 134      * be missing. This is not an issue, but should be kept in mind when comparing the two strings.
 135      *
 136      * @param mixed $items Could be null, a string or an array. The method behaves differently for each case.
 137      * @return array The resulting string of scale items or null if the method failed to produce one.
 138      */
 139     function compact_items($items=NULL) {
 140         if (empty($items)) {
 141             $this->scale = implode(',', $this->scale_items);
 142         } elseif (is_array($items)) {
 143             $this->scale = implode(',', $items);
 144         } else {
 145             $this->scale = $items;
 146         }
 147
 148         return $this->scale;
 149     }
 150
 151     /**
 152      * When called on a loaded scale object (with a valid id) and given a float grade between
 153      * the grademin and grademax, this method returns the scale item that falls closest to the
 154      * float given (which is usually an average of several grades on a scale). If the float falls
 155      * below 1 but above 0, it will be rounded up to 1.
 156      * @param float $grade
 157      * @return string
 158      */
 159     function get_nearest_item($grade) {
 160         // Obtain nearest scale item from average
 161         $scales_array = get_records_list('scale', 'id', $this->id);
 162         $scale = $scales_array[$this->id];
 163         $scales = explode(",", $scale->scale);
 164
 165         // this could be a 0 when summed and rounded, e.g, 1, no grade, no grade, no grade
 166         if ($grade < 1) {
 167             $grade = 1;
 168         }
 169
 170         return $scales[$grade-1];
 171     }
 172 }
 173 ?>