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