Search moodle.org's
Developer Documentation
Developer Documentation
- Bug fixes for general core bugs in 4.2.x will end 22 April 2024 (12 months).
- Bug fixes for security issues in 4.2.x will end 7 October 2024 (18 months).
- PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.1.x is supported too.
/grade/grading/form/ -> lib.php (source)
Differences Between: [Versions 310 and 402] [Versions 311 and 402] [Versions 39 and 402] [Versions 400 and 402] [Versions 401 and 402]
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_assign 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 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
