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      * @return object grade_item.
 160      */
 161     function load_grade_item() {
 162         if (empty($this->itemid)) {
 163             debugging('Missing itemid');
 164             $this->grade_item = null;
 165             return null;
 166         }
 167
 168         if (empty($this->grade_item)) {
 169             $this->grade_item = grade_item::fetch(array('id'=>$this->itemid));
 170
 171         } else if ($this->grade_item->id != $this->itemid) {
 172             debugging('Itemid mismatch');
 173             $this->grade_item = grade_item::fetch(array('id'=>$this->itemid));
 174         }
 175
 176         return $this->grade_item;
 177     }
 178
 179     /**
 180      * Is grading object editable?
 181      * @return boolean
 182      */
 183     function is_editable() {
 184         if ($this->is_locked()) {
 185             return false;
 186         }
 187
 188         $grade_item = $this->load_grade_item();
 189
 190         if ($grade_item->gradetype == GRADE_TYPE_NONE) {
 191             return false;
 192         }
 193
 194         return true;
 195     }
 196
 197     /**
 198      * Check grade lock status. Uses both grade item lock and grade lock.
 199      * Internally any date in locked field (including future ones) means locked,
 200      * the date is stored for logging purposes only.
 201      *
 202      * @return boolean true if locked, false if not
 203      */
 204     function is_locked() {
 205         $this->load_grade_item();
 206
 207         return !empty($this->locked) or $this->grade_item->is_locked();
 208     }
 209
 210     /**
 211      * Checks if grade overridden
 212      * @return boolean
 213      */
 214     function is_overridden() {
 215         return !empty($this->overridden);
 216     }
 217
 218     /**
 219      * Set the overridden status of grade
 220      * @param boolean $state requested overridden state
 221      * @return boolean true is db state changed
 222      */
 223     function set_overridden($state) {
 224         if (empty($this->overridden) and $state) {
 225             $this->overridden = time();
 226             $this->update();
 227             return true;
 228
 229         } else if (!empty($this->overridden) and !$state) {
 230             $this->overridden = 0;
 231             $this->update();
 232             return true;
 233         }
 234         return false;
 235     }
 236
 237     /**
 238      * Checks if grade excluded from aggregation functions
 239      * @return boolean
 240      */
 241     function is_excluded() {
 242         return !empty($this->excluded);
 243     }
 244
 245     /**
 246      * Set the excluded status of grade
 247      * @param boolean $state requested excluded state
 248      * @return boolean true is db state changed
 249      */
 250     function set_excluded($state) {
 251         if (empty($this->excluded) and $state) {
 252             $this->excluded = time();
 253             $this->update();
 254             return true;
 255
 256         } else if (!empty($this->excluded) and !$state) {
 257             $this->excluded = 0;
 258             $this->update();
 259             return true;
 260         }
 261         return false;
 262     }
 263
 264     /**
 265      * Lock/unlock this grade.
 266      *
 267      * @param int $locked 0, 1 or a timestamp int(10) after which date the item will be locked.
 268      * @param boolean $cascade ignored param
 269      * @param boolean $refresh refresh grades when unlocking
 270      * @return boolean true if sucessful, false if can not set new lock state for grade
 271      */
 272     function set_locked($lockedstate, $cascade=false, $refresh=true) {
 273         $this->load_grade_item();
 274
 275         if ($lockedstate) {
 276             if ($this->grade_item->needsupdate) {
 277                 //can not lock grade if final not calculated!
 278                 return false;
 279             }
 280
 281             $this->locked = time();
 282             $this->update();
 283
 284             return true;
 285
 286         } else {
 287             if (!empty($this->locked) and $this->locktime < time()) {
 288                 //we have to reset locktime or else it would lock up again
 289                 $this->locktime = 0;
 290             }
 291
 292             // remove the locked flag
 293             $this->locked = 0;
 294             $this->update();
 295
 296             if ($refresh) {
 297                 //refresh when unlocking
 298                 $this->grade_item->refresh_grades($this->userid);
 299             }
 300
 301             return true;
 302         }
 303     }
 304
 305     /**
 306      * Lock the grade if needed - make sure this is called only when final grades are valid
 307      * @param array $items array of all grade item ids
 308      * @return void
 309      */
 310     function check_locktime_all($items) {
 311         global $CFG;
 312
 313         $items_sql = implode(',', $items);
 314
 315         $now = time(); // no rounding needed, this is not supposed to be called every 10 seconds
 316
 317         if ($rs = get_recordset_select('grade_grades', "itemid IN ($items_sql) AND locked = 0 AND locktime > 0 AND locktime < $now")) {
 318             if ($rs->RecordCount() > 0) {
 319                 while ($grade = rs_fetch_next_record($rs)) {
 320                     $grade_grade = new grade_grade($grade, false);
 321                     $grade_grade->locked = time();
 322                     $grade_grade->update('locktime');
 323                 }
 324             }
 325             rs_close($rs);
 326         }
 327     }
 328
 329     /**
 330      * Set the locktime for this grade.
 331      *
 332      * @param int $locktime timestamp for lock to activate
 333      * @return void
 334      */
 335     function set_locktime($locktime) {
 336         $this->locktime = $locktime;
 337         $this->update();
 338     }
 339
 340     /**
 341      * Set the locktime for this grade.
 342      *
 343      * @return int $locktime timestamp for lock to activate
 344      */
 345     function get_locktime() {
 346         $this->load_grade_item();
 347
 348         $item_locktime = $this->grade_item->get_locktime();
 349
 350         if (empty($this->locktime) or ($item_locktime and $item_locktime < $this->locktime)) {
 351             return $item_locktime;
 352
 353         } else {
 354             return $this->locktime;
 355         }
 356     }
 357
 358     /**
 359      * Check grade hidden status. Uses data from both grade item and grade.
 360      * @return boolean true if hidden, false if not
 361      */
 362     function is_hidden() {
 363         $this->load_grade_item();
 364
 365         return $this->hidden == 1 or ($this->hidden != 0 and $this->hidden > time()) or $this->grade_item->is_hidden();
 366     }
 367
 368     /**
 369      * Check grade hidden status. Uses data from both grade item and grade.
 370      * @return int 0 means visible, 1 hidden always, timestamp hidden until
 371      */
 372     function get_hidden() {
 373         $this->load_grade_item();
 374
 375         $item_hidden = $this->grade_item->get_hidden();
 376
 377         if ($item_hidden == 1) {
 378             return 1;
 379
 380         } else if ($item_hidden == 0) {
 381             return $this->hidden;
 382
 383         } else {
 384             if ($this->hidden == 0) {
 385                 return $item_hidden;
 386             } else if ($this->hidden == 1) {
 387                 return 1;
 388             } else if ($this->hidden > $item_hidden) {
 389                 return $this->hidden;
 390             } else {
 391                 return $item_hidden;
 392             }
 393         }
 394     }
 395
 396     /**
 397      * Set the hidden status of grade, 0 mean visible, 1 always hidden, number means date to hide until.
 398      * @param boolean $cascade ignored
 399      * @param int $hidden new hidden status
 400      */
 401     function set_hidden($hidden, $cascade=false) {
 402        $this->hidden = $hidden;
 403        $this->update();
 404     }
 405
 406     /**
 407      * Finds and returns a grade_grade instance based on params.
 408      * @static
 409      *
 410      * @param array $params associative arrays varname=>value
 411      * @return object grade_grade instance or false if none found.
 412      */
 413     function fetch($params) {
 414         return grade_object::fetch_helper('grade_grades', 'grade_grade', $params);
 415     }
 416
 417     /**
 418      * Finds and returns all grade_grade instances based on params.
 419      * @static
 420      *
 421      * @param array $params associative arrays varname=>value
 422      * @return array array of grade_grade insatnces or false if none found.
 423      */
 424     function fetch_all($params) {
 425         return grade_object::fetch_all_helper('grade_grades', 'grade_grade', $params);
 426     }
 427
 428
 429     /**
 430      * Delete grade together with feedback.
 431      * @param string $source from where was the object deleted (mod/forum, manual, etc.)
 432      * @return boolean success
 433      */
 434     function delete($source=null) {
 435         if ($text = $this->load_text()) {
 436             $text->delete($source);
 437         }
 438         return parent::delete($source);
 439     }
 440
 441     /**
 442      * Updates this grade with the given textual information. This will create a new grade_grade_text entry
 443      * if none was previously in DB for this raw grade, or will update the existing one.
 444      * @param string $information Manual information from the teacher. Could be a code like 'mi'
 445      * @param int $informationformat Text format for the information
 446      * @return boolean Success or Failure
 447      */
 448     function update_information($information, $informationformat) {
 449         $this->load_text();
 450
 451         if (empty($this->grade_grade_text->id)) {
 452             $this->grade_grade_text = new grade_grade_text();
 453
 454             $this->grade_grade_text->gradeid           = $this->id;
 455             $this->grade_grade_text->userid            = $this->userid;
 456             $this->grade_grade_text->information       = $information;
 457             $this->grade_grade_text->informationformat = $informationformat;
 458
 459             return $this->grade_grade_text->insert();
 460
 461         } else {
 462             if ($this->grade_grade_text->information != $information
 463               or $this->grade_grade_text->informationformat != $informationformat) {
 464
 465                 $this->grade_grade_text->information       = $information;
 466                 $this->grade_grade_text->informationformat = $informationformat;
 467                 return  $this->grade_grade_text->update();
 468             } else {
 469                 return true;
 470             }
 471         }
 472     }
 473
 474     /**
 475      * Updates this grade with the given textual information. This will create a new grade_grade_text entry
 476      * if none was previously in DB for this raw grade, or will update the existing one.
 477      * @param string $feedback Manual feedback from the teacher. Could be a code like 'mi'
 478      * @param int $feedbackformat Text format for the feedback
 479      * @return boolean Success or Failure
 480      */
 481     function update_feedback($feedback, $feedbackformat, $usermodified=null) {
 482         global $USER;
 483
 484         $this->load_text();
 485
 486         if (empty($usermodified)) {
 487             $usermodified = $USER->id;
 488         }
 489
 490         if (empty($this->grade_grade_text->id)) {
 491             $this->grade_grade_text = new grade_grade_text();
 492
 493             $this->grade_grade_text->gradeid        = $this->id;
 494             $this->grade_grade_text->feedback       = $feedback;
 495             $this->grade_grade_text->feedbackformat = $feedbackformat;
 496             $this->grade_grade_text->usermodified   = $usermodified;
 497
 498             return $this->grade_grade_text->insert();
 499
 500         } else {
 501             if ($this->grade_grade_text->feedback != $feedback
 502               or $this->grade_grade_text->feedbackformat != $feedbackformat) {
 503
 504                 $this->grade_grade_text->feedback       = $feedback;
 505                 $this->grade_grade_text->feedbackformat = $feedbackformat;
 506                 $this->grade_grade_text->usermodified   = $usermodified;
 507
 508                 return  $this->grade_grade_text->update();
 509             } else {
 510                 return true;
 511             }
 512         }
 513     }
 514
 515     /**
 516      * Given a float value situated between a source minimum and a source maximum, converts it to the
 517      * corresponding value situated between a target minimum and a target maximum. Thanks to Darlene
 518      * for the formula :-)
 519      *
 520      * @static
 521      * @param float $rawgrade
 522      * @param float $source_min
 523      * @param float $source_max
 524      * @param float $target_min
 525      * @param float $target_max
 526      * @return float Converted value
 527      */
 528     function standardise_score($rawgrade, $source_min, $source_max, $target_min, $target_max) {
 529         if (is_null($rawgrade)) {
 530           return null;
 531         }
 532
 533         $factor = ($rawgrade - $source_min) / ($source_max - $source_min);
 534         $diff = $target_max - $target_min;
 535         $standardised_value = $factor * $diff + $target_min;
 536         return $standardised_value;
 537     }
 538
 539     /**
 540      * Returns the grade letter this grade falls under, as they are set up in the given array.
 541      * @param array $letters An array of grade boundaries with associated letters
 542      * @param float $gradevalue The value to convert. If not given, will use instantiated object
 543      * @param float $grademin If not given, will look up the grade_item's grademin
 544      * @param float $grademax If not given, will look up the grade_item's grademax
 545      * @return string Grade letter
 546      */
 547     function get_letter($letters, $gradevalue=null, $grademin=null, $grademax=null) {
 548         if (is_null($grademin) || is_null($grademax)) {
 549             if (!isset($this)) {
 550                 debugging("Tried to call grade_grade::get_letter statically without giving an explicit grademin or grademax!");
 551                 return false;
 552             }
 553             $this->load_grade_item();
 554             $grademin = $this->grade_item->grademin;
 555             $grademax = $this->grade_item->grademax;
 556         }
 557
 558         if (is_null($gradevalue)) {
 559             if (!isset($this)) {
 560                 debugging("Tried to call grade_grade::get_letter statically without giving an explicit gradevalue!");
 561                 return false;
 562             }
 563             $gradevalue = $this->finalgrade;
 564         }
 565         // Standardise grade first
 566         $grade = grade_grade::standardise_score($gradevalue, $grademin, $grademax, 0, 100);
 567
 568         // Sort the letters by descending boundaries (100-0)
 569         krsort($letters);
 570         foreach ($letters as $boundary => $letter) {
 571             if ($grade >= $boundary) {
 572                 return $letter;
 573             }
 574         }
 575         return '-';
 576     }
 577
 578 }
 579 ?>