grade/grading/form/rubric/lib.php

   1 <?php
   2
   3 // This file is part of Moodle - http://moodle.org/
   4 //
   5 // Moodle is free software: you can redistribute it and/or modify
   6 // it under the terms of the GNU General Public License as published by
   7 // the Free Software Foundation, either version 3 of the License, or
   8 // (at your option) any later version.
   9 //
  10 // Moodle is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 // GNU General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU General Public License
  16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  17
  18 /**
  19  * Grading method controller for the Rubric plugin
  20  *
  21  * @package    gradingform
  22  * @subpackage rubric
  23  * @copyright  2011 David Mudrak <david@moodle.com>
  24  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  25  */
  26
  27 defined('MOODLE_INTERNAL') || die();
  28
  29 require_once($CFG->dirroot.'/grade/grading/form/lib.php');
  30
  31 /**
  32  * This controller encapsulates the rubric grading logic
  33  */
  34 class gradingform_rubric_controller extends gradingform_controller {
  35     // Modes of displaying the rubric (used in gradingform_rubric_renderer)
  36     /** Rubric display mode: For editing (moderator or teacher creates a rubric) */
  37     const DISPLAY_EDIT_FULL     = 1;
  38     /** Rubric display mode: Preview the rubric design with hidden fields */
  39     const DISPLAY_EDIT_FROZEN   = 2;
  40     /** Rubric display mode: Preview the rubric design */
  41     const DISPLAY_PREVIEW       = 3;
  42     /** Rubric display mode: For evaluation, enabled (teacher grades a student) */
  43     const DISPLAY_EVAL          = 4;
  44     /** Rubric display mode: For evaluation, with hidden fields */
  45     const DISPLAY_EVAL_FROZEN   = 5;
  46     /** Rubric display mode: Teacher reviews filled rubric */
  47     const DISPLAY_REVIEW        = 6;
  48     /** Rubric display mode: Dispaly filled rubric (i.e. students see their grades) */
  49     const DISPLAY_VIEW          = 7;
  50
  51     /**
  52      * Extends the module settings navigation with the rubric grading settings
  53      *
  54      * This function is called when the context for the page is an activity module with the
  55      * FEATURE_ADVANCED_GRADING, the user has the permission moodle/grade:managegradingforms
  56      * and there is an area with the active grading method set to 'rubric'.
  57      *
  58      * @param settings_navigation $settingsnav {@link settings_navigation}
  59      * @param navigation_node $node {@link navigation_node}
  60      */
  61     public function extend_settings_navigation(settings_navigation $settingsnav, navigation_node $node=null) {
  62         $node->add(get_string('definerubric', 'gradingform_rubric'),
  63             $this->get_editor_url(), settings_navigation::TYPE_CUSTOM,
  64             null, null, new pix_icon('icon', '', 'gradingform_rubric'));
  65     }
  66
  67     /**
  68      * Saves the rubric definition into the database
  69      *
  70      * @see parent::update_definition()
  71      * @param stdClass $newdefinition rubric definition data as coming from gradingform_rubric_editrubric::get_data()
  72      * @param int|null $usermodified optional userid of the author of the definition, defaults to the current user
  73      */
  74     public function update_definition(stdClass $newdefinition, $usermodified = null) {
  75         $this->update_or_check_rubric($newdefinition, $usermodified, true);
  76         if (isset($newdefinition->rubric['regrade']) && $newdefinition->rubric['regrade']) {
  77             $this->mark_for_regrade();
  78         }
  79     }
  80
  81     /**
  82      * Either saves the rubric definition into the database or check if it has been changed.
  83      * Returns the level of changes:
  84      * 0 - no changes
  85      * 1 - only texts or criteria sortorders are changed, students probably do not require re-grading
  86      * 2 - added levels but maximum score on rubric is the same, students still may not require re-grading
  87      * 3 - removed criteria or added levels or changed number of points, students require re-grading but may be re-graded automatically
  88      * 4 - removed levels - students require re-grading and not all students may be re-graded automatically
  89      * 5 - added criteria - all students require manual re-grading
  90      *
  91      * @param stdClass $newdefinition rubric definition data as coming from gradingform_rubric_editrubric::get_data()
  92      * @param int|null $usermodified optional userid of the author of the definition, defaults to the current user
  93      * @param boolean $doupdate if true actually updates DB, otherwise performs a check
  94      *
  95      */
  96     public function update_or_check_rubric(stdClass $newdefinition, $usermodified = null, $doupdate = false) {
  97         global $DB;
  98
  99         // firstly update the common definition data in the {grading_definition} table
 100         if ($this->definition === false) {
 101             if (!$doupdate) {
 102                 // if we create the new definition there is no such thing as re-grading anyway
 103                 return 5;
 104             }
 105             // if definition does not exist yet, create a blank one
 106             // (we need id to save files embedded in description)
 107             parent::update_definition(new stdClass(), $usermodified);
 108             parent::load_definition();
 109         }
 110         if (!isset($newdefinition->rubric['options'])) {
 111             $newdefinition->rubric['options'] = self::get_default_options();
 112         }
 113         $newdefinition->options = json_encode($newdefinition->rubric['options']);
 114         $editoroptions = self::description_form_field_options($this->get_context());
 115         $newdefinition = file_postupdate_standard_editor($newdefinition, 'description', $editoroptions, $this->get_context(),
 116             'grading', 'description', $this->definition->id);
 117
 118         // reload the definition from the database
 119         $currentdefinition = $this->get_definition(true);
 120
 121         // update rubric data
 122         $haschanges = array();
 123         if (empty($newdefinition->rubric['criteria'])) {
 124             $newcriteria = array();
 125         } else {
 126             $newcriteria = $newdefinition->rubric['criteria']; // new ones to be saved
 127         }
 128         $currentcriteria = $currentdefinition->rubric_criteria;
 129         $criteriafields = array('sortorder', 'description', 'descriptionformat');
 130         $levelfields = array('score', 'definition', 'definitionformat');
 131         foreach ($newcriteria as $id => $criterion) {
 132             // get list of submitted levels
 133             $levelsdata = array();
 134             if (array_key_exists('levels', $criterion)) {
 135                 $levelsdata = $criterion['levels'];
 136             }
 137             $criterionmaxscore = null;
 138             if (preg_match('/^NEWID\d+$/', $id)) {
 139                 // insert criterion into DB
 140                 $data = array('definitionid' => $this->definition->id, 'descriptionformat' => FORMAT_MOODLE); // TODO format is not supported yet
 141                 foreach ($criteriafields as $key) {
 142                     if (array_key_exists($key, $criterion)) {
 143                         $data[$key] = $criterion[$key];
 144                     }
 145                 }
 146                 if ($doupdate) {
 147                     $id = $DB->insert_record('gradingform_rubric_criteria', $data);
 148                 }
 149                 $haschanges[5] = true;
 150             } else {
 151                 // update criterion in DB
 152                 $data = array();
 153                 foreach ($criteriafields as $key) {
 154                     if (array_key_exists($key, $criterion) && $criterion[$key] != $currentcriteria[$id][$key]) {
 155                         $data[$key] = $criterion[$key];
 156                     }
 157                 }
 158                 if (!empty($data)) {
 159                     // update only if something is changed
 160                     $data['id'] = $id;
 161                     if ($doupdate) {
 162                         $DB->update_record('gradingform_rubric_criteria', $data);
 163                     }
 164                     $haschanges[1] = true;
 165                 }
 166                 // remove deleted levels from DB and calculate the maximum score for this criteria
 167                 foreach ($currentcriteria[$id]['levels'] as $levelid => $currentlevel) {
 168                     if ($criterionmaxscore === null || $criterionmaxscore < $currentlevel['score']) {
 169                         $criterionmaxscore = $currentlevel['score'];
 170                     }
 171                     if (!array_key_exists($levelid, $levelsdata)) {
 172                         if ($doupdate) {
 173                             $DB->delete_records('gradingform_rubric_levels', array('id' => $levelid));
 174                         }
 175                         $haschanges[4] = true;
 176                     }
 177                 }
 178             }
 179             foreach ($levelsdata as $levelid => $level) {
 180                 if (isset($level['score'])) {
 181                     $level['score'] = (float)$level['score'];
 182                     if ($level['score']<0) {
 183                         // TODO why we can't allow negative score for rubric?
 184                         $level['score'] = 0;
 185                     }
 186                 }
 187                 if (preg_match('/^NEWID\d+$/', $levelid)) {
 188                     // insert level into DB
 189                     $data = array('criterionid' => $id, 'definitionformat' => FORMAT_MOODLE); // TODO format is not supported yet
 190                     foreach ($levelfields as $key) {
 191                         if (array_key_exists($key, $level)) {
 192                             $data[$key] = $level[$key];
 193                         }
 194                     }
 195                     if ($doupdate) {
 196                         $levelid = $DB->insert_record('gradingform_rubric_levels', $data);
 197                     }
 198                     if ($criterionmaxscore !== null && $criterionmaxscore >= $level['score']) {
 199                         // new level is added but the maximum score for this criteria did not change, re-grading may not be necessary
 200                         $haschanges[2] = true;
 201                     } else {
 202                         $haschanges[3] = true;
 203                     }
 204                 } else {
 205                     // update level in DB
 206                     $data = array();
 207                     foreach ($levelfields as $key) {
 208                         if (array_key_exists($key, $level) && $level[$key] != $currentcriteria[$id]['levels'][$levelid][$key]) {
 209                             $data[$key] = $level[$key];
 210                         }
 211                     }
 212                     if (!empty($data)) {
 213                         // update only if something is changed
 214                         $data['id'] = $levelid;
 215                         if ($doupdate) {
 216                             $DB->update_record('gradingform_rubric_levels', $data);
 217                         }
 218                         if (isset($data['score'])) {
 219                             $haschanges[3] = true;
 220                         }
 221                         $haschanges[1] = true;
 222                     }
 223                 }
 224             }
 225         }
 226         // remove deleted criteria from DB
 227         foreach (array_keys($currentcriteria) as $id) {
 228             if (!array_key_exists($id, $newcriteria)) {
 229                 if ($doupdate) {
 230                     $DB->delete_records('gradingform_rubric_criteria', array('id' => $id));
 231                     $DB->delete_records('gradingform_rubric_levels', array('criterionid' => $id));
 232                 }
 233                 $haschanges[3] = true;
 234             }
 235         }
 236         foreach (array('status', 'description', 'descriptionformat', 'name', 'options') as $key) {
 237             if (isset($newdefinition->$key) && $newdefinition->$key != $this->definition->$key) {
 238                 $haschanges[1] = true;
 239             }
 240         }
 241         if ($usermodified && $usermodified != $this->definition->usermodified) {
 242             $haschanges[1] = true;
 243         }
 244         if (!count($haschanges)) {
 245             return 0;
 246         }
 247         if ($doupdate) {
 248             parent::update_definition($newdefinition, $usermodified);
 249             $this->load_definition();
 250         }
 251         // return the maximum level of changes
 252         $changelevels = array_keys($haschanges);
 253         sort($changelevels);
 254         return array_pop($changelevels);
 255     }
 256
 257     /**
 258      * Marks all instances filled with this rubric with the status INSTANCE_STATUS_NEEDUPDATE
 259      */
 260     public function mark_for_regrade() {
 261         global $DB;
 262         if ($this->has_active_instances()) {
 263             $conditions = array('definitionid'  => $this->definition->id,
 264                         'status'  => gradingform_instance::INSTANCE_STATUS_ACTIVE);
 265             $DB->set_field('grading_instances', 'status', gradingform_instance::INSTANCE_STATUS_NEEDUPDATE, $conditions);
 266         }
 267     }
 268
 269     /**
 270      * Loads the rubric form definition if it exists
 271      *
 272      * There is a new array called 'rubric_criteria' appended to the list of parent's definition properties.
 273      */
 274     protected function load_definition() {
 275         global $DB;
 276         $sql = "SELECT gd.*,
 277                        rc.id AS rcid, rc.sortorder AS rcsortorder, rc.description AS rcdescription, rc.descriptionformat AS rcdescriptionformat,
 278                        rl.id AS rlid, rl.score AS rlscore, rl.definition AS rldefinition, rl.definitionformat AS rldefinitionformat
 279                   FROM {grading_definitions} gd
 280              LEFT JOIN {gradingform_rubric_criteria} rc ON (rc.definitionid = gd.id)
 281              LEFT JOIN {gradingform_rubric_levels} rl ON (rl.criterionid = rc.id)
 282                  WHERE gd.areaid = :areaid AND gd.method = :method
 283               ORDER BY rc.sortorder,rl.score";
 284         $params = array('areaid' => $this->areaid, 'method' => $this->get_method_name());
 285
 286         $rs = $DB->get_recordset_sql($sql, $params);
 287         $this->definition = false;
 288         foreach ($rs as $record) {
 289             // pick the common definition data
 290             if ($this->definition === false) {
 291                 $this->definition = new stdClass();
 292                 foreach (array('id', 'name', 'description', 'descriptionformat', 'status', 'copiedfromid',
 293                         'timecreated', 'usercreated', 'timemodified', 'usermodified', 'timecopied', 'options') as $fieldname) {
 294                     $this->definition->$fieldname = $record->$fieldname;
 295                 }
 296                 $this->definition->rubric_criteria = array();
 297             }
 298             // pick the criterion data
 299             if (!empty($record->rcid) and empty($this->definition->rubric_criteria[$record->rcid])) {
 300                 foreach (array('id', 'sortorder', 'description', 'descriptionformat') as $fieldname) {
 301                     $this->definition->rubric_criteria[$record->rcid][$fieldname] = $record->{'rc'.$fieldname};
 302                 }
 303                 $this->definition->rubric_criteria[$record->rcid]['levels'] = array();
 304             }
 305             // pick the level data
 306             if (!empty($record->rlid)) {
 307                 foreach (array('id', 'score', 'definition', 'definitionformat') as $fieldname) {
 308                     $value = $record->{'rl'.$fieldname};
 309                     if ($fieldname == 'score') {
 310                         $value = (float)$value; // To prevent display like 1.00000
 311                     }
 312                     $this->definition->rubric_criteria[$record->rcid]['levels'][$record->rlid][$fieldname] = $value;
 313                 }
 314             }
 315         }
 316         $rs->close();
 317         $options = $this->get_options();
 318         if (!$options['sortlevelsasc']) {
 319             foreach (array_keys($this->definition->rubric_criteria) as $rcid) {
 320                 $this->definition->rubric_criteria[$rcid]['levels'] = array_reverse($this->definition->rubric_criteria[$rcid]['levels'], true);
 321             }
 322         }
 323     }
 324
 325     /**
 326      * Returns the default options for the rubric display
 327      *
 328      * @return array
 329      */
 330     public static function get_default_options() {
 331         $options = array(
 332             'sortlevelsasc' => 1,
 333             //'showdescriptionteacher' => 1,
 334             //'showdescriptionstudent' => 1,
 335             'showscoreteacher' => 1,
 336             'showscorestudent' => 1,
 337             'enableremarks' => 1,
 338             'showremarksstudent' => 1
 339         );
 340         // TODO description options
 341         return $options;
 342     }
 343
 344     /**
 345      * Gets the options of this rubric definition, fills the missing options with default values
 346      *
 347      * @return array
 348      */
 349     public function get_options() {
 350         $options = self::get_default_options();
 351         if (!empty($this->definition->options)) {
 352             $thisoptions = json_decode($this->definition->options);
 353             foreach ($thisoptions as $option => $value) {
 354                 $options[$option] = $value;
 355             }
 356         }
 357         return $options;
 358     }
 359
 360     /**
 361      * Converts the current definition into an object suitable for the editor form's set_data()
 362      *
 363      * @return stdClass
 364      */
 365     public function get_definition_for_editing() {
 366
 367         $definition = $this->get_definition();
 368         $properties = new stdClass();
 369         $properties->areaid = $this->areaid;
 370         if ($definition) {
 371             foreach (array('id', 'name', 'description', 'descriptionformat', 'status') as $key) {
 372                 $properties->$key = $definition->$key;
 373             }
 374             $options = self::description_form_field_options($this->get_context());
 375             $properties = file_prepare_standard_editor($properties, 'description', $options, $this->get_context(),
 376                 'grading', 'description', $definition->id);
 377         }
 378         $properties->rubric = array('criteria' => array(), 'options' => $this->get_options());
 379         if (!empty($definition->rubric_criteria)) {
 380             $properties->rubric['criteria'] = $definition->rubric_criteria;
 381         }
 382
 383         return $properties;
 384     }
 385
 386     /**
 387      * Returns the form definition suitable for cloning into another area
 388      *
 389      * @see parent::get_definition_copy()
 390      * @param gradingform_controller $target the controller of the new copy
 391      * @return stdClass definition structure to pass to the target's {@link update_definition()}
 392      */
 393     public function get_definition_copy(gradingform_controller $target) {
 394
 395         $new = parent::get_definition_copy($target);
 396         $old = $this->get_definition_for_editing();
 397         $new->description_editor = $old->description_editor;
 398         $new->rubric = array('criteria' => array(), 'options' => $old->rubric['options']);
 399         $newcritid = 1;
 400         $newlevid = 1;
 401         foreach ($old->rubric['criteria'] as $oldcritid => $oldcrit) {
 402             unset($oldcrit['id']);
 403             if (isset($oldcrit['levels'])) {
 404                 foreach ($oldcrit['levels'] as $oldlevid => $oldlev) {
 405                     unset($oldlev['id']);
 406                     $oldcrit['levels']['NEWID'.$newlevid] = $oldlev;
 407                     unset($oldcrit['levels'][$oldlevid]);
 408                     $newlevid++;
 409                 }
 410             } else {
 411                 $oldcrit['levels'] = array();
 412             }
 413             $new->rubric['criteria']['NEWID'.$newcritid] = $oldcrit;
 414             $newcritid++;
 415         }
 416
 417         return $new;
 418     }
 419
 420     /**
 421      * Options for displaying the rubric description field in the form
 422      *
 423      * @param object $context
 424      * @return array options for the form description field
 425      */
 426     public static function description_form_field_options($context) {
 427         global $CFG;
 428         return array(
 429             'maxfiles' => -1,
 430             'maxbytes' => get_max_upload_file_size($CFG->maxbytes),
 431             'context'  => $context,
 432         );
 433     }
 434
 435     /**
 436      * Formats the definition description for display on page
 437      *
 438      * @return string
 439      */
 440     public function get_formatted_description() {
 441         if (!isset($this->definition->description)) {
 442             return '';
 443         }
 444         $context = $this->get_context();
 445
 446         $options = self::description_form_field_options($this->get_context());
 447         $description = file_rewrite_pluginfile_urls($this->definition->description, 'pluginfile.php', $context->id,
 448             'grading', 'description', $this->definition->id, $options);
 449
 450         $formatoptions = array(
 451             'noclean' => false,
 452             'trusted' => false,
 453             'filter' => true,
 454             'context' => $context
 455         );
 456         return format_text($description, $this->definition->descriptionformat, $formatoptions);
 457     }
 458
 459     /**
 460      * Returns the rubric plugin renderer
 461      *
 462      * @param moodle_page $page the target page
 463      * @return gradingform_rubric_renderer
 464      */
 465     public function get_renderer(moodle_page $page) {
 466         return $page->get_renderer('gradingform_'. $this->get_method_name());
 467     }
 468
 469     /**
 470      * Returns the HTML code displaying the preview of the grading form
 471      *
 472      * @param moodle_page $page the target page
 473      * @return string
 474      */
 475     public function render_preview(moodle_page $page) {
 476
 477         if (!$this->is_form_defined()) {
 478             throw new coding_exception('It is the caller\'s responsibility to make sure that the form is actually defined');
 479         }
 480
 481         $output = $this->get_renderer($page);
 482         $criteria = $this->definition->rubric_criteria;
 483         $options = $this->get_options();
 484         $rubric = $output->display_rubric($criteria, $options, self::DISPLAY_PREVIEW, 'rubric');
 485
 486         return $rubric;
 487     }
 488
 489     /**
 490      * Deletes the rubric definition and all the associated information
 491      */
 492     protected function delete_plugin_definition() {
 493         global $DB;
 494
 495         // get the list of instances
 496         $instances = array_keys($DB->get_records('grading_instances', array('definitionid' => $this->definition->id), '', 'id'));
 497         // delete all fillings
 498         $DB->delete_records_list('gradingform_rubric_fillings', 'instanceid', $instances);
 499         // delete instances
 500         $DB->delete_records_list('grading_instances', 'id', $instances);
 501         // get the list of criteria records
 502         $criteria = array_keys($DB->get_records('gradingform_rubric_criteria', array('definitionid' => $this->definition->id), '', 'id'));
 503         // delete levels
 504         $DB->delete_records_list('gradingform_rubric_levels', 'criterionid', $criteria);
 505         // delete critera
 506         $DB->delete_records_list('gradingform_rubric_criteria', 'id', $criteria);
 507     }
 508
 509     /**
 510      * If instanceid is specified and grading instance exists and it is created by this rater for
 511      * this item, this instance is returned.
 512      * If there exists a draft for this raterid+itemid, take this draft (this is the change from parent)
 513      * Otherwise new instance is created for the specified rater and itemid
 514      *
 515      * @param int $instanceid
 516      * @param int $raterid
 517      * @param int $itemid
 518      * @return gradingform_instance
 519      */
 520     public function get_or_create_instance($instanceid, $raterid, $itemid) {
 521         global $DB;
 522         if ($instanceid &&
 523                 $instance = $DB->get_record('grading_instances', array('id'  => $instanceid, 'raterid' => $raterid, 'itemid' => $itemid), '*', IGNORE_MISSING)) {
 524             return $this->get_instance($instance);
 525         }
 526         if ($itemid && $raterid) {
 527             if ($rs = $DB->get_records('grading_instances', array('raterid' => $raterid, 'itemid' => $itemid), 'timemodified DESC', '*', 0, 1)) {
 528                 $record = reset($rs);
 529                 $currentinstance = $this->get_current_instance($raterid, $itemid);
 530                 if ($record->status == gradingform_rubric_instance::INSTANCE_STATUS_INCOMPLETE &&
 531                         (!$currentinstance || $record->timemodified > $currentinstance->get_data('timemodified'))) {
 532                     $record->isrestored = true;
 533                     return $this->get_instance($record);
 534                 }
 535             }
 536         }
 537         return $this->create_instance($raterid, $itemid);
 538     }
 539
 540     /**
 541      * Returns html code to be included in student's feedback.
 542      *
 543      * @param moodle_page $page
 544      * @param int $itemid
 545      * @param array $gradinginfo result of function grade_get_grades
 546      * @param string $defaultcontent default string to be returned if no active grading is found
 547      * @param boolean $cangrade whether current user has capability to grade in this context
 548      * @return string
 549      */
 550     public function render_grade($page, $itemid, $gradinginfo, $defaultcontent, $cangrade) {
 551         return $this->get_renderer($page)->display_instances($this->get_active_instances($itemid), $defaultcontent, $cangrade);
 552     }
 553
 554     //// full-text search support /////////////////////////////////////////////
 555
 556     /**
 557      * Prepare the part of the search query to append to the FROM statement
 558      *
 559      * @param string $gdid the alias of grading_definitions.id column used by the caller
 560      * @return string
 561      */
 562     public static function sql_search_from_tables($gdid) {
 563         return " LEFT JOIN {gradingform_rubric_criteria} rc ON (rc.definitionid = $gdid)
 564                  LEFT JOIN {gradingform_rubric_levels} rl ON (rl.criterionid = rc.id)";
 565     }
 566
 567     /**
 568      * Prepare the parts of the SQL WHERE statement to search for the given token
 569      *
 570      * The returned array cosists of the list of SQL comparions and the list of
 571      * respective parameters for the comparisons. The returned chunks will be joined
 572      * with other conditions using the OR operator.
 573      *
 574      * @param string $token token to search for
 575      * @return array
 576      */
 577     public static function sql_search_where($token) {
 578         global $DB;
 579
 580         $subsql = array();
 581         $params = array();
 582
 583         // search in rubric criteria description
 584         $subsql[] = $DB->sql_like('rc.description', '?', false, false);
 585         $params[] = '%'.$DB->sql_like_escape($token).'%';
 586
 587         // search in rubric levels definition
 588         $subsql[] = $DB->sql_like('rl.definition', '?', false, false);
 589         $params[] = '%'.$DB->sql_like_escape($token).'%';
 590
 591         return array($subsql, $params);
 592     }
 593 }
 594
 595 /**
 596  * Class to manage one rubric grading instance. Stores information and performs actions like
 597  * update, copy, validate, submit, etc.
 598  *
 599  * @copyright  2011 Marina Glancy
 600  */
 601 class gradingform_rubric_instance extends gradingform_instance {
 602
 603     protected $rubric;
 604
 605     /**
 606      * Deletes this (INCOMPLETE) instance from database.
 607      */
 608     public function cancel() {
 609         global $DB;
 610         parent::cancel();
 611         $DB->delete_records('gradingform_rubric_fillings', array('instanceid' => $this->get_id()));
 612     }
 613
 614     /**
 615      * Duplicates the instance before editing (optionally substitutes raterid and/or itemid with
 616      * the specified values)
 617      *
 618      * @param int $raterid value for raterid in the duplicate
 619      * @param int $itemid value for itemid in the duplicate
 620      * @return int id of the new instance
 621      */
 622     public function copy($raterid, $itemid) {
 623         global $DB;
 624         $instanceid = parent::copy($raterid, $itemid);
 625         $currentgrade = $this->get_rubric_filling();
 626         foreach ($currentgrade['criteria'] as $criterionid => $record) {
 627             $params = array('instanceid' => $instanceid, 'criterionid' => $criterionid,
 628                 'levelid' => $record['levelid'], 'remark' => $record['remark'], 'remarkformat' => $record['remarkformat']);
 629             $DB->insert_record('gradingform_rubric_fillings', $params);
 630         }
 631         return $instanceid;
 632     }
 633
 634     /**
 635      * Validates that rubric is fully completed and contains valid grade on each criterion
 636      *
 637      * @param array $elementvalue value of element as came in form submit
 638      * @return boolean true if the form data is validated and contains no errors
 639      */
 640     public function validate_grading_element($elementvalue) {
 641         $criteria = $this->get_controller()->get_definition()->rubric_criteria;
 642         if (!isset($elementvalue['criteria']) || !is_array($elementvalue['criteria']) || sizeof($elementvalue['criteria']) < sizeof($criteria)) {
 643             return false;
 644         }
 645         foreach ($criteria as $id => $criterion) {
 646             if (!isset($elementvalue['criteria'][$id]['levelid'])
 647                     || !array_key_exists($elementvalue['criteria'][$id]['levelid'], $criterion['levels'])) {
 648                 return false;
 649             }
 650         }
 651         return true;
 652     }
 653
 654     /**
 655      * Retrieves from DB and returns the data how this rubric was filled
 656      *
 657      * @param boolean $force whether to force DB query even if the data is cached
 658      * @return array
 659      */
 660     public function get_rubric_filling($force = false) {
 661         global $DB;
 662         if ($this->rubric === null || $force) {
 663             $records = $DB->get_records('gradingform_rubric_fillings', array('instanceid' => $this->get_id()));
 664             $this->rubric = array('criteria' => array());
 665             foreach ($records as $record) {
 666                 $this->rubric['criteria'][$record->criterionid] = (array)$record;
 667             }
 668         }
 669         return $this->rubric;
 670     }
 671
 672     /**
 673      * Updates the instance with the data received from grading form. This function may be
 674      * called via AJAX when grading is not yet completed, so it does not change the
 675      * status of the instance.
 676      *
 677      * @param array $data
 678      */
 679     public function update($data) {
 680         global $DB;
 681         $currentgrade = $this->get_rubric_filling();
 682         parent::update($data);
 683         foreach ($data['criteria'] as $criterionid => $record) {
 684             if (!array_key_exists($criterionid, $currentgrade['criteria'])) {
 685                 $newrecord = array('instanceid' => $this->get_id(), 'criterionid' => $criterionid,
 686                     'levelid' => $record['levelid'], 'remarkformat' => FORMAT_MOODLE);
 687                 if (isset($record['remark'])) {
 688                     $newrecord['remark'] = $record['remark'];
 689                 }
 690                 $DB->insert_record('gradingform_rubric_fillings', $newrecord);
 691             } else {
 692                 $newrecord = array('id' => $currentgrade['criteria'][$criterionid]['id']);
 693                 foreach (array('levelid', 'remark'/*, 'remarkformat' TODO */) as $key) {
 694                     if (isset($record[$key]) && $currentgrade['criteria'][$criterionid][$key] != $record[$key]) {
 695                         $newrecord[$key] = $record[$key];
 696                     }
 697                 }
 698                 if (count($newrecord) > 1) {
 699                     $DB->update_record('gradingform_rubric_fillings', $newrecord);
 700                 }
 701             }
 702         }
 703         foreach ($currentgrade['criteria'] as $criterionid => $record) {
 704             if (!array_key_exists($criterionid, $data['criteria'])) {
 705                 $DB->delete_records('gradingform_rubric_fillings', array('id' => $record['id']));
 706             }
 707         }
 708         $this->get_rubric_filling(true);
 709     }
 710
 711     /**
 712      * Calculates the grade to be pushed to the gradebook
 713      *
 714      * @return int the valid grade from $this->get_controller()->get_grade_range()
 715      */
 716     public function get_grade() {
 717         global $DB, $USER;
 718         $grade = $this->get_rubric_filling();
 719
 720         $minscore = 0;
 721         $maxscore = 0;
 722         foreach ($this->get_controller()->get_definition()->rubric_criteria as $id => $criterion) {
 723             $scores = array();
 724             foreach ($criterion['levels'] as $level) {
 725                 $scores[] = $level['score'];
 726             }
 727             sort($scores);
 728             $minscore += $scores[0];
 729             $maxscore += $scores[sizeof($scores)-1];
 730         }
 731
 732         if ($maxscore <= $minscore) {
 733             return -1;
 734         }
 735
 736         $graderange = array_keys($this->get_controller()->get_grade_range());
 737         if (empty($graderange)) {
 738             return -1;
 739         }
 740         sort($graderange);
 741         $mingrade = $graderange[0];
 742         $maxgrade = $graderange[sizeof($graderange) - 1];
 743
 744         $curscore = 0;
 745         foreach ($grade['criteria'] as $id => $record) {
 746             $curscore += $this->get_controller()->get_definition()->rubric_criteria[$id]['levels'][$record['levelid']]['score'];
 747         }
 748         return round(($curscore-$minscore)/($maxscore-$minscore)*($maxgrade-$mingrade), 0) + $mingrade; // TODO mapping
 749     }
 750
 751     /**
 752      * Returns html for form element of type 'grading'.
 753      *
 754      * @param moodle_page $page
 755      * @param MoodleQuickForm_grading $formelement
 756      * @return string
 757      */
 758     public function render_grading_element($page, $gradingformelement) {
 759         global $USER;
 760         if (!$gradingformelement->_flagFrozen) {
 761             $module = array('name'=>'gradingform_rubric', 'fullpath'=>'/grade/grading/form/rubric/js/rubric.js');
 762             $page->requires->js_init_call('M.gradingform_rubric.init', array(array('name' => $gradingformelement->getName())), true, $module);
 763             $mode = gradingform_rubric_controller::DISPLAY_EVAL;
 764         } else {
 765             if ($gradingformelement->_persistantFreeze) {
 766                 $mode = gradingform_rubric_controller::DISPLAY_EVAL_FROZEN;
 767             } else {
 768                 $mode = gradingform_rubric_controller::DISPLAY_REVIEW;
 769             }
 770         }
 771         $criteria = $this->get_controller()->get_definition()->rubric_criteria;
 772         $options = $this->get_controller()->get_options();
 773         $value = $gradingformelement->getValue();
 774         $html = '';
 775         if ($value === null) {
 776             $value = $this->get_rubric_filling();
 777         } else if (!$this->validate_grading_element($value)) {
 778             $html .= html_writer::tag('div', get_string('rubricnotcompleted', 'gradingform_rubric'), array('class' => 'gradingform_rubric-error'));
 779         }
 780         $currentinstance = $this->get_current_instance();
 781         if ($currentinstance && $currentinstance->get_status() == gradingform_instance::INSTANCE_STATUS_NEEDUPDATE) {
 782             $html .= html_writer::tag('div', get_string('needregrademessage', 'gradingform_rubric'), array('class' => 'gradingform_rubric-regrade'));
 783         }
 784         $haschanges = false;
 785         if ($currentinstance) {
 786             $curfilling = $currentinstance->get_rubric_filling();
 787             foreach ($curfilling['criteria'] as $criterionid => $curvalues) {
 788                 $value['criteria'][$criterionid]['savedlevelid'] = $curvalues['levelid'];
 789                 $newremark = null;
 790                 $newlevelid = null;
 791                 if (isset($value['criteria'][$criterionid]['remark'])) $newremark = $value['criteria'][$criterionid]['remark'];
 792                 if (isset($value['criteria'][$criterionid]['levelid'])) $newlevelid = $value['criteria'][$criterionid]['levelid'];
 793                 if ($newlevelid != $curvalues['levelid'] || $newremark != $curvalues['remark']) {
 794                     $haschanges = true;
 795                 }
 796             }
 797         }
 798         if ($this->get_data('isrestored') && $haschanges) {
 799             $html .= html_writer::tag('div', get_string('restoredfromdraft', 'gradingform_rubric'), array('class' => 'gradingform_rubric-restored'));
 800         }
 801         $html .= $this->get_controller()->get_renderer($page)->display_rubric($criteria, $options, $mode, $gradingformelement->getName(), $value);
 802         return $html;
 803     }
 804 }