lib/grade/grade_grade.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 class grade_grade extends grade_object {
  29
  30     /**
  31      * The DB table.
  32      * @var string $table
  33      */
  34     var $table = 'grade_grades';
  35
  36     /**
  37      * Array of class variables that are not part of the DB table fields
  38      * @var array $nonfields
  39      */
  40     var $nonfields = array('table', 'nonfields', 'required_fields', 'grade_grade_text', 'grade_item');
  41
  42     /**
  43      * The id of the grade_item this grade belongs to.
  44      * @var int $itemid
  45      */
  46     var $itemid;
  47
  48     /**
  49      * The grade_item object referenced by $this->itemid.
  50      * @var object $grade_item
  51      */
  52     var $grade_item;
  53
  54     /**
  55      * The id of the user this grade belongs to.
  56      * @var int $userid
  57      */
  58     var $userid;
  59
  60     /**
  61      * The grade value of this raw grade, if such was provided by the module.
  62      * @var float $rawgrade
  63      */
  64     var $rawgrade;
  65
  66     /**
  67      * The maximum allowable grade when this grade was created.
  68      * @var float $rawgrademax
  69      */
  70     var $rawgrademax = 100;
  71
  72     /**
  73      * The minimum allowable grade when this grade was created.
  74      * @var float $rawgrademin
  75      */
  76     var $rawgrademin = 0;
  77
  78     /**
  79      * id of the scale, if this grade is based on a scale.
  80      * @var int $rawscaleid
  81      */
  82     var $rawscaleid;
  83
  84     /**
  85      * The userid of the person who last modified this grade.
  86      * @var int $usermodified
  87      */
  88     var $usermodified;
  89
  90     /**
  91      * Additional textual information about this grade. It can be automatically generated
  92      * from the module or entered manually by the teacher. This is kept in its own table
  93      * for efficiency reasons, so it is encapsulated in its own object, and included in this grade object.
  94      * @var object $grade_grade_text
  95      */
  96     var $grade_grade_text;
  97
  98     /**
  99      * The final value of this grade.
 100      * @var float $finalgrade
 101      */
 102     var $finalgrade;
 103
 104     /**
 105      * 0 if visible, 1 always hidden or date not visible until
 106      * @var float $hidden
 107      */
 108     var $hidden = 0;
 109
 110     /**
 111      * 0 not locked, date when the item was locked
 112      * @var float locked
 113      */
 114     var $locked = 0;
 115
 116     /**
 117      * 0 no automatic locking, date when to lock the grade automatically
 118      * @var float $locktime
 119      */
 120     var $locktime = 0;
 121
 122     /**
 123      * Exported flag
 124      * @var boolean $exported
 125      */
 126     var $exported = 0;
 127
 128     /**
 129      * Overridden flag
 130      * @var boolean $overridden
 131      */
 132     var $overridden = 0;
 133
 134     /**
 135      * Grade excluded from aggregation functions
 136      * @var boolean $excluded
 137      */
 138     var $excluded = 0;
 139
 140     /**
 141      * Loads the grade_grade_text object linked to this grade (through the intersection of itemid and userid), and
 142      * saves it as a class variable for this final object.
 143      * @return object
 144      */
 145     function load_text() {
 146         if (empty($this->id)) {
 147             return false; // text can not be attached to non existing grade
 148         }
 149
 150         if (empty($this->grade_grade_text->id)) {
 151             $this->grade_grade_text = grade_grade_text::fetch(array('gradeid'=>$this->id));
 152         }
 153
 154         return $this->grade_grade_text;
 155     }
 156
 157     /**
 158      * Loads the grade_item object referenced by $this->itemid and saves it as $this->grade_item for easy access.
 159      * @param object $grade_item An optional grade_item given to avoid having to reload one from the DB
 160      * @return object grade_item.
 161      */
 162     function load_grade_item($grade_item=null) {
 163         if (!empty($grade_item) && get_class($grade_item) == 'grade_item') {
 164             $this->grade_item = $grade_item;
 165         } elseif (empty($this->grade_item) && !empty($this->itemid)) {
 166             $this->grade_item = grade_item::fetch(array('id'=>$this->itemid));
 167         }
 168         return $this->grade_item;
 169     }
 170
 171     /**
 172      * Is grading object editable?
 173      * @param object $grade_item An optional grade_item given to avoid having to reload one from the DB
 174      * @return boolean
 175      */
 176     function is_editable($grade_item=null) {
 177         if ($this->is_locked($grade_item)) {
 178             return false;
 179         }
 180
 181         $grade_item = $this->load_grade_item($grade_item);
 182
 183         if ($grade_item->gradetype == GRADE_TYPE_NONE) {
 184             return false;
 185         }
 186
 187         return true;
 188     }
 189
 190     /**
 191      * Check grade lock status. Uses both grade item lock and grade lock.
 192      * Internally any date in locked field (including future ones) means locked,
 193      * the date is stored for logging purposes only.
 194      *
 195      * @param object $grade_item An optional grade_item given to avoid having to reload one from the DB
 196      * @return boolean true if locked, false if not
 197      */
 198     function is_locked($grade_item=null) {
 199         $this->load_grade_item($grade_item);
 200
 201         return !empty($this->locked) or $this->grade_item->is_locked();
 202     }
 203
 204     /**
 205      * Checks if grade overridden
 206      * @return boolean
 207      */
 208     function is_overridden() {
 209         return !empty($this->overridden);
 210     }
 211
 212     /**
 213      * Set the overridden status of grade
 214      * @param boolean $state requested overridden state
 215      * @return boolean true is db state changed
 216      */
 217     function set_overridden($state) {
 218         if (empty($this->overridden) and $state) {
 219             $this->overridden = time();
 220             $this->update();
 221             return true;
 222
 223         } else if (!empty($this->overridden) and !$state) {
 224             $this->overridden = 0;
 225             $this->update();
 226             return true;
 227         }
 228         return false;
 229     }
 230
 231     /**
 232      * Checks if grade excluded from aggregation functions
 233      * @return boolean
 234      */
 235     function is_excluded() {
 236         return !empty($this->excluded);
 237     }
 238
 239     /**
 240      * Set the excluded status of grade
 241      * @param boolean $state requested excluded state
 242      * @return boolean true is db state changed
 243      */
 244     function set_excluded($state) {
 245         if (empty($this->excluded) and $state) {
 246             $this->excluded = time();
 247             $this->update();
 248             return true;
 249
 250         } else if (!empty($this->excluded) and !$state) {
 251             $this->excluded = 0;
 252             $this->update();
 253             return true;
 254         }
 255         return false;
 256     }
 257
 258     /**
 259      * Lock/unlock this grade.
 260      *
 261      * @param boolean $lockstate true means lock, false unlock grade
 262      * @return boolean true if sucessful, false if can not set new lock state for grade
 263      */
 264     function set_locked($lockedstate) {
 265         $this->load_grade_item();
 266
 267         if ($lockedstate) {
 268             if (!empty($this->locked)) {
 269                 return true; // already locked
 270             }
 271
 272             if ($this->grade_item->needsupdate) {
 273                 //can not lock grade if final not calculated!
 274                 return false;
 275             }
 276
 277             $this->locked = time();
 278             $this->update();
 279
 280             return true;
 281
 282         } else {
 283             if (empty($this->locked)) {
 284                 return true; // not locked
 285             }
 286
 287             if ($this->grade_item->is_locked()) {
 288                 return false;
 289             }
 290
 291             // remove the locked flag
 292             $this->locked = 0;
 293
 294             $this->update();
 295
 296             return true;
 297         }
 298     }
 299
 300
 301     /**
 302      * Set the locktime for this grade.
 303      *
 304      * @param int $locktime timestamp for lock to activate
 305      * @return boolean true if sucessful, false if can not set new lock state for grade
 306      */
 307     function set_locktime($locktime) {
 308
 309         if ($locktime) {
 310             // if current locktime is before, no need to reset
 311
 312             if ($this->locktime && $this->locktime <= $locktime) {
 313                 return true;
 314             }
 315
 316             /*
 317             if ($this->grade_item->needsupdate) {
 318                 //can not lock grade if final not calculated!
 319                 return false;
 320             }
 321             */
 322
 323             $this->locktime = $locktime;
 324             $this->update();
 325
 326             return true;
 327
 328         } else {
 329
 330             // remove the locktime timestamp
 331             $this->locktime = 0;
 332
 333             $this->update();
 334
 335             return true;
 336         }
 337     }
 338
 339     /**
 340      * Check grade lock status. Uses both grade item lock and grade lock.
 341      * Internally any date in hidden field (including future ones) means hidden,
 342      * the date is stored for logging purposes only.
 343      *
 344      * @param object $grade_item An optional grade_item given to avoid having to reload one from the DB
 345      * @return boolean true if hidden, false if not
 346      */
 347     function is_hidden($grade_item=null) {
 348         $this->load_grade_item($grade_item);
 349
 350         return $this->hidden == 1 or $this->hidden > time() or $this->grade_item->is_hidden();
 351     }
 352
 353     /**
 354      * Set the hidden status of grade, 0 mean visible, 1 always hidden, number means date to hide until.
 355      * @param int $hidden new hidden status
 356      */
 357     function set_hidden($hidden) {
 358        $this->hidden = $hidden;
 359        $this->update();
 360     }
 361
 362     /**
 363      * Finds and returns a grade_grade instance based on params.
 364      * @static
 365      *
 366      * @param array $params associative arrays varname=>value
 367      * @return object grade_grade instance or false if none found.
 368      */
 369     function fetch($params) {
 370         return grade_object::fetch_helper('grade_grades', 'grade_grade', $params);
 371     }
 372
 373     /**
 374      * Finds and returns all grade_grade instances based on params.
 375      * @static
 376      *
 377      * @param array $params associative arrays varname=>value
 378      * @return array array of grade_grade insatnces or false if none found.
 379      */
 380     function fetch_all($params) {
 381         return grade_object::fetch_all_helper('grade_grades', 'grade_grade', $params);
 382     }
 383
 384
 385     /**
 386      * Delete grade together with feedback.
 387      * @param string $source from where was the object deleted (mod/forum, manual, etc.)
 388      * @return boolean success
 389      */
 390     function delete($source=null) {
 391         if ($text = $this->load_text()) {
 392             $text->delete($source);
 393         }
 394         return parent::delete($source);
 395     }
 396
 397     /**
 398      * Updates this grade with the given textual information. This will create a new grade_grade_text entry
 399      * if none was previously in DB for this raw grade, or will update the existing one.
 400      * @param string $information Manual information from the teacher. Could be a code like 'mi'
 401      * @param int $informationformat Text format for the information
 402      * @return boolean Success or Failure
 403      */
 404     function update_information($information, $informationformat) {
 405         $this->load_text();
 406
 407         if (empty($this->grade_grade_text->id)) {
 408             $this->grade_grade_text = new grade_grade_text();
 409
 410             $this->grade_grade_text->gradeid           = $this->id;
 411             $this->grade_grade_text->userid            = $this->userid;
 412             $this->grade_grade_text->information       = $information;
 413             $this->grade_grade_text->informationformat = $informationformat;
 414
 415             return $this->grade_grade_text->insert();
 416
 417         } else {
 418             if ($this->grade_grade_text->information != $information
 419               or $this->grade_grade_text->informationformat != $informationformat) {
 420
 421                 $this->grade_grade_text->information       = $information;
 422                 $this->grade_grade_text->informationformat = $informationformat;
 423                 return  $this->grade_grade_text->update();
 424             } else {
 425                 return true;
 426             }
 427         }
 428     }
 429
 430     /**
 431      * Updates this grade with the given textual information. This will create a new grade_grade_text entry
 432      * if none was previously in DB for this raw grade, or will update the existing one.
 433      * @param string $feedback Manual feedback from the teacher. Could be a code like 'mi'
 434      * @param int $feedbackformat Text format for the feedback
 435      * @return boolean Success or Failure
 436      */
 437     function update_feedback($feedback, $feedbackformat, $usermodified=null) {
 438         global $USER;
 439
 440         $this->load_text();
 441
 442         if (empty($usermodified)) {
 443             $usermodified = $USER->id;
 444         }
 445
 446         if (empty($this->grade_grade_text->id)) {
 447             $this->grade_grade_text = new grade_grade_text();
 448
 449             $this->grade_grade_text->gradeid        = $this->id;
 450             $this->grade_grade_text->feedback       = $feedback;
 451             $this->grade_grade_text->feedbackformat = $feedbackformat;
 452             $this->grade_grade_text->usermodified   = $usermodified;
 453
 454             return $this->grade_grade_text->insert();
 455
 456         } else {
 457             if ($this->grade_grade_text->feedback != $feedback
 458               or $this->grade_grade_text->feedbackformat != $feedbackformat) {
 459
 460                 $this->grade_grade_text->feedback       = $feedback;
 461                 $this->grade_grade_text->feedbackformat = $feedbackformat;
 462                 $this->grade_grade_text->usermodified   = $usermodified;
 463
 464                 return  $this->grade_grade_text->update();
 465             } else {
 466                 return true;
 467             }
 468         }
 469     }
 470
 471     /**
 472      * Given a float value situated between a source minimum and a source maximum, converts it to the
 473      * corresponding value situated between a target minimum and a target maximum. Thanks to Darlene
 474      * for the formula :-)
 475      *
 476      * @static
 477      * @param float $rawgrade
 478      * @param float $source_min
 479      * @param float $source_max
 480      * @param float $target_min
 481      * @param float $target_max
 482      * @return float Converted value
 483      */
 484     function standardise_score($rawgrade, $source_min, $source_max, $target_min, $target_max) {
 485         if (is_null($rawgrade)) {
 486           return null;
 487         }
 488
 489         $factor = ($rawgrade - $source_min) / ($source_max - $source_min);
 490         $diff = $target_max - $target_min;
 491         $standardised_value = $factor * $diff + $target_min;
 492         return $standardised_value;
 493     }
 494
 495     /**
 496      * Returns the grade letter this grade falls under, as they are set up in the given array.
 497      * @param array $letters An array of grade boundaries with associated letters
 498      * @param float $gradevalue The value to convert. If not given, will use instantiated object
 499      * @param float $grademin If not given, will look up the grade_item's grademin
 500      * @param float $grademax If not given, will look up the grade_item's grademax
 501      * @return string Grade letter
 502      */
 503     function get_letter($letters, $gradevalue=null, $grademin=null, $grademax=null) {
 504         if (is_null($grademin) || is_null($grademax)) {
 505             if (!isset($this)) {
 506                 debugging("Tried to call grade_grade::get_letter statically without giving an explicit grademin or grademax!");
 507                 return false;
 508             }
 509             $this->load_grade_item();
 510             $grademin = $this->grade_item->grademin;
 511             $grademax = $this->grade_item->grademax;
 512         }
 513
 514         if (is_null($gradevalue)) {
 515             if (!isset($this)) {
 516                 debugging("Tried to call grade_grade::get_letter statically without giving an explicit gradevalue!");
 517                 return false;
 518             }
 519             $gradevalue = $this->finalgrade;
 520         }
 521         // Standardise grade first
 522         $grade = grade_grade::standardise_score($gradevalue, $grademin, $grademax, 0, 100);
 523
 524         // Sort the letters by descending boundaries (100-0)
 525         krsort($letters);
 526         foreach ($letters as $boundary => $letter) {
 527             if ($grade >= $boundary) {
 528                 return $letter;
 529             }
 530         }
 531         return '-';
 532     }
 533
 534 }
 535
 536 ?>