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 lock status. Uses both grade item lock and grade lock.
 360      * Internally any date in hidden field (including future ones) means hidden,
 361      * the date is stored for logging purposes only.
 362      *
 363      * @param object $grade_item An optional grade_item given to avoid having to reload one from the DB
 364      * @return boolean true if hidden, false if not
 365      */
 366     function is_hidden($grade_item=null) {
 367         $this->load_grade_item($grade_item);
 368
 369         return $this->hidden == 1 or $this->hidden > time() or $this->grade_item->is_hidden();
 370     }
 371
 372     /**
 373      * Set the hidden status of grade, 0 mean visible, 1 always hidden, number means date to hide until.
 374      * @param int $hidden new hidden status
 375      */
 376     function set_hidden($hidden) {
 377        $this->hidden = $hidden;
 378        $this->update();
 379     }
 380
 381     /**
 382      * Finds and returns a grade_grade instance based on params.
 383      * @static
 384      *
 385      * @param array $params associative arrays varname=>value
 386      * @return object grade_grade instance or false if none found.
 387      */
 388     function fetch($params) {
 389         return grade_object::fetch_helper('grade_grades', 'grade_grade', $params);
 390     }
 391
 392     /**
 393      * Finds and returns all grade_grade instances based on params.
 394      * @static
 395      *
 396      * @param array $params associative arrays varname=>value
 397      * @return array array of grade_grade insatnces or false if none found.
 398      */
 399     function fetch_all($params) {
 400         return grade_object::fetch_all_helper('grade_grades', 'grade_grade', $params);
 401     }
 402
 403
 404     /**
 405      * Delete grade together with feedback.
 406      * @param string $source from where was the object deleted (mod/forum, manual, etc.)
 407      * @return boolean success
 408      */
 409     function delete($source=null) {
 410         if ($text = $this->load_text()) {
 411             $text->delete($source);
 412         }
 413         return parent::delete($source);
 414     }
 415
 416     /**
 417      * Updates this grade with the given textual information. This will create a new grade_grade_text entry
 418      * if none was previously in DB for this raw grade, or will update the existing one.
 419      * @param string $information Manual information from the teacher. Could be a code like 'mi'
 420      * @param int $informationformat Text format for the information
 421      * @return boolean Success or Failure
 422      */
 423     function update_information($information, $informationformat) {
 424         $this->load_text();
 425
 426         if (empty($this->grade_grade_text->id)) {
 427             $this->grade_grade_text = new grade_grade_text();
 428
 429             $this->grade_grade_text->gradeid           = $this->id;
 430             $this->grade_grade_text->userid            = $this->userid;
 431             $this->grade_grade_text->information       = $information;
 432             $this->grade_grade_text->informationformat = $informationformat;
 433
 434             return $this->grade_grade_text->insert();
 435
 436         } else {
 437             if ($this->grade_grade_text->information != $information
 438               or $this->grade_grade_text->informationformat != $informationformat) {
 439
 440                 $this->grade_grade_text->information       = $information;
 441                 $this->grade_grade_text->informationformat = $informationformat;
 442                 return  $this->grade_grade_text->update();
 443             } else {
 444                 return true;
 445             }
 446         }
 447     }
 448
 449     /**
 450      * Updates this grade with the given textual information. This will create a new grade_grade_text entry
 451      * if none was previously in DB for this raw grade, or will update the existing one.
 452      * @param string $feedback Manual feedback from the teacher. Could be a code like 'mi'
 453      * @param int $feedbackformat Text format for the feedback
 454      * @return boolean Success or Failure
 455      */
 456     function update_feedback($feedback, $feedbackformat, $usermodified=null) {
 457         global $USER;
 458
 459         $this->load_text();
 460
 461         if (empty($usermodified)) {
 462             $usermodified = $USER->id;
 463         }
 464
 465         if (empty($this->grade_grade_text->id)) {
 466             $this->grade_grade_text = new grade_grade_text();
 467
 468             $this->grade_grade_text->gradeid        = $this->id;
 469             $this->grade_grade_text->feedback       = $feedback;
 470             $this->grade_grade_text->feedbackformat = $feedbackformat;
 471             $this->grade_grade_text->usermodified   = $usermodified;
 472
 473             return $this->grade_grade_text->insert();
 474
 475         } else {
 476             if ($this->grade_grade_text->feedback != $feedback
 477               or $this->grade_grade_text->feedbackformat != $feedbackformat) {
 478
 479                 $this->grade_grade_text->feedback       = $feedback;
 480                 $this->grade_grade_text->feedbackformat = $feedbackformat;
 481                 $this->grade_grade_text->usermodified   = $usermodified;
 482
 483                 return  $this->grade_grade_text->update();
 484             } else {
 485                 return true;
 486             }
 487         }
 488     }
 489
 490     /**
 491      * Given a float value situated between a source minimum and a source maximum, converts it to the
 492      * corresponding value situated between a target minimum and a target maximum. Thanks to Darlene
 493      * for the formula :-)
 494      *
 495      * @static
 496      * @param float $rawgrade
 497      * @param float $source_min
 498      * @param float $source_max
 499      * @param float $target_min
 500      * @param float $target_max
 501      * @return float Converted value
 502      */
 503     function standardise_score($rawgrade, $source_min, $source_max, $target_min, $target_max) {
 504         if (is_null($rawgrade)) {
 505           return null;
 506         }
 507
 508         $factor = ($rawgrade - $source_min) / ($source_max - $source_min);
 509         $diff = $target_max - $target_min;
 510         $standardised_value = $factor * $diff + $target_min;
 511         return $standardised_value;
 512     }
 513
 514     /**
 515      * Returns the grade letter this grade falls under, as they are set up in the given array.
 516      * @param array $letters An array of grade boundaries with associated letters
 517      * @param float $gradevalue The value to convert. If not given, will use instantiated object
 518      * @param float $grademin If not given, will look up the grade_item's grademin
 519      * @param float $grademax If not given, will look up the grade_item's grademax
 520      * @return string Grade letter
 521      */
 522     function get_letter($letters, $gradevalue=null, $grademin=null, $grademax=null) {
 523         if (is_null($grademin) || is_null($grademax)) {
 524             if (!isset($this)) {
 525                 debugging("Tried to call grade_grade::get_letter statically without giving an explicit grademin or grademax!");
 526                 return false;
 527             }
 528             $this->load_grade_item();
 529             $grademin = $this->grade_item->grademin;
 530             $grademax = $this->grade_item->grademax;
 531         }
 532
 533         if (is_null($gradevalue)) {
 534             if (!isset($this)) {
 535                 debugging("Tried to call grade_grade::get_letter statically without giving an explicit gradevalue!");
 536                 return false;
 537             }
 538             $gradevalue = $this->finalgrade;
 539         }
 540         // Standardise grade first
 541         $grade = grade_grade::standardise_score($gradevalue, $grademin, $grademax, 0, 100);
 542
 543         // Sort the letters by descending boundaries (100-0)
 544         krsort($letters);
 545         foreach ($letters as $boundary => $letter) {
 546             if ($grade >= $boundary) {
 547                 return $letter;
 548             }
 549         }
 550         return '-';
 551     }
 552
 553 }
 554
 555 ?>