on-demand release 4.0dev+
[moodle.git] / grade / grading / form / lib.php
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/>.
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  */
25 defined('MOODLE_INTERNAL') || die();
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 {
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;
58     /** @var stdClass the context */
59     protected $context;
61     /** @var string the frankenstyle name of the component */
62     protected $component;
64     /** @var string the name of the gradable area */
65     protected $area;
67     /** @var int the id of the gradable area record */
68     protected $areaid;
70     /** @var stdClass|false the definition structure */
71     protected $definition = false;
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;
76     /** @var bool if decimal values are allowed as grades. */
77     private $allowgradedecimals = false;
79     /** @var boolean|null cached result of function has_active_instances() */
80     protected $hasactiveinstances = null;
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;
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;
99         $this->load_definition();
100     }
102     /**
103      * Returns controller context
104      *
105      * @return stdClass controller context
106      */
107     public function get_context() {
108         return $this->context;
109     }
111     /**
112      * Returns gradable component name
113      *
114      * @return string gradable component name
115      */
116     public function get_component() {
117         return $this->component;
118     }
120     /**
121      * Returns gradable area name
122      *
123      * @return string gradable area name
124      */
125     public function get_area() {
126         return $this->area;
127     }
129     /**
130      * Returns gradable area id
131      *
132      * @return int gradable area id
133      */
134     public function get_areaid() {
135         return $this->areaid;
136     }
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     }
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     }
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     }
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;
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     }
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     }
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) {
210         $params = array('areaid' => $this->areaid);
212         if (!is_null($returnurl)) {
213             $params['returnurl'] = $returnurl->out(false);
214         }
216         return new moodle_url('/grade/grading/form/'.$this->get_method_name().'/edit.php', $params);
217     }
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     }
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     }
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     }
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) {
267         if (get_class($this) != get_class($target)) {
268             throw new coding_exception('The source and copy controller mismatch');
269         }
271         if ($target->is_form_defined()) {
272             throw new coding_exception('The target controller already contains a form definition');
273         }
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;
287         return $new;
288     }
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;
303         if (is_null($usermodified)) {
304             $usermodified = $USER->id;
305         }
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;
330             $DB->update_record('grading_definitions', $record);
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             }
361             $DB->insert_record('grading_definitions', $record);
363         } else {
364             throw new coding_exception('Unknown status of the cached definition record.');
365         }
366     }
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     }
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     }
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     }
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     }
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     }
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     }
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) {
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     }
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     }
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;
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         }
559         if (!empty($instanceid)) {
560             $instance = $DB->get_record('grading_instances', [
561                 'id'  => $instanceid,
562                 'raterid' => $raterid,
563                 'itemid' => $itemid,
564             ], '*', IGNORE_MISSING);
566             if ($instance) {
567                 return $this->get_instance($instance);
568             }
569         }
571         return $this->create_instance($raterid, $itemid);
572     }
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);
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;
594         if (!$this->is_form_defined()) {
595             // nothing to do
596             return;
597         }
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));
606         $this->definition = false;
607     }
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     }
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) {
631         $subsql = array();
632         $params = array();
634         return array($subsql, $params);
635     }
637     // //////////////////////////////////////////////////////////////////////////
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     }
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();
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     }
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     }
688     /**
689      * Sets the range of grades used in this area. This is usually either range like 0-100
690      * or the scale where keys start from 1.
691      *
692      * Typically modules will call it:
693      * $controller->set_grade_range(make_grades_menu($gradingtype), $gradingtype > 0);
694      * Negative $gradingtype means that scale is used and the grade must be rounded
695      * to the nearest int. Positive $gradingtype means that range 0..$gradingtype
696      * is used for the grades and in this case grade does not have to be rounded.
697      *
698      * Sometimes modules always expect grade to be rounded (like mod_assignment does).
699      *
700      * @param array $graderange array where first _key_ is the minimum grade and the
701      *     last key is the maximum grade.
702      * @param bool $allowgradedecimals if decimal values are allowed as grades.
703      */
704     public final function set_grade_range(array $graderange, $allowgradedecimals = false) {
705         $this->graderange = $graderange;
706         $this->allowgradedecimals = $allowgradedecimals;
707     }
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     }
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     }
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     }
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     }
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;
802     /** @var stdClass record from table grading_instances */
803     protected $data;
804     /** @var gradingform_controller link to the corresponding controller */
805     protected $controller;
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     }
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     }
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     }
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     }
873     /**
874      * Returns the controller
875      *
876      * @return gradingform_controller
877      */
878     public function get_controller() {
879         return $this->controller;
880     }
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     }
895     /**
896      * Returns instance id
897      *
898      * @return int
899      */
900     public function get_id() {
901         return $this->get_data('id');
902     }
904     /**
905      * Returns instance status
906      *
907      * @return int
908      */
909     public function get_status() {
910         return $this->get_data('status');
911     }
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     }
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     }
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     }
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();
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     }
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     }
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     }
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);
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     }
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     }