Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 401 and 402] [Versions 401 and 403]

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