on-demand release 4.0dev+
[moodle.git] / grade / grading / form / lib.php
CommitLineData
9b8550f8 1<?php
9b8550f8
DM
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/**
21d37aa6
DM
18 * Common classes used by gradingform plugintypes are defined here
19 *
d22e9e32 20 * @package core_grading
9b8550f8
DM
21 * @copyright 2011 David Mudrak <david@moodle.com>
22 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23 */
24
25defined('MOODLE_INTERNAL') || die();
26
27/**
d22e9e32
MG
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 *
5dc1ca87 44 * @package core_grading
d22e9e32
MG
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
9b8550f8 48 */
3e43eff5 49abstract class gradingform_controller {
9b8550f8 50
7622ae95
DM
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;
d22e9e32 55 /** the form was marked as ready for actual usage */
7622ae95 56 const DEFINITION_STATUS_READY = 20;
21d37aa6 57
9b8550f8
DM
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
fe817d87 70 /** @var stdClass|false the definition structure */
5060997b 71 protected $definition = false;
3e43eff5 72
9e2eca0f
MG
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
170f6e60
MG
76 /** @var bool if decimal values are allowed as grades. */
77 private $allowgradedecimals = false;
78
0136124e
MG
79 /** @var boolean|null cached result of function has_active_instances() */
80 protected $hasactiveinstances = null;
81
9b8550f8
DM
82 /**
83 * Do not instantinate this directly, use {@link grading_manager::get_controller()}
84 *
fe817d87
DM
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
9b8550f8
DM
89 */
90 public function __construct(stdClass $context, $component, $area, $areaid) {
3e43eff5
DM
91 global $DB;
92
93 $this->context = $context;
56da374e 94 list($type, $name) = core_component::normalize_component($component);
fe817d87 95 $this->component = $type.'_'.$name;
3e43eff5
DM
96 $this->area = $area;
97 $this->areaid = $areaid;
98
99 $this->load_definition();
100 }
101
fe817d87 102 /**
d22e9e32
MG
103 * Returns controller context
104 *
fe817d87
DM
105 * @return stdClass controller context
106 */
107 public function get_context() {
108 return $this->context;
109 }
110
111 /**
d22e9e32
MG
112 * Returns gradable component name
113 *
fe817d87
DM
114 * @return string gradable component name
115 */
116 public function get_component() {
117 return $this->component;
118 }
119
120 /**
d22e9e32
MG
121 * Returns gradable area name
122 *
fe817d87
DM
123 * @return string gradable area name
124 */
125 public function get_area() {
126 return $this->area;
127 }
128
129 /**
d22e9e32
MG
130 * Returns gradable area id
131 *
fe817d87
DM
132 * @return int gradable area id
133 */
134 public function get_areaid() {
135 return $this->areaid;
136 }
137
6832a102
DM
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() {
5060997b 147 return ($this->definition !== false);
6832a102
DM
148 }
149
3e43eff5 150 /**
7622ae95 151 * Is the grading form defined and ready for usage?
3e43eff5
DM
152 *
153 * @return boolean
154 */
7622ae95 155 public function is_form_available() {
3599b113 156 return ($this->is_form_defined() && $this->definition->status == self::DEFINITION_STATUS_READY);
3e43eff5
DM
157 }
158
967d346f
DM
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
2ae7faf1
MG
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 }
0e2a1d75 199 return get_string('gradingformunavailable', 'grading');
2ae7faf1
MG
200 }
201
6832a102
DM
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
9b8550f8
DM
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 }
3e43eff5 232
577c8964
MG
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
3e43eff5 246 /**
fe817d87 247 * Returns the grading form definition structure
3e43eff5 248 *
9e2eca0f 249 * @param boolean $force whether to force loading from DB even if it was already loaded
fe817d87 250 * @return stdClass|false definition data or false if the form is not defined yet
3e43eff5 251 */
9e2eca0f 252 public function get_definition($force = false) {
5060997b 253 if ($this->definition === false || $force) {
fe817d87
DM
254 $this->load_definition();
255 }
256 return $this->definition;
3e43eff5
DM
257 }
258
fde33804
DM
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;
3599b113 285 $new->status = $old->status;
fde33804
DM
286
287 return $new;
288 }
289
3e43eff5 290 /**
fe817d87 291 * Saves the defintion data into the database
21d37aa6 292 *
fe817d87
DM
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.
21d37aa6 296 *
fe817d87
DM
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
21d37aa6 299 */
3599b113 300 public function update_definition(stdClass $definition, $usermodified = null) {
21d37aa6
DM
301 global $DB, $USER;
302
303 if (is_null($usermodified)) {
304 $usermodified = $USER->id;
305 }
306
fe817d87
DM
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;
21d37aa6 329
fe817d87 330 $DB->update_record('grading_definitions', $record);
21d37aa6
DM
331
332 } else if ($this->definition === false) {
fe817d87
DM
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;
ac16cedf
DM
352 $record->timemodified = $record->timecreated;
353 $record->usermodified = $record->usercreated;
3599b113 354 if (empty($record->status)) {
7622ae95
DM
355 $record->status = self::DEFINITION_STATUS_DRAFT;
356 }
3599b113
MG
357 if (empty($record->descriptionformat)) {
358 $record->descriptionformat = FORMAT_MOODLE; // field can not be empty
359 }
21d37aa6 360
ac16cedf 361 $DB->insert_record('grading_definitions', $record);
21d37aa6
DM
362
363 } else {
fe817d87 364 throw new coding_exception('Unknown status of the cached definition record.');
21d37aa6
DM
365 }
366 }
367
3599b113
MG
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
21d37aa6 380 /**
0136124e
MG
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).
21d37aa6 383 *
21d37aa6
DM
384 * @param int $raterid
385 * @param int $itemid
36937f02
MG
386 * @param boolean $idonly
387 * @return mixed if $idonly=true returns id of the found instance, otherwise returns the instance object
21d37aa6 388 */
36937f02 389 public function get_current_instance($raterid, $itemid, $idonly = false) {
21d37aa6 390 global $DB;
0136124e 391 $params = array(
71ab436a 392 'definitionid' => $this->definition->id,
36937f02 393 'itemid' => $itemid,
0136124e
MG
394 'status1' => gradingform_instance::INSTANCE_STATUS_ACTIVE,
395 'status2' => gradingform_instance::INSTANCE_STATUS_NEEDUPDATE);
71ab436a 396 $select = 'definitionid=:definitionid and itemid=:itemid and (status=:status1 or status=:status2)';
5dc1ca87
MG
397 if (false) {
398 // TODO MDL-31237 should be: if ($manager->allow_multiple_raters())
0136124e
MG
399 $select .= ' and raterid=:raterid';
400 $params['raterid'] = $raterid;
21d37aa6 401 }
36937f02 402 if ($idonly) {
0136124e 403 if ($current = $DB->get_record_select('grading_instances', $select, $params, 'id', IGNORE_MISSING)) {
36937f02
MG
404 return $current->id;
405 }
21d37aa6 406 } else {
0136124e 407 if ($current = $DB->get_record_select('grading_instances', $select, $params, '*', IGNORE_MISSING)) {
36937f02
MG
408 return $this->get_instance($current);
409 }
21d37aa6 410 }
36937f02 411 return null;
21d37aa6
DM
412 }
413
18e6298c 414 /**
0136124e
MG
415 * Returns list of ACTIVE instances for the specified $itemid
416 * (intentionally does not return instances with status NEEDUPDATE)
36937f02
MG
417 *
418 * @param int $itemid
419 * @return array of gradingform_instance objects
18e6298c 420 */
0136124e 421 public function get_active_instances($itemid) {
36937f02 422 global $DB;
71ab436a 423 $conditions = array('definitionid' => $this->definition->id,
36937f02
MG
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 }
a938e409 431 $records->close();
36937f02
MG
432 return $rv;
433 }
6798c63e 434
9028d9b5
PC
435 /**
436 * Returns an array of all active instances for this definition.
437 * (intentionally does not return instances with status NEEDUPDATE)
438 *
98c2189d 439 * @param int since only return instances with timemodified >= since
9028d9b5
PC
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
0136124e
MG
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;
2d41a911
MG
464 if (empty($this->definition->id)) {
465 return false;
466 }
0136124e 467 if ($this->hasactiveinstances === null) {
71ab436a 468 $conditions = array('definitionid' => $this->definition->id,
0136124e
MG
469 'status' => gradingform_instance::INSTANCE_STATUS_ACTIVE);
470 $this->hasactiveinstances = $DB->record_exists('grading_instances', $conditions);
471 }
472 return $this->hasactiveinstances;
473 }
474
6798c63e 475 /**
36937f02 476 * Returns the object of type gradingform_XXX_instance (where XXX is the plugin method name)
6798c63e 477 *
36937f02
MG
478 * @param mixed $instance id or row from grading_isntances table
479 * @return gradingform_instance
6798c63e 480 */
36937f02
MG
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;
6798c63e
MG
492 }
493
494 /**
36937f02
MG
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
6798c63e 499 *
36937f02
MG
500 * @param int $raterid
501 * @param int $itemid
502 * @return gradingform_instance
6798c63e 503 */
fc05f222 504 public function create_instance($raterid, $itemid = null) {
6f19a2a9 505
36937f02 506 // first find if there is already an active instance for this itemid
fc05f222 507 if ($itemid && $current = $this->get_current_instance($raterid, $itemid)) {
36937f02
MG
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 }
6798c63e 513 }
18e6298c 514
13926e73
MG
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
9f1195fa 524 * @throws dml_exception
13926e73
MG
525 */
526 public function get_or_create_instance($instanceid, $raterid, $itemid) {
f8da1b93
AN
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 *
f8da1b93
AN
542 * @param int $raterid
543 * @param int $itemid
9f1195fa 544 * @param int $instanceid
f8da1b93 545 * @return gradingform_instance
9f1195fa 546 * @throws dml_exception
f8da1b93
AN
547 */
548 public function fetch_instance(int $raterid, int $itemid, ?int $instanceid): gradingform_instance {
13926e73 549 global $DB;
f8da1b93
AN
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 }
13926e73 569 }
f8da1b93 570
13926e73
MG
571 return $this->create_instance($raterid, $itemid);
572 }
573
ab156741 574 /**
6832a102 575 * Returns the HTML code displaying the preview of the grading form
ab156741 576 *
20836db9 577 * Plugins are forced to override this. Ideally they should delegate
6832a102
DM
578 * the task to their own renderer.
579 *
580 * @param moodle_page $page the target page
581 * @return string
ab156741 582 */
20836db9 583 abstract public function render_preview(moodle_page $page);
ab156741 584
671ec8f5
DM
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 }
fe817d87 598
671ec8f5
DM
599 // firstly, let the plugin delete everything from their own tables
600 $this->delete_plugin_definition();
601 // then, delete all instances left
71ab436a 602 $DB->delete_records('grading_instances', array('definitionid' => $this->definition->id));
671ec8f5
DM
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
20836db9
DM
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) {
20836db9
DM
630
631 $subsql = array();
632 $params = array();
633
634 return array($subsql, $params);
635 }
636
d22e9e32 637 // //////////////////////////////////////////////////////////////////////////
fe817d87 638
21d37aa6
DM
639 /**
640 * Loads the form definition if it exists
3e43eff5 641 *
21d37aa6 642 * The default implementation just tries to load the record from the {grading_definitions}
3e43eff5
DM
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;
3e43eff5
DM
648 $this->definition = $DB->get_record('grading_definitions', array(
649 'areaid' => $this->areaid,
650 'method' => $this->get_method_name()), '*', IGNORE_MISSING);
651 }
21d37aa6 652
671ec8f5
DM
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
21d37aa6 660 /**
d22e9e32
MG
661 * Returns the name of the grading method plugin, eg 'rubric'
662 *
fe817d87
DM
663 * @return string the name of the grading method plugin, eg 'rubric'
664 * @see PARAM_PLUGIN
21d37aa6 665 */
fe817d87
DM
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 }
21d37aa6 672 }
36937f02
MG
673
674 /**
675 * Returns html code to be included in student's feedback.
676 *
677 * @param moodle_page $page
678 * @param int $itemid
3c2b3cb3 679 * @param array $gradinginfo result of function grade_get_grades if plugin want to use some of their info
9e2eca0f 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
0136124e 681 * @param boolean $cangrade whether current user has capability to grade in this context
36937f02
MG
682 * @return string
683 */
3c2b3cb3 684 public function render_grade($page, $itemid, $gradinginfo, $defaultcontent, $cangrade) {
36937f02
MG
685 return $defaultcontent;
686 }
9e2eca0f
MG
687
688 /**
689 * Sets the range of grades used in this area. This is usually either range like 0-100
170f6e60
MG
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).
3c2b3cb3 699 *
170f6e60
MG
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.
9e2eca0f 703 */
170f6e60 704 public final function set_grade_range(array $graderange, $allowgradedecimals = false) {
9e2eca0f 705 $this->graderange = $graderange;
170f6e60 706 $this->allowgradedecimals = $allowgradedecimals;
9e2eca0f
MG
707 }
708
709 /**
710 * Returns the range of grades used in this area
3c2b3cb3 711 *
9e2eca0f
MG
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 }
3f0ea6d8 720
170f6e60
MG
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
3f0ea6d8
PC
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 }
9028d9b5
PC
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 }
21d37aa6 763}
36937f02
MG
764
765/**
d22e9e32
MG
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}
36937f02 786 *
5dc1ca87 787 * @package core_grading
36937f02 788 * @copyright 2011 Marina Glancy
d22e9e32
MG
789 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
790 * @category grading
36937f02
MG
791 */
792abstract class gradingform_instance {
d22e9e32 793 /** Valid istance status */
36937f02 794 const INSTANCE_STATUS_ACTIVE = 1;
d22e9e32 795 /** The grade needs to be updated by grader (usually because of changes is grading method) */
0136124e 796 const INSTANCE_STATUS_NEEDUPDATE = 2;
d22e9e32 797 /** The grader started grading but did clicked neither submit nor cancel */
36937f02 798 const INSTANCE_STATUS_INCOMPLETE = 0;
d22e9e32 799 /** Grader re-graded the student and this is the status for previous grade stored as history */
36937f02
MG
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 *
71ab436a 821 * @param int $definitionid
36937f02
MG
822 * @param int $raterid
823 * @param int $itemid
824 * @return int id of the created instance
825 */
71ab436a 826 public static function create_new($definitionid, $raterid, $itemid) {
36937f02
MG
827 global $DB;
828 $instance = new stdClass();
71ab436a 829 $instance->definitionid = $definitionid;
36937f02
MG
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
0136124e
MG
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
36937f02
MG
873 /**
874 * Returns the controller
875 *
876 * @return gradingform_controller
877 */
878 public function get_controller() {
879 return $this->controller;
880 }
881
188e840b
MG
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
36937f02
MG
895 /**
896 * Returns instance id
897 *
898 * @return int
899 */
900 public function get_id() {
188e840b 901 return $this->get_data('id');
36937f02
MG
902 }
903
0136124e
MG
904 /**
905 * Returns instance status
906 *
907 * @return int
908 */
909 public function get_status() {
188e840b 910 return $this->get_data('status');
0136124e
MG
911 }
912
36937f02
MG
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 }
fc05f222
MG
922 if (empty($this->data->itemid)) {
923 throw new coding_exception('You cannot mark active the grading instance without itemid');
924 }
36937f02 925 $currentid = $this->get_controller()->get_current_instance($this->data->raterid, $this->data->itemid, true);
0136124e
MG
926 if ($currentid && $currentid != $this->get_id()) {
927 $DB->update_record('grading_instances', array('id' => $currentid, 'status' => self::INSTANCE_STATUS_ARCHIVE));
36937f02 928 }
0136124e 929 $DB->update_record('grading_instances', array('id' => $this->get_id(), 'status' => self::INSTANCE_STATUS_ACTIVE));
36937f02
MG
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;
d22e9e32 942 // TODO MDL-31239 throw exception if status is not INSTANCE_STATUS_INCOMPLETE
36937f02
MG
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.
fc05f222
MG
950 *
951 * @param array $elementvalue
36937f02
MG
952 */
953 public function update($elementvalue) {
fc05f222
MG
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 }
d22e9e32 961 // TODO MDL-31087 also update: rawgrade, feedback, feedbackformat
fc05f222
MG
962 $DB->update_record('grading_instances', $newdata);
963 foreach ($newdata as $key => $value) {
964 $this->data->$key = $value;
965 }
36937f02
MG
966 }
967
968 /**
969 * Calculates the grade to be pushed to the gradebook
9e2eca0f 970 *
170f6e60
MG
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
36937f02
MG
976 */
977 abstract public function get_grade();
978
93023cee
DC
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
36937f02
MG
1001 /**
1002 * Called when teacher submits the grading form:
fc05f222
MG
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
36937f02
MG
1009 * @return int the grade on 0-100 scale
1010 */
fc05f222
MG
1011 public function submit_and_get_grade($elementvalue, $itemid) {
1012 $elementvalue['itemid'] = $itemid;
93023cee
DC
1013 if ($this->is_empty_form($elementvalue)) {
1014 $this->clear_attempt($elementvalue);
1015 $this->make_active();
1016 return -1;
1017 }
36937f02
MG
1018 $this->update($elementvalue);
1019 $this->make_active();
1020 return $this->get_grade();
1021 }
1022
36937f02
MG
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.
9e2eca0f 1029 * ( {NAME} is a shortcut for $gradingformelement->getName() )
36937f02
MG
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
9e2eca0f 1034 * form submit
36937f02
MG
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 *
d22e9e32
MG
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 *
36937f02
MG
1079 * @see validate_grading_element()
1080 * @return string
1081 */
1082 public function default_validation_error_message() {
1083 return '';
1084 }
98c2189d 1085}