[Summary view]

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   * Common classes used by gradingform plugintypes are defined here
  19   *
  20   * @package    core_grading
  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  /**
  28   * Class represents a grading form definition used in a particular area
  29   *
  30   * General data about definition is stored in the standard DB table
  31   * grading_definitions. A separate entry is created for each grading area
  32   * (i.e. for each module). Plugins may define and use additional tables
  33   * to store additional data about definitions.
  34   *
  35   * Advanced grading plugins must declare a class gradingform_xxxx_controller
  36   * extending this class and put it in lib.php in the plugin folder.
  37   *
  38   * See {@link gradingform_rubric_controller} as an example
  39   *
  40   * Except for overwriting abstract functions, plugin developers may want
  41   * to overwrite functions responsible for loading and saving of the
  42   * definition to include additional data stored.
  43   *
  44   * @package    core_grading
  45   * @copyright  2011 David Mudrak <david@moodle.com>
  46   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  47   * @category   grading
  48   */
  49  abstract class gradingform_controller {
  50  
  51      /** undefined definition status */
  52      const DEFINITION_STATUS_NULL = 0;
  53      /** the form is currently being edited and is not ready for usage yet */
  54      const DEFINITION_STATUS_DRAFT = 10;
  55      /** the form was marked as ready for actual usage */
  56      const DEFINITION_STATUS_READY = 20;
  57  
  58      /** @var stdClass the context */
  59      protected $context;
  60  
  61      /** @var string the frankenstyle name of the component */
  62      protected $component;
  63  
  64      /** @var string the name of the gradable area */
  65      protected $area;
  66  
  67      /** @var int the id of the gradable area record */
  68      protected $areaid;
  69  
  70      /** @var stdClass|false the definition structure */
  71      protected $definition = false;
  72  
  73      /** @var array graderange array of valid grades for this area. Use set_grade_range and get_grade_range to access this */
  74      private $graderange = null;
  75  
  76      /** @var bool if decimal values are allowed as grades. */
  77      private $allowgradedecimals = false;
  78  
  79      /** @var boolean|null cached result of function has_active_instances() */
  80      protected $hasactiveinstances = null;
  81  
  82      /**
  83       * Do not instantinate this directly, use {@link grading_manager::get_controller()}
  84       *
  85       * @param stdClass $context the context of the form
  86       * @param string $component the frankenstyle name of the component
  87       * @param string $area the name of the gradable area
  88       * @param int $areaid the id of the gradable area record
  89       */
  90      public function __construct(stdClass $context, $component, $area, $areaid) {
  91          global $DB;
  92  
  93          $this->context      = $context;
  94          list($type, $name)  = core_component::normalize_component($component);
  95          $this->component    = $type.'_'.$name;
  96          $this->area         = $area;
  97          $this->areaid       = $areaid;
  98  
  99          $this->load_definition();
 100      }
 101  
 102      /**
 103       * Returns controller context
 104       *
 105       * @return stdClass controller context
 106       */
 107      public function get_context() {
 108          return $this->context;
 109      }
 110  
 111      /**
 112       * Returns gradable component name
 113       *
 114       * @return string gradable component name
 115       */
 116      public function get_component() {
 117          return $this->component;
 118      }
 119  
 120      /**
 121       * Returns gradable area name
 122       *
 123       * @return string gradable area name
 124       */
 125      public function get_area() {
 126          return $this->area;
 127      }
 128  
 129      /**
 130       * Returns gradable area id
 131       *
 132       * @return int gradable area id
 133       */
 134      public function get_areaid() {
 135          return $this->areaid;
 136      }
 137  
 138      /**
 139       * Is the form definition record available?
 140       *
 141       * Note that this actually checks whether the process of defining the form ever started
 142       * and not whether the form definition should be considered as final.
 143       *
 144       * @return boolean
 145       */
 146      public function is_form_defined() {
 147          return ($this->definition !== false);
 148      }
 149  
 150      /**
 151       * Is the grading form defined and ready for usage?
 152       *
 153       * @return boolean
 154       */
 155      public function is_form_available() {
 156          return ($this->is_form_defined() && $this->definition->status == self::DEFINITION_STATUS_READY);
 157      }
 158  
 159      /**
 160       * Is the grading form saved as a shared public template?
 161       *
 162       * @return boolean
 163       */
 164      public function is_shared_template() {
 165          return ($this->get_context()->id == context_system::instance()->id
 166              and $this->get_component() == 'core_grading');
 167      }
 168  
 169      /**
 170       * Is the grading form owned by the given user?
 171       *
 172       * The form owner is the user who created this instance of the form.
 173       *
 174       * @param int $userid the user id to check, defaults to the current user
 175       * @return boolean|null null if the form not defined yet, boolean otherwise
 176       */
 177      public function is_own_form($userid = null) {
 178          global $USER;
 179  
 180          if (!$this->is_form_defined()) {
 181              return null;
 182          }
 183          if (is_null($userid)) {
 184              $userid = $USER->id;
 185          }
 186          return ($this->definition->usercreated == $userid);
 187      }
 188  
 189      /**
 190       * Returns a message why this form is unavailable. Maybe overriden by plugins to give more details.
 191       * @see is_form_available()
 192       *
 193       * @return string
 194       */
 195      public function form_unavailable_notification() {
 196          if ($this->is_form_available()) {
 197              return null;
 198          }
 199          return get_string('gradingformunavailable', 'grading');
 200      }
 201  
 202      /**
 203       * Returns URL of a page where the grading form can be defined and edited.
 204       *
 205       * @param moodle_url $returnurl optional URL of a page where the user should be sent once they are finished with editing
 206       * @return moodle_url
 207       */
 208      public function get_editor_url(moodle_url $returnurl = null) {
 209  
 210          $params = array('areaid' => $this->areaid);
 211  
 212          if (!is_null($returnurl)) {
 213              $params['returnurl'] = $returnurl->out(false);
 214          }
 215  
 216          return new moodle_url('/grade/grading/form/'.$this->get_method_name().'/edit.php', $params);
 217      }
 218  
 219      /**
 220       * Extends the module settings navigation
 221       *
 222       * This function is called when the context for the page is an activity module with the
 223       * FEATURE_ADVANCED_GRADING, the user has the permission moodle/grade:managegradingforms
 224       * and there is an area with the active grading method set to the given plugin.
 225       *
 226       * @param settings_navigation $settingsnav {@link settings_navigation}
 227       * @param navigation_node $node {@link navigation_node}
 228       */
 229      public function extend_settings_navigation(settings_navigation $settingsnav, navigation_node $node=null) {
 230          // do not extend by default
 231      }
 232  
 233      /**
 234       * Extends the module navigation
 235       *
 236       * This function is called when the context for the page is an activity module with the
 237       * FEATURE_ADVANCED_GRADING and there is an area with the active grading method set to the given plugin.
 238       *
 239       * @param global_navigation $navigation {@link global_navigation}
 240       * @param navigation_node $node {@link navigation_node}
 241       */
 242      public function extend_navigation(global_navigation $navigation, navigation_node $node=null) {
 243          // do not extend by default
 244      }
 245  
 246      /**
 247       * Returns the grading form definition structure
 248       *
 249       * @param boolean $force whether to force loading from DB even if it was already loaded
 250       * @return stdClass|false definition data or false if the form is not defined yet
 251       */
 252      public function get_definition($force = false) {
 253          if ($this->definition === false || $force) {
 254              $this->load_definition();
 255          }
 256          return $this->definition;
 257      }
 258  
 259      /**
 260       * Returns the form definition suitable for cloning into another area
 261       *
 262       * @param gradingform_controller $target the controller of the new copy
 263       * @return stdClass definition structure to pass to the target's {@link update_definition()}
 264       */
 265      public function get_definition_copy(gradingform_controller $target) {
 266  
 267          if (get_class($this) != get_class($target)) {
 268              throw new coding_exception('The source and copy controller mismatch');
 269          }
 270  
 271          if ($target->is_form_defined()) {
 272              throw new coding_exception('The target controller already contains a form definition');
 273          }
 274  
 275          $old = $this->get_definition();
 276          // keep our id
 277          $new = new stdClass();
 278          $new->copiedfromid = $old->id;
 279          $new->name = $old->name;
 280          // once we support files embedded into the description, we will want to
 281          // relink them into the new file area here (that is why we accept $target)
 282          $new->description = $old->description;
 283          $new->descriptionformat = $old->descriptionformat;
 284          $new->options = $old->options;
 285          $new->status = $old->status;
 286  
 287          return $new;
 288      }
 289  
 290      /**
 291       * Saves the defintion data into the database
 292       *
 293       * The implementation in this base class stores the common data into the record
 294       * into the {grading_definition} table. The plugins are likely to extend this
 295       * and save their data into own tables, too.
 296       *
 297       * @param stdClass $definition data containing values for the {grading_definition} table
 298       * @param int|null $usermodified optional userid of the author of the definition, defaults to the current user
 299       */
 300      public function update_definition(stdClass $definition, $usermodified = null) {
 301          global $DB, $USER;
 302  
 303          if (is_null($usermodified)) {
 304              $usermodified = $USER->id;
 305          }
 306  
 307          if (!empty($this->definition->id)) {
 308              // prepare a record to be updated
 309              $record = new stdClass();
 310              // populate it with scalar values from the passed definition structure
 311              foreach ($definition as $prop => $val) {
 312                  if (is_array($val) or is_object($val)) {
 313                      // probably plugin's data
 314                      continue;
 315                  }
 316                  $record->{$prop} = $val;
 317              }
 318              // make sure we do not override some crucial values by accident
 319              if (!empty($record->id) and $record->id != $this->definition->id) {
 320                  throw new coding_exception('Attempting to update other definition record.');
 321              }
 322              $record->id = $this->definition->id;
 323              unset($record->areaid);
 324              unset($record->method);
 325              unset($record->timecreated);
 326              // set the modification flags
 327              $record->timemodified = time();
 328              $record->usermodified = $usermodified;
 329  
 330              $DB->update_record('grading_definitions', $record);
 331  
 332          } else if ($this->definition === false) {
 333              // prepare a record to be inserted
 334              $record = new stdClass();
 335              // populate it with scalar values from the passed definition structure
 336              foreach ($definition as $prop => $val) {
 337                  if (is_array($val) or is_object($val)) {
 338                      // probably plugin's data
 339                      continue;
 340                  }
 341                  $record->{$prop} = $val;
 342              }
 343              // make sure we do not override some crucial values by accident
 344              if (!empty($record->id)) {
 345                  throw new coding_exception('Attempting to create a new record while there is already one existing.');
 346              }
 347              unset($record->id);
 348              $record->areaid       = $this->areaid;
 349              $record->method       = $this->get_method_name();
 350              $record->timecreated  = time();
 351              $record->usercreated  = $usermodified;
 352              $record->timemodified = $record->timecreated;
 353              $record->usermodified = $record->usercreated;
 354              if (empty($record->status)) {
 355                  $record->status = self::DEFINITION_STATUS_DRAFT;
 356              }
 357              if (empty($record->descriptionformat)) {
 358                  $record->descriptionformat = FORMAT_MOODLE; // field can not be empty
 359              }
 360  
 361              $DB->insert_record('grading_definitions', $record);
 362  
 363          } else {
 364              throw new coding_exception('Unknown status of the cached definition record.');
 365          }
 366      }
 367  
 368      /**
 369       * Formats the definition description for display on page
 370       *
 371       * @return string
 372       */
 373      public function get_formatted_description() {
 374          if (!isset($this->definition->description)) {
 375              return '';
 376          }
 377          return format_text($this->definition->description, $this->definition->descriptionformat);
 378      }
 379  
 380      /**
 381       * Returns the current instance (either with status ACTIVE or NEEDUPDATE) for this definition for the
 382       * specified $raterid and $itemid (if multiple raters are allowed, or only for $itemid otherwise).
 383       *
 384       * @param int $raterid
 385       * @param int $itemid
 386       * @param boolean $idonly
 387       * @return mixed if $idonly=true returns id of the found instance, otherwise returns the instance object
 388       */
 389      public function get_current_instance($raterid, $itemid, $idonly = false) {
 390          global $DB;
 391          $params = array(
 392                  'definitionid'  => $this->definition->id,
 393                  'itemid' => $itemid,
 394                  'status1'  => gradingform_instance::INSTANCE_STATUS_ACTIVE,
 395                  'status2'  => gradingform_instance::INSTANCE_STATUS_NEEDUPDATE);
 396          $select = 'definitionid=:definitionid and itemid=:itemid and (status=:status1 or status=:status2)';
 397          if (false) {
 398              // TODO MDL-31237 should be: if ($manager->allow_multiple_raters())
 399              $select .= ' and raterid=:raterid';
 400              $params['raterid'] = $raterid;
 401          }
 402          if ($idonly) {
 403              if ($current = $DB->get_record_select('grading_instances', $select, $params, 'id', IGNORE_MISSING)) {
 404                  return $current->id;
 405              }
 406          } else {
 407              if ($current = $DB->get_record_select('grading_instances', $select, $params, '*', IGNORE_MISSING)) {
 408                  return $this->get_instance($current);
 409              }
 410          }
 411          return null;
 412      }
 413  
 414      /**
 415       * Returns list of ACTIVE instances for the specified $itemid
 416       * (intentionally does not return instances with status NEEDUPDATE)
 417       *
 418       * @param int $itemid
 419       * @return array of gradingform_instance objects
 420       */
 421      public function get_active_instances($itemid) {
 422          global $DB;
 423          $conditions = array('definitionid'  => $this->definition->id,
 424                      'itemid' => $itemid,
 425                      'status'  => gradingform_instance::INSTANCE_STATUS_ACTIVE);
 426          $records = $DB->get_recordset('grading_instances', $conditions);
 427          $rv = array();
 428          foreach ($records as $record) {
 429              $rv[] = $this->get_instance($record);
 430          }
 431          $records->close();
 432          return $rv;
 433      }
 434  
 435      /**
 436       * Returns an array of all active instances for this definition.
 437       * (intentionally does not return instances with status NEEDUPDATE)
 438       *
 439       * @param int since only return instances with timemodified >= since
 440       * @return array of gradingform_instance objects
 441       */
 442      public function get_all_active_instances($since = 0) {
 443          global $DB;
 444          $conditions = array ($this->definition->id,
 445                               gradingform_instance::INSTANCE_STATUS_ACTIVE,
 446                               $since);
 447          $where = "definitionid = ? AND status = ? AND timemodified >= ?";
 448          $records = $DB->get_records_select('grading_instances', $where, $conditions);
 449          $rv = array();
 450          foreach ($records as $record) {
 451              $rv[] = $this->get_instance($record);
 452          }
 453          return $rv;
 454      }
 455  
 456      /**
 457       * Returns true if there are already people who has been graded on this definition.
 458       * In this case plugins may restrict changes of the grading definition
 459       *
 460       * @return boolean
 461       */
 462      public function has_active_instances() {
 463          global $DB;
 464          if (empty($this->definition->id)) {
 465              return false;
 466          }
 467          if ($this->hasactiveinstances === null) {
 468              $conditions = array('definitionid'  => $this->definition->id,
 469                          'status'  => gradingform_instance::INSTANCE_STATUS_ACTIVE);
 470              $this->hasactiveinstances = $DB->record_exists('grading_instances', $conditions);
 471          }
 472          return $this->hasactiveinstances;
 473      }
 474  
 475      /**
 476       * Returns the object of type gradingform_XXX_instance (where XXX is the plugin method name)
 477       *
 478       * @param mixed $instance id or row from grading_isntances table
 479       * @return gradingform_instance
 480       */
 481      protected function get_instance($instance) {
 482          global $DB;
 483          if (is_scalar($instance)) {
 484              // instance id is passed as parameter
 485              $instance = $DB->get_record('grading_instances', array('id'  => $instance), '*', MUST_EXIST);
 486          }
 487          if ($instance) {
 488              $class = 'gradingform_'. $this->get_method_name(). '_instance';
 489              return new $class($this, $instance);
 490          }
 491          return null;
 492      }
 493  
 494      /**
 495       * This function is invoked when user (teacher) starts grading.
 496       * It creates and returns copy of the current ACTIVE instance if it exists. If this is the
 497       * first grading attempt, a new instance is created.
 498       * The status of the returned instance is INCOMPLETE
 499       *
 500       * @param int $raterid
 501       * @param int $itemid
 502       * @return gradingform_instance
 503       */
 504      public function create_instance($raterid, $itemid = null) {
 505  
 506          // first find if there is already an active instance for this itemid
 507          if ($itemid && $current = $this->get_current_instance($raterid, $itemid)) {
 508              return $this->get_instance($current->copy($raterid, $itemid));
 509          } else {
 510              $class = 'gradingform_'. $this->get_method_name(). '_instance';
 511              return $this->get_instance($class::create_new($this->definition->id, $raterid, $itemid));
 512          }
 513      }
 514  
 515      /**
 516       * If instanceid is specified and grading instance exists and it is created by this rater for
 517       * this item, this instance is returned.
 518       * Otherwise new instance is created for the specified rater and itemid
 519       *
 520       * @param int $instanceid
 521       * @param int $raterid
 522       * @param int $itemid
 523       * @return gradingform_instance
 524       * @throws dml_exception
 525       */
 526      public function get_or_create_instance($instanceid, $raterid, $itemid) {
 527          if (!is_numeric($instanceid)) {
 528              $instanceid = null;
 529          }
 530          return $this->fetch_instance($raterid, $itemid, $instanceid);
 531      }
 532  
 533      /**
 534       * If an instanceid is specified and grading instance exists and it is created by this rater for
 535       * this item, then the instance is returned.
 536       *
 537       * If instanceid is not known, then null can be passed to fetch the current instance matchign the specified raterid
 538       * and itemid.
 539       *
 540       * If the instanceid is falsey, or no instance was found, then create a new instance for the specified rater and item.
 541       *
 542       * @param int $raterid
 543       * @param int $itemid
 544       * @param int $instanceid
 545       * @return gradingform_instance
 546       * @throws dml_exception
 547       */
 548      public function fetch_instance(int $raterid, int $itemid, ?int $instanceid): gradingform_instance {
 549          global $DB;
 550  
 551          $instance = null;
 552          if (null === $instanceid) {
 553              if ($instance = $this->get_current_instance($raterid, $itemid)) {
 554                  return $instance;
 555              }
 556              $instanceid = $instancerecord->id ?? null;
 557          }
 558  
 559          if (!empty($instanceid)) {
 560              $instance = $DB->get_record('grading_instances', [
 561                  'id'  => $instanceid,
 562                  'raterid' => $raterid,
 563                  'itemid' => $itemid,
 564              ], '*', IGNORE_MISSING);
 565  
 566              if ($instance) {
 567                  return $this->get_instance($instance);
 568              }
 569          }
 570  
 571          return $this->create_instance($raterid, $itemid);
 572      }
 573  
 574      /**
 575       * Returns the HTML code displaying the preview of the grading form
 576       *
 577       * Plugins are forced to override this. Ideally they should delegate
 578       * the task to their own renderer.
 579       *
 580       * @param moodle_page $page the target page
 581       * @return string
 582       */
 583      abstract public function render_preview(moodle_page $page);
 584  
 585      /**
 586       * Deletes the form definition and all the associated data
 587       *
 588       * @see delete_plugin_definition()
 589       * @return void
 590       */
 591      public function delete_definition() {
 592          global $DB;
 593  
 594          if (!$this->is_form_defined()) {
 595              // nothing to do
 596              return;
 597          }
 598  
 599          // firstly, let the plugin delete everything from their own tables
 600          $this->delete_plugin_definition();
 601          // then, delete all instances left
 602          $DB->delete_records('grading_instances', array('definitionid' => $this->definition->id));
 603          // finally, delete the main definition record
 604          $DB->delete_records('grading_definitions', array('id' => $this->definition->id));
 605  
 606          $this->definition = false;
 607      }
 608  
 609      /**
 610       * Prepare the part of the search query to append to the FROM statement
 611       *
 612       * @param string $gdid the alias of grading_definitions.id column used by the caller
 613       * @return string
 614       */
 615      public static function sql_search_from_tables($gdid) {
 616          return '';
 617      }
 618  
 619      /**
 620       * Prepare the parts of the SQL WHERE statement to search for the given token
 621       *
 622       * The returned array cosists of the list of SQL comparions and the list of
 623       * respective parameters for the comparisons. The returned chunks will be joined
 624       * with other conditions using the OR operator.
 625       *
 626       * @param string $token token to search for
 627       * @return array
 628       */
 629      public static function sql_search_where($token) {
 630  
 631          $subsql = array();
 632          $params = array();
 633  
 634          return array($subsql, $params);
 635      }
 636  
 637      // //////////////////////////////////////////////////////////////////////////
 638  
 639      /**
 640       * Loads the form definition if it exists
 641       *
 642       * The default implementation just tries to load the record from the {grading_definitions}
 643       * table. The plugins are likely to override this with a more complex query that loads
 644       * all required data at once.
 645       */
 646      protected function load_definition() {
 647          global $DB;
 648          $this->definition = $DB->get_record('grading_definitions', array(
 649              'areaid' => $this->areaid,
 650              'method' => $this->get_method_name()), '*', IGNORE_MISSING);
 651      }
 652  
 653      /**
 654       * Deletes all plugin data associated with the given form definiton
 655       *
 656       * @see delete_definition()
 657       */
 658      abstract protected function delete_plugin_definition();
 659  
 660      /**
 661       * Returns the name of the grading method plugin, eg 'rubric'
 662       *
 663       * @return string the name of the grading method plugin, eg 'rubric'
 664       * @see PARAM_PLUGIN
 665       */
 666      protected function get_method_name() {
 667          if (preg_match('/^gradingform_([a-z][a-z0-9_]*[a-z0-9])_controller$/', get_class($this), $matches)) {
 668              return $matches[1];
 669          } else {
 670              throw new coding_exception('Invalid class name');
 671          }
 672      }
 673  
 674      /**
 675       * Returns html code to be included in student's feedback.
 676       *
 677       * @param moodle_page $page
 678       * @param int $itemid
 679       * @param array $gradinginfo result of function grade_get_grades if plugin want to use some of their info
 680       * @param string $defaultcontent default string to be returned if no active grading is found or for some reason can not be shown to a user
 681       * @param boolean $cangrade whether current user has capability to grade in this context
 682       * @return string
 683       */
 684      public function render_grade($page, $itemid, $gradinginfo, $defaultcontent, $cangrade) {
 685          return $defaultcontent;
 686      }
 687  
 688      /**
 689       * Sets the range of grades used in this area. This is usually either range like 0-100
 690       * or the scale where keys start from 1.
 691       *
 692       * Typically modules will call it:
 693       * $controller->set_grade_range(make_grades_menu($gradingtype), $gradingtype > 0);
 694       * Negative $gradingtype means that scale is used and the grade must be rounded
 695       * to the nearest int. Positive $gradingtype means that range 0..$gradingtype
 696       * is used for the grades and in this case grade does not have to be rounded.
 697       *
 698       * Sometimes modules always expect grade to be rounded (like mod_assignment does).
 699       *
 700       * @param array $graderange array where first _key_ is the minimum grade and the
 701       *     last key is the maximum grade.
 702       * @param bool $allowgradedecimals if decimal values are allowed as grades.
 703       */
 704      public final function set_grade_range(array $graderange, $allowgradedecimals = false) {
 705          $this->graderange = $graderange;
 706          $this->allowgradedecimals = $allowgradedecimals;
 707      }
 708  
 709      /**
 710       * Returns the range of grades used in this area
 711       *
 712       * @return array
 713       */
 714      public final function get_grade_range() {
 715          if (empty($this->graderange)) {
 716              return array();
 717          }
 718          return $this->graderange;
 719      }
 720  
 721      /**
 722       * Returns if decimal values are allowed as grades
 723       *
 724       * @return bool
 725       */
 726      public final function get_allow_grade_decimals() {
 727          return $this->allowgradedecimals;
 728      }
 729  
 730      /**
 731       * Overridden by sub classes that wish to make definition details available to web services.
 732       * When not overridden, only definition data common to all grading methods is made available.
 733       * When overriding, the return value should be an array containing one or more key/value pairs.
 734       * These key/value pairs should match the definition returned by the get_definition() function.
 735       * For examples, look at:
 736       *    $gradingform_rubric_controller->get_external_definition_details()
 737       *    $gradingform_guide_controller->get_external_definition_details()
 738       * @return array An array of one or more key/value pairs containing the external_multiple_structure/s
 739       * corresponding to the definition returned by $controller->get_definition()
 740       * @since Moodle 2.5
 741       */
 742      public static function get_external_definition_details() {
 743          return null;
 744      }
 745  
 746      /**
 747       * Overridden by sub classes that wish to make instance filling details available to web services.
 748       * When not overridden, only instance filling data common to all grading methods is made available.
 749       * When overriding, the return value should be an array containing one or more key/value pairs.
 750       * These key/value pairs should match the filling data returned by the get_<method>_filling() function
 751       * in the gradingform_instance subclass.
 752       * For examples, look at:
 753       *    $gradingform_rubric_controller->get_external_instance_filling_details()
 754       *    $gradingform_guide_controller->get_external_instance_filling_details()
 755       *
 756       * @return array An array of one or more key/value pairs containing the external_multiple_structure/s
 757       * corresponding to the definition returned by $gradingform_<method>_instance->get_<method>_filling()
 758       * @since Moodle 2.6
 759       */
 760      public static function get_external_instance_filling_details() {
 761          return null;
 762      }
 763  }
 764  
 765  /**
 766   * Class to manage one gradingform instance.
 767   *
 768   * Gradingform instance is created for each evaluation of a student, using advanced grading.
 769   * It is stored as an entry in the DB table gradingform_instance.
 770   *
 771   * One instance (usually the latest) has the status INSTANCE_STATUS_ACTIVE. Sometimes it may
 772   * happen that a teacher wants to change the definition when some students have already been
 773   * graded. In this case their instances change status to INSTANCE_STATUS_NEEDUPDATE.
 774   *
 775   * To support future use of AJAX for background saving of incomplete evaluations the
 776   * status INSTANCE_STATUS_INCOMPLETE is introduced. If 'Cancel' is pressed this entry
 777   * is deleted.
 778   * When grade is updated the previous active instance receives status INSTANCE_STATUS_ACTIVE.
 779   *
 780   * Advanced grading plugins must declare a class gradingform_xxxx_instance
 781   * extending this class and put it in lib.php in the plugin folder.
 782   *
 783   * The reference to an instance of this class is passed to an advanced grading form element
 784   * included in the grading form, so this class must implement functions for rendering
 785   * and validation of this form element. See {@link MoodleQuickForm_grading}
 786   *
 787   * @package    core_grading
 788   * @copyright  2011 Marina Glancy
 789   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 790   * @category   grading
 791   */
 792  abstract class gradingform_instance {
 793      /** Valid istance status */
 794      const INSTANCE_STATUS_ACTIVE = 1;
 795      /** The grade needs to be updated by grader (usually because of changes is grading method) */
 796      const INSTANCE_STATUS_NEEDUPDATE = 2;
 797      /** The grader started grading but did clicked neither submit nor cancel */
 798      const INSTANCE_STATUS_INCOMPLETE = 0;
 799      /** Grader re-graded the student and this is the status for previous grade stored as history */
 800      const INSTANCE_STATUS_ARCHIVE = 3;
 801  
 802      /** @var stdClass record from table grading_instances */
 803      protected $data;
 804      /** @var gradingform_controller link to the corresponding controller */
 805      protected $controller;
 806  
 807      /**
 808       * Creates an instance
 809       *
 810       * @param gradingform_controller $controller
 811       * @param stdClass $data
 812       */
 813      public function __construct($controller, $data) {
 814          $this->data = (object)$data;
 815          $this->controller = $controller;
 816      }
 817  
 818      /**
 819       * Creates a new empty instance in DB and mark its status as INCOMPLETE
 820       *
 821       * @param int $definitionid
 822       * @param int $raterid
 823       * @param int $itemid
 824       * @return int id of the created instance
 825       */
 826      public static function create_new($definitionid, $raterid, $itemid) {
 827          global $DB;
 828          $instance = new stdClass();
 829          $instance->definitionid = $definitionid;
 830          $instance->raterid = $raterid;
 831          $instance->itemid = $itemid;
 832          $instance->status = self::INSTANCE_STATUS_INCOMPLETE;
 833          $instance->timemodified = time();
 834          $instance->feedbackformat = FORMAT_MOODLE;
 835          $instanceid = $DB->insert_record('grading_instances', $instance);
 836          return $instanceid;
 837      }
 838  
 839      /**
 840       * Duplicates the instance before editing (optionally substitutes raterid and/or itemid with
 841       * the specified values)
 842       * Plugins may want to override this function to copy data from additional tables as well
 843       *
 844       * @param int $raterid value for raterid in the duplicate
 845       * @param int $itemid value for itemid in the duplicate
 846       * @return int id of the new instance
 847       */
 848      public function copy($raterid, $itemid) {
 849          global $DB;
 850          $data = (array)$this->data; // Cast to array to make a copy
 851          unset($data['id']);
 852          $data['raterid'] = $raterid;
 853          $data['itemid'] = $itemid;
 854          $data['timemodified'] = time();
 855          $data['status'] = self::INSTANCE_STATUS_INCOMPLETE;
 856          $instanceid = $DB->insert_record('grading_instances', $data);
 857          return $instanceid;
 858      }
 859  
 860      /**
 861       * Returns the current (active or needupdate) instance for the same raterid and itemid as this
 862       * instance. This function is useful to find the status of the currently modified instance
 863       *
 864       * @return gradingform_instance
 865       */
 866      public function get_current_instance() {
 867          if ($this->get_status() == self::INSTANCE_STATUS_ACTIVE || $this->get_status() == self::INSTANCE_STATUS_NEEDUPDATE) {
 868              return $this;
 869          }
 870          return $this->get_controller()->get_current_instance($this->data->raterid, $this->data->itemid);
 871      }
 872  
 873      /**
 874       * Returns the controller
 875       *
 876       * @return gradingform_controller
 877       */
 878      public function get_controller() {
 879          return $this->controller;
 880      }
 881  
 882      /**
 883       * Returns the specified element from object $this->data
 884       *
 885       * @param string $key
 886       * @return mixed
 887       */
 888      public function get_data($key) {
 889          if (isset($this->data->$key)) {
 890              return $this->data->$key;
 891          }
 892          return null;
 893      }
 894  
 895      /**
 896       * Returns instance id
 897       *
 898       * @return int
 899       */
 900      public function get_id() {
 901          return $this->get_data('id');
 902      }
 903  
 904      /**
 905       * Returns instance status
 906       *
 907       * @return int
 908       */
 909      public function get_status() {
 910          return $this->get_data('status');
 911      }
 912  
 913      /**
 914       * Marks the instance as ACTIVE and current active instance (if exists) as ARCHIVE
 915       */
 916      protected function make_active() {
 917          global $DB;
 918          if ($this->data->status == self::INSTANCE_STATUS_ACTIVE) {
 919              // already active
 920              return;
 921          }
 922          if (empty($this->data->itemid)) {
 923              throw new coding_exception('You cannot mark active the grading instance without itemid');
 924          }
 925          $currentid = $this->get_controller()->get_current_instance($this->data->raterid, $this->data->itemid, true);
 926          if ($currentid && $currentid != $this->get_id()) {
 927              $DB->update_record('grading_instances', array('id' => $currentid, 'status' => self::INSTANCE_STATUS_ARCHIVE));
 928          }
 929          $DB->update_record('grading_instances', array('id' => $this->get_id(), 'status' => self::INSTANCE_STATUS_ACTIVE));
 930          $this->data->status = self::INSTANCE_STATUS_ACTIVE;
 931      }
 932  
 933      /**
 934       * Deletes this (INCOMPLETE) instance from database. This function is invoked on cancelling the
 935       * grading form and/or during cron cleanup.
 936       * Plugins using additional tables must override this method to remove additional data.
 937       * Note that if the teacher just closes the window or presses 'Back' button of the browser,
 938       * this function is not invoked.
 939       */
 940      public function cancel() {
 941          global $DB;
 942          // TODO MDL-31239 throw exception if status is not INSTANCE_STATUS_INCOMPLETE
 943          $DB->delete_records('grading_instances', array('id' => $this->get_id()));
 944      }
 945  
 946      /**
 947       * Updates the instance with the data received from grading form. This function may be
 948       * called via AJAX when grading is not yet completed, so it does not change the
 949       * status of the instance.
 950       *
 951       * @param array $elementvalue
 952       */
 953      public function update($elementvalue) {
 954          global $DB;
 955          $newdata = new stdClass();
 956          $newdata->id = $this->get_id();
 957          $newdata->timemodified = time();
 958          if (isset($elementvalue['itemid']) && $elementvalue['itemid'] != $this->data->itemid) {
 959              $newdata->itemid = $elementvalue['itemid'];
 960          }
 961          // TODO MDL-31087 also update: rawgrade, feedback, feedbackformat
 962          $DB->update_record('grading_instances', $newdata);
 963          foreach ($newdata as $key => $value) {
 964              $this->data->$key = $value;
 965          }
 966      }
 967  
 968      /**
 969       * Calculates the grade to be pushed to the gradebook
 970       *
 971       * Returned grade must be in range $this->get_controller()->get_grade_range()
 972       * Plugins must returned grade converted to int unless
 973       * $this->get_controller()->get_allow_grade_decimals() is true.
 974       *
 975       * @return float|int
 976       */
 977      abstract public function get_grade();
 978  
 979      /**
 980       * Determines whether the submitted form was empty.
 981       *
 982       * @param array $elementvalue value of element submitted from the form
 983       * @return boolean true if the form is empty
 984       */
 985      public function is_empty_form($elementvalue) {
 986          return false;
 987      }
 988  
 989      /**
 990       * Removes the attempt from the gradingform_*_fillings table.
 991       * This function is not abstract as to not break plugins that might
 992       * use advanced grading.
 993       * @param array $data the attempt data
 994       */
 995      public function clear_attempt($data) {
 996          // This function is empty because the way to clear a grade
 997          // attempt will be different depending on the grading method.
 998          return;
 999      }
1000  
1001      /**
1002       * Called when teacher submits the grading form:
1003       * updates the instance in DB, marks it as ACTIVE and returns the grade to be pushed to the gradebook.
1004       * $itemid must be specified here (it was not required when the instance was
1005       * created, because it might not existed in draft)
1006       *
1007       * @param array $elementvalue
1008       * @param int $itemid
1009       * @return int the grade on 0-100 scale
1010       */
1011      public function submit_and_get_grade($elementvalue, $itemid) {
1012          $elementvalue['itemid'] = $itemid;
1013          if ($this->is_empty_form($elementvalue)) {
1014              $this->clear_attempt($elementvalue);
1015              $this->make_active();
1016              return -1;
1017          }
1018          $this->update($elementvalue);
1019          $this->make_active();
1020          return $this->get_grade();
1021      }
1022  
1023      /**
1024       * Returns html for form element of type 'grading'. If there is a form input element
1025       * it must have the name $gradingformelement->getName().
1026       * If there are more than one input elements they MUST be elements of array with
1027       * name $gradingformelement->getName().
1028       * Example: {NAME}[myelement1], {NAME}[myelement2][sub1], {NAME}[myelement2][sub2], etc.
1029       * ( {NAME} is a shortcut for $gradingformelement->getName() )
1030       * After submitting the form the value of $_POST[{NAME}] is passed to the functions
1031       * validate_grading_element() and submit_and_get_grade()
1032       *
1033       * Plugins may use $gradingformelement->getValue() to get the value passed on previous
1034       * form submit
1035       *
1036       * When forming html it is a plugin's responsibility to analyze flags
1037       * $gradingformelement->_flagFrozen and $gradingformelement->_persistantFreeze:
1038       *
1039       * (_flagFrozen == false) => form element is editable
1040       *
1041       * (_flagFrozen == false && _persistantFreeze == true) => form element is not editable
1042       * but all values are passed as hidden elements
1043       *
1044       * (_flagFrozen == false && _persistantFreeze == false) => form element is not editable
1045       * and no values are passed as hidden elements
1046       *
1047       * Plugins are welcome to use AJAX in the form element. But it is strongly recommended
1048       * that the grading only becomes active when teacher presses 'Submit' button (the
1049       * method submit_and_get_grade() is invoked)
1050       *
1051       * Also client-side JS validation may be implemented here
1052       *
1053       * @see MoodleQuickForm_grading in lib/form/grading.php
1054       *
1055       * @param moodle_page $page
1056       * @param MoodleQuickForm_grading $gradingformelement
1057       * @return string
1058       */
1059      abstract function render_grading_element($page, $gradingformelement);
1060  
1061      /**
1062       * Server-side validation of the data received from grading form.
1063       *
1064       * @param mixed $elementvalue is the scalar or array received in $_POST
1065       * @return boolean true if the form data is validated and contains no errors
1066       */
1067      public function validate_grading_element($elementvalue) {
1068          return true;
1069      }
1070  
1071      /**
1072       * Returns the error message displayed if validation failed.
1073       * If plugin wants to display custom message, the empty string should be returned here
1074       * and the custom message should be output in render_grading_element()
1075       *
1076       * Please note that in assignments grading in 2.2 the grading form is not validated
1077       * properly and this message is not being displayed.
1078       *
1079       * @see validate_grading_element()
1080       * @return string
1081       */
1082      public function default_validation_error_message() {
1083          return '';
1084      }
1085  }