Replaced deprecated get_system_context() with the new context_system::instance()
[moodle.git] / grade / grading / form / lib.php
CommitLineData
9b8550f8
DM
1<?php
2
3// This file is part of Moodle - http://moodle.org/
4//
5// Moodle is free software: you can redistribute it and/or modify
6// it under the terms of the GNU General Public License as published by
7// the Free Software Foundation, either version 3 of the License, or
8// (at your option) any later version.
9//
10// Moodle is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU General Public License for more details.
14//
15// You should have received a copy of the GNU General Public License
16// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
17
18/**
21d37aa6
DM
19 * Common classes used by gradingform plugintypes are defined here
20 *
9b8550f8
DM
21 * @package core
22 * @subpackage grading
23 * @copyright 2011 David Mudrak <david@moodle.com>
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
26
27defined('MOODLE_INTERNAL') || die();
28
29/**
21d37aa6 30 * Grading method controller represents a plugin used in a particular area
9b8550f8 31 */
3e43eff5 32abstract class gradingform_controller {
9b8550f8 33
7622ae95
DM
34 /** undefined definition status */
35 const DEFINITION_STATUS_NULL = 0;
36 /** the form is currently being edited and is not ready for usage yet */
37 const DEFINITION_STATUS_DRAFT = 10;
38 /** the for was marked as ready for actual usage */
39 const DEFINITION_STATUS_READY = 20;
21d37aa6 40
9b8550f8
DM
41 /** @var stdClass the context */
42 protected $context;
43
44 /** @var string the frankenstyle name of the component */
45 protected $component;
46
47 /** @var string the name of the gradable area */
48 protected $area;
49
50 /** @var int the id of the gradable area record */
51 protected $areaid;
52
fe817d87 53 /** @var stdClass|false the definition structure */
5060997b 54 protected $definition = false;
3e43eff5 55
9e2eca0f
MG
56 /** @var array graderange array of valid grades for this area. Use set_grade_range and get_grade_range to access this */
57 private $graderange = null;
58
9b8550f8
DM
59 /**
60 * Do not instantinate this directly, use {@link grading_manager::get_controller()}
61 *
fe817d87
DM
62 * @param stdClass $context the context of the form
63 * @param string $component the frankenstyle name of the component
64 * @param string $area the name of the gradable area
65 * @param int $areaid the id of the gradable area record
9b8550f8
DM
66 */
67 public function __construct(stdClass $context, $component, $area, $areaid) {
3e43eff5
DM
68 global $DB;
69
70 $this->context = $context;
fe817d87
DM
71 list($type, $name) = normalize_component($component);
72 $this->component = $type.'_'.$name;
3e43eff5
DM
73 $this->area = $area;
74 $this->areaid = $areaid;
75
76 $this->load_definition();
77 }
78
fe817d87
DM
79 /**
80 * @return stdClass controller context
81 */
82 public function get_context() {
83 return $this->context;
84 }
85
86 /**
87 * @return string gradable component name
88 */
89 public function get_component() {
90 return $this->component;
91 }
92
93 /**
94 * @return string gradable area name
95 */
96 public function get_area() {
97 return $this->area;
98 }
99
100 /**
101 * @return int gradable area id
102 */
103 public function get_areaid() {
104 return $this->areaid;
105 }
106
6832a102
DM
107 /**
108 * Is the form definition record available?
109 *
110 * Note that this actually checks whether the process of defining the form ever started
111 * and not whether the form definition should be considered as final.
112 *
113 * @return boolean
114 */
115 public function is_form_defined() {
5060997b 116 return ($this->definition !== false);
6832a102
DM
117 }
118
3e43eff5 119 /**
7622ae95 120 * Is the grading form defined and ready for usage?
3e43eff5
DM
121 *
122 * @return boolean
123 */
7622ae95 124 public function is_form_available() {
3599b113 125 return ($this->is_form_defined() && $this->definition->status == self::DEFINITION_STATUS_READY);
3e43eff5
DM
126 }
127
967d346f
DM
128 /**
129 * Is the grading form saved as a shared public template?
130 *
131 * @return boolean
132 */
133 public function is_shared_template() {
134 return ($this->get_context()->id == context_system::instance()->id
135 and $this->get_component() == 'core_grading');
136 }
137
138 /**
139 * Is the grading form owned by the given user?
140 *
141 * The form owner is the user who created this instance of the form.
142 *
143 * @param int $userid the user id to check, defaults to the current user
144 * @return boolean|null null if the form not defined yet, boolean otherwise
145 */
146 public function is_own_form($userid = null) {
147 global $USER;
148
149 if (!$this->is_form_defined()) {
150 return null;
151 }
152 if (is_null($userid)) {
153 $userid = $USER->id;
154 }
155 return ($this->definition->usercreated == $userid);
156 }
157
2ae7faf1
MG
158 /**
159 * Returns a message why this form is unavailable. Maybe overriden by plugins to give more details.
160 * @see is_form_available()
161 *
162 * @return string
163 */
164 public function form_unavailable_notification() {
165 if ($this->is_form_available()) {
166 return null;
167 }
0e2a1d75 168 return get_string('gradingformunavailable', 'grading');
2ae7faf1
MG
169 }
170
6832a102
DM
171 /**
172 * Returns URL of a page where the grading form can be defined and edited.
173 *
174 * @param moodle_url $returnurl optional URL of a page where the user should be sent once they are finished with editing
175 * @return moodle_url
176 */
177 public function get_editor_url(moodle_url $returnurl = null) {
178
179 $params = array('areaid' => $this->areaid);
180
181 if (!is_null($returnurl)) {
182 $params['returnurl'] = $returnurl->out(false);
183 }
184
185 return new moodle_url('/grade/grading/form/'.$this->get_method_name().'/edit.php', $params);
186 }
187
9b8550f8
DM
188 /**
189 * Extends the module settings navigation
190 *
191 * This function is called when the context for the page is an activity module with the
192 * FEATURE_ADVANCED_GRADING, the user has the permission moodle/grade:managegradingforms
193 * and there is an area with the active grading method set to the given plugin.
194 *
195 * @param settings_navigation $settingsnav {@link settings_navigation}
196 * @param navigation_node $node {@link navigation_node}
197 */
198 public function extend_settings_navigation(settings_navigation $settingsnav, navigation_node $node=null) {
199 // do not extend by default
200 }
3e43eff5
DM
201
202 /**
fe817d87 203 * Returns the grading form definition structure
3e43eff5 204 *
9e2eca0f 205 * @param boolean $force whether to force loading from DB even if it was already loaded
fe817d87 206 * @return stdClass|false definition data or false if the form is not defined yet
3e43eff5 207 */
9e2eca0f 208 public function get_definition($force = false) {
5060997b 209 if ($this->definition === false || $force) {
fe817d87
DM
210 $this->load_definition();
211 }
212 return $this->definition;
3e43eff5
DM
213 }
214
fde33804
DM
215 /**
216 * Returns the form definition suitable for cloning into another area
217 *
218 * @param gradingform_controller $target the controller of the new copy
219 * @return stdClass definition structure to pass to the target's {@link update_definition()}
220 */
221 public function get_definition_copy(gradingform_controller $target) {
222
223 if (get_class($this) != get_class($target)) {
224 throw new coding_exception('The source and copy controller mismatch');
225 }
226
227 if ($target->is_form_defined()) {
228 throw new coding_exception('The target controller already contains a form definition');
229 }
230
231 $old = $this->get_definition();
232 // keep our id
233 $new = new stdClass();
234 $new->copiedfromid = $old->id;
235 $new->name = $old->name;
236 // once we support files embedded into the description, we will want to
237 // relink them into the new file area here (that is why we accept $target)
238 $new->description = $old->description;
239 $new->descriptionformat = $old->descriptionformat;
240 $new->options = $old->options;
3599b113 241 $new->status = $old->status;
fde33804
DM
242
243 return $new;
244 }
245
3e43eff5 246 /**
fe817d87 247 * Saves the defintion data into the database
21d37aa6 248 *
fe817d87
DM
249 * The implementation in this base class stores the common data into the record
250 * into the {grading_definition} table. The plugins are likely to extend this
251 * and save their data into own tables, too.
21d37aa6 252 *
fe817d87
DM
253 * @param stdClass $definition data containing values for the {grading_definition} table
254 * @param int|null $usermodified optional userid of the author of the definition, defaults to the current user
21d37aa6 255 */
3599b113 256 public function update_definition(stdClass $definition, $usermodified = null) {
21d37aa6
DM
257 global $DB, $USER;
258
259 if (is_null($usermodified)) {
260 $usermodified = $USER->id;
261 }
262
fe817d87
DM
263 if (!empty($this->definition->id)) {
264 // prepare a record to be updated
265 $record = new stdClass();
266 // populate it with scalar values from the passed definition structure
267 foreach ($definition as $prop => $val) {
268 if (is_array($val) or is_object($val)) {
269 // probably plugin's data
270 continue;
271 }
272 $record->{$prop} = $val;
273 }
274 // make sure we do not override some crucial values by accident
275 if (!empty($record->id) and $record->id != $this->definition->id) {
276 throw new coding_exception('Attempting to update other definition record.');
277 }
278 $record->id = $this->definition->id;
279 unset($record->areaid);
280 unset($record->method);
281 unset($record->timecreated);
282 // set the modification flags
283 $record->timemodified = time();
284 $record->usermodified = $usermodified;
21d37aa6 285
fe817d87 286 $DB->update_record('grading_definitions', $record);
21d37aa6
DM
287
288 } else if ($this->definition === false) {
fe817d87
DM
289 // prepare a record to be inserted
290 $record = new stdClass();
291 // populate it with scalar values from the passed definition structure
292 foreach ($definition as $prop => $val) {
293 if (is_array($val) or is_object($val)) {
294 // probably plugin's data
295 continue;
296 }
297 $record->{$prop} = $val;
298 }
299 // make sure we do not override some crucial values by accident
300 if (!empty($record->id)) {
301 throw new coding_exception('Attempting to create a new record while there is already one existing.');
302 }
303 unset($record->id);
304 $record->areaid = $this->areaid;
305 $record->method = $this->get_method_name();
306 $record->timecreated = time();
307 $record->usercreated = $usermodified;
ac16cedf
DM
308 $record->timemodified = $record->timecreated;
309 $record->usermodified = $record->usercreated;
3599b113 310 if (empty($record->status)) {
7622ae95
DM
311 $record->status = self::DEFINITION_STATUS_DRAFT;
312 }
3599b113
MG
313 if (empty($record->descriptionformat)) {
314 $record->descriptionformat = FORMAT_MOODLE; // field can not be empty
315 }
21d37aa6 316
ac16cedf 317 $DB->insert_record('grading_definitions', $record);
21d37aa6
DM
318
319 } else {
fe817d87 320 throw new coding_exception('Unknown status of the cached definition record.');
21d37aa6
DM
321 }
322 }
323
3599b113
MG
324 /**
325 * Formats the definition description for display on page
326 *
327 * @return string
328 */
329 public function get_formatted_description() {
330 if (!isset($this->definition->description)) {
331 return '';
332 }
333 return format_text($this->definition->description, $this->definition->descriptionformat);
334 }
335
21d37aa6 336 /**
36937f02
MG
337 * Returns the ACTIVE instance for this definition for the specified $raterid and $itemid
338 * (if multiple raters are allowed, or only for $itemid otherwise).
21d37aa6 339 *
21d37aa6
DM
340 * @param int $raterid
341 * @param int $itemid
36937f02
MG
342 * @param boolean $idonly
343 * @return mixed if $idonly=true returns id of the found instance, otherwise returns the instance object
21d37aa6 344 */
36937f02 345 public function get_current_instance($raterid, $itemid, $idonly = false) {
21d37aa6 346 global $DB;
36937f02
MG
347 $select = array(
348 'formid' => $this->definition->id,
349 'itemid' => $itemid,
350 'status' => gradingform_instance::INSTANCE_STATUS_ACTIVE);
351 if (false /* TODO $manager->allow_multiple_raters() */) {
352 $select['raterid'] = $raterid;
21d37aa6 353 }
36937f02
MG
354 if ($idonly) {
355 if ($current = $DB->get_record('grading_instances', $select, 'id', IGNORE_MISSING)) {
356 return $current->id;
357 }
21d37aa6 358 } else {
36937f02
MG
359 if ($current = $DB->get_record('grading_instances', $select, '*', IGNORE_MISSING)) {
360 return $this->get_instance($current);
361 }
21d37aa6 362 }
36937f02 363 return null;
21d37aa6
DM
364 }
365
18e6298c 366 /**
36937f02
MG
367 * Returns list of active instances for the specified $itemid
368 *
369 * @param int $itemid
370 * @return array of gradingform_instance objects
18e6298c 371 */
36937f02
MG
372 public function get_current_instances($itemid) {
373 global $DB;
374 $conditions = array('formid' => $this->definition->id,
375 'itemid' => $itemid,
376 'status' => gradingform_instance::INSTANCE_STATUS_ACTIVE);
377 $records = $DB->get_recordset('grading_instances', $conditions);
378 $rv = array();
379 foreach ($records as $record) {
380 $rv[] = $this->get_instance($record);
381 }
382 return $rv;
383 }
6798c63e
MG
384
385 /**
36937f02 386 * Returns the object of type gradingform_XXX_instance (where XXX is the plugin method name)
6798c63e 387 *
36937f02
MG
388 * @param mixed $instance id or row from grading_isntances table
389 * @return gradingform_instance
6798c63e 390 */
36937f02
MG
391 protected function get_instance($instance) {
392 global $DB;
393 if (is_scalar($instance)) {
394 // instance id is passed as parameter
395 $instance = $DB->get_record('grading_instances', array('id' => $instance), '*', MUST_EXIST);
396 }
397 if ($instance) {
398 $class = 'gradingform_'. $this->get_method_name(). '_instance';
399 return new $class($this, $instance);
400 }
401 return null;
6798c63e
MG
402 }
403
404 /**
36937f02
MG
405 * This function is invoked when user (teacher) starts grading.
406 * It creates and returns copy of the current ACTIVE instance if it exists. If this is the
407 * first grading attempt, a new instance is created.
408 * The status of the returned instance is INCOMPLETE
6798c63e 409 *
36937f02
MG
410 * @param int $raterid
411 * @param int $itemid
412 * @return gradingform_instance
6798c63e 413 */
fc05f222 414 public function create_instance($raterid, $itemid = null) {
36937f02
MG
415 global $DB;
416 // first find if there is already an active instance for this itemid
fc05f222 417 if ($itemid && $current = $this->get_current_instance($raterid, $itemid)) {
36937f02
MG
418 return $this->get_instance($current->copy($raterid, $itemid));
419 } else {
420 $class = 'gradingform_'. $this->get_method_name(). '_instance';
421 return $this->get_instance($class::create_new($this->definition->id, $raterid, $itemid));
422 }
6798c63e 423 }
18e6298c 424
ab156741 425 /**
6832a102 426 * Returns the HTML code displaying the preview of the grading form
ab156741 427 *
20836db9 428 * Plugins are forced to override this. Ideally they should delegate
6832a102
DM
429 * the task to their own renderer.
430 *
431 * @param moodle_page $page the target page
432 * @return string
ab156741 433 */
20836db9 434 abstract public function render_preview(moodle_page $page);
ab156741 435
671ec8f5
DM
436 /**
437 * Deletes the form definition and all the associated data
438 *
439 * @see delete_plugin_definition()
440 * @return void
441 */
442 public function delete_definition() {
443 global $DB;
444
445 if (!$this->is_form_defined()) {
446 // nothing to do
447 return;
448 }
fe817d87 449
671ec8f5
DM
450 // firstly, let the plugin delete everything from their own tables
451 $this->delete_plugin_definition();
452 // then, delete all instances left
453 $DB->delete_records('grading_instances', array('formid' => $this->definition->id));
454 // finally, delete the main definition record
455 $DB->delete_records('grading_definitions', array('id' => $this->definition->id));
456
457 $this->definition = false;
458 }
459
20836db9
DM
460 /**
461 * Prepare the part of the search query to append to the FROM statement
462 *
463 * @param string $gdid the alias of grading_definitions.id column used by the caller
464 * @return string
465 */
466 public static function sql_search_from_tables($gdid) {
467 return '';
468 }
469
470 /**
471 * Prepare the parts of the SQL WHERE statement to search for the given token
472 *
473 * The returned array cosists of the list of SQL comparions and the list of
474 * respective parameters for the comparisons. The returned chunks will be joined
475 * with other conditions using the OR operator.
476 *
477 * @param string $token token to search for
478 * @return array
479 */
480 public static function sql_search_where($token) {
481 global $DB;
482
483 $subsql = array();
484 $params = array();
485
486 return array($subsql, $params);
487 }
488
671ec8f5 489 ////////////////////////////////////////////////////////////////////////////
fe817d87 490
21d37aa6
DM
491 /**
492 * Loads the form definition if it exists
3e43eff5 493 *
21d37aa6 494 * The default implementation just tries to load the record from the {grading_definitions}
3e43eff5
DM
495 * table. The plugins are likely to override this with a more complex query that loads
496 * all required data at once.
497 */
498 protected function load_definition() {
499 global $DB;
3e43eff5
DM
500 $this->definition = $DB->get_record('grading_definitions', array(
501 'areaid' => $this->areaid,
502 'method' => $this->get_method_name()), '*', IGNORE_MISSING);
503 }
21d37aa6 504
671ec8f5
DM
505 /**
506 * Deletes all plugin data associated with the given form definiton
507 *
508 * @see delete_definition()
509 */
510 abstract protected function delete_plugin_definition();
511
21d37aa6 512 /**
fe817d87
DM
513 * @return string the name of the grading method plugin, eg 'rubric'
514 * @see PARAM_PLUGIN
21d37aa6 515 */
fe817d87
DM
516 protected function get_method_name() {
517 if (preg_match('/^gradingform_([a-z][a-z0-9_]*[a-z0-9])_controller$/', get_class($this), $matches)) {
518 return $matches[1];
519 } else {
520 throw new coding_exception('Invalid class name');
521 }
21d37aa6 522 }
36937f02
MG
523
524 /**
525 * Returns html code to be included in student's feedback.
526 *
527 * @param moodle_page $page
528 * @param int $itemid
9e2eca0f
MG
529 * @param array $grading_info result of function grade_get_grades if plugin want to use some of their info
530 * @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
36937f02
MG
531 * @return string
532 */
9e2eca0f 533 public function render_grade($page, $itemid, $grading_info, $defaultcontent) {
36937f02
MG
534 return $defaultcontent;
535 }
9e2eca0f
MG
536
537 /**
538 * Sets the range of grades used in this area. This is usually either range like 0-100
539 * or the scale where keys start from 1. Typical use:
540 * $controller->set_grade_range(make_grades_menu($gradingtype));
541 */
542 public final function set_grade_range(array $graderange) {
543 $this->graderange = $graderange;
544 }
545
546 /**
547 * Returns the range of grades used in this area
548 * @return array
549 */
550 public final function get_grade_range() {
551 if (empty($this->graderange)) {
552 return array();
553 }
554 return $this->graderange;
555 }
21d37aa6 556}
36937f02
MG
557
558/**
559 * Class to manage one grading instance. Stores information and performs actions like
560 * update, copy, validate, submit, etc.
561 *
562 * @copyright 2011 Marina Glancy
563 */
564abstract class gradingform_instance {
565 const INSTANCE_STATUS_ACTIVE = 1;
566 const INSTANCE_STATUS_INCOMPLETE = 0;
567 const INSTANCE_STATUS_ARCHIVE = 3;
568
569 /** @var stdClass record from table grading_instances */
570 protected $data;
571 /** @var gradingform_controller link to the corresponding controller */
572 protected $controller;
573
574 /**
575 * Creates an instance
576 *
577 * @param gradingform_controller $controller
578 * @param stdClass $data
579 */
580 public function __construct($controller, $data) {
581 $this->data = (object)$data;
582 $this->controller = $controller;
583 }
584
585 /**
586 * Creates a new empty instance in DB and mark its status as INCOMPLETE
587 *
588 * @param int $formid
589 * @param int $raterid
590 * @param int $itemid
591 * @return int id of the created instance
592 */
593 public static function create_new($formid, $raterid, $itemid) {
594 global $DB;
595 $instance = new stdClass();
596 $instance->formid = $formid;
597 $instance->raterid = $raterid;
598 $instance->itemid = $itemid;
599 $instance->status = self::INSTANCE_STATUS_INCOMPLETE;
600 $instance->timemodified = time();
601 $instance->feedbackformat = FORMAT_MOODLE;
602 $instanceid = $DB->insert_record('grading_instances', $instance);
603 return $instanceid;
604 }
605
606 /**
607 * Duplicates the instance before editing (optionally substitutes raterid and/or itemid with
608 * the specified values)
609 * Plugins may want to override this function to copy data from additional tables as well
610 *
611 * @param int $raterid value for raterid in the duplicate
612 * @param int $itemid value for itemid in the duplicate
613 * @return int id of the new instance
614 */
615 public function copy($raterid, $itemid) {
616 global $DB;
617 $data = (array)$this->data; // Cast to array to make a copy
618 unset($data['id']);
619 $data['raterid'] = $raterid;
620 $data['itemid'] = $itemid;
621 $data['timemodified'] = time();
622 $data['status'] = self::INSTANCE_STATUS_INCOMPLETE;
623 $instanceid = $DB->insert_record('grading_instances', $data);
624 return $instanceid;
625 }
626
627 /**
628 * Returns the controller
629 *
630 * @return gradingform_controller
631 */
632 public function get_controller() {
633 return $this->controller;
634 }
635
636 /**
637 * Returns instance id
638 *
639 * @return int
640 */
641 public function get_id() {
642 return $this->data->id;
643 }
644
645 /**
646 * Marks the instance as ACTIVE and current active instance (if exists) as ARCHIVE
647 */
648 protected function make_active() {
649 global $DB;
650 if ($this->data->status == self::INSTANCE_STATUS_ACTIVE) {
651 // already active
652 return;
653 }
fc05f222
MG
654 if (empty($this->data->itemid)) {
655 throw new coding_exception('You cannot mark active the grading instance without itemid');
656 }
36937f02
MG
657 $currentid = $this->get_controller()->get_current_instance($this->data->raterid, $this->data->itemid, true);
658 if ($currentid) {
659 if ($currentid != $this->get_id()) {
660 $DB->update_record('grading_instances', array('id' => $currentid, 'status' => self::INSTANCE_STATUS_ARCHIVE));
661 $DB->update_record('grading_instances', array('id' => $this->get_id(), 'status' => self::INSTANCE_STATUS_ACTIVE));
662 }
663 } else {
664 $DB->update_record('grading_instances', array('id' => $this->get_id(), 'status' => self::INSTANCE_STATUS_ACTIVE));
665 }
666 $this->data->status = self::INSTANCE_STATUS_ACTIVE;
667 }
668
669 /**
670 * Deletes this (INCOMPLETE) instance from database. This function is invoked on cancelling the
671 * grading form and/or during cron cleanup.
672 * Plugins using additional tables must override this method to remove additional data.
673 * Note that if the teacher just closes the window or presses 'Back' button of the browser,
674 * this function is not invoked.
675 */
676 public function cancel() {
677 global $DB;
678 // TODO what if we happen delete the ACTIVE instance, shall we rollback to the last ARCHIVE? or throw an exception?
679 // TODO create cleanup cron
680 $DB->delete_records('grading_instances', array('id' => $this->get_id()));
681 }
682
683 /**
684 * Updates the instance with the data received from grading form. This function may be
685 * called via AJAX when grading is not yet completed, so it does not change the
686 * status of the instance.
fc05f222
MG
687 *
688 * @param array $elementvalue
36937f02
MG
689 */
690 public function update($elementvalue) {
fc05f222
MG
691 global $DB;
692 $newdata = new stdClass();
693 $newdata->id = $this->get_id();
694 $newdata->timemodified = time();
695 if (isset($elementvalue['itemid']) && $elementvalue['itemid'] != $this->data->itemid) {
696 $newdata->itemid = $elementvalue['itemid'];
697 }
698 // TODO also update: rawgrade, feedback, feedbackformat
699 $DB->update_record('grading_instances', $newdata);
700 foreach ($newdata as $key => $value) {
701 $this->data->$key = $value;
702 }
36937f02
MG
703 }
704
705 /**
706 * Calculates the grade to be pushed to the gradebook
9e2eca0f
MG
707 *
708 * @return int the valid grade from $this->get_controller()->get_grade_range()
36937f02
MG
709 */
710 abstract public function get_grade();
711
712 /**
713 * Called when teacher submits the grading form:
fc05f222
MG
714 * updates the instance in DB, marks it as ACTIVE and returns the grade to be pushed to the gradebook.
715 * $itemid must be specified here (it was not required when the instance was
716 * created, because it might not existed in draft)
717 *
718 * @param array $elementvalue
719 * @param int $itemid
36937f02
MG
720 * @return int the grade on 0-100 scale
721 */
fc05f222
MG
722 public function submit_and_get_grade($elementvalue, $itemid) {
723 $elementvalue['itemid'] = $itemid;
36937f02
MG
724 $this->update($elementvalue);
725 $this->make_active();
726 return $this->get_grade();
727 }
728
729
730 /**
731 * Returns html for form element of type 'grading'. If there is a form input element
732 * it must have the name $gradingformelement->getName().
733 * If there are more than one input elements they MUST be elements of array with
734 * name $gradingformelement->getName().
735 * Example: {NAME}[myelement1], {NAME}[myelement2][sub1], {NAME}[myelement2][sub2], etc.
9e2eca0f 736 * ( {NAME} is a shortcut for $gradingformelement->getName() )
36937f02
MG
737 * After submitting the form the value of $_POST[{NAME}] is passed to the functions
738 * validate_grading_element() and submit_and_get_grade()
739 *
740 * Plugins may use $gradingformelement->getValue() to get the value passed on previous
9e2eca0f 741 * form submit
36937f02
MG
742 *
743 * When forming html it is a plugin's responsibility to analyze flags
744 * $gradingformelement->_flagFrozen and $gradingformelement->_persistantFreeze:
745 *
746 * (_flagFrozen == false) => form element is editable
747 *
748 * (_flagFrozen == false && _persistantFreeze == true) => form element is not editable
749 * but all values are passed as hidden elements
750 *
751 * (_flagFrozen == false && _persistantFreeze == false) => form element is not editable
752 * and no values are passed as hidden elements
753 *
754 * Plugins are welcome to use AJAX in the form element. But it is strongly recommended
755 * that the grading only becomes active when teacher presses 'Submit' button (the
756 * method submit_and_get_grade() is invoked)
757 *
758 * Also client-side JS validation may be implemented here
759 *
760 * @see MoodleQuickForm_grading in lib/form/grading.php
761 *
762 * @param moodle_page $page
763 * @param MoodleQuickForm_grading $gradingformelement
764 * @return string
765 */
766 abstract function render_grading_element($page, $gradingformelement);
767
768 /**
769 * Server-side validation of the data received from grading form.
770 *
771 * @param mixed $elementvalue is the scalar or array received in $_POST
772 * @return boolean true if the form data is validated and contains no errors
773 */
774 public function validate_grading_element($elementvalue) {
775 return true;
776 }
777
778 /**
779 * Returns the error message displayed if validation failed.
780 * If plugin wants to display custom message, the empty string should be returned here
781 * and the custom message should be output in render_grading_element()
782 *
783 * @see validate_grading_element()
784 * @return string
785 */
786 public function default_validation_error_message() {
787 return '';
788 }
789}