MDL-30998: updated docblocks for advanced grading
[moodle.git] / grade / grading / form / rubric / 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  * Grading method controller for the Rubric plugin
19  *
20  * @package    gradingform_rubric
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 require_once($CFG->dirroot.'/grade/grading/form/lib.php');
29 /**
30  * This controller encapsulates the rubric grading logic
31  *
32  * @copyright  2011 David Mudrak <david@moodle.com>
33  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
34  */
35 class gradingform_rubric_controller extends gradingform_controller {
36     // Modes of displaying the rubric (used in gradingform_rubric_renderer)
37     /** Rubric display mode: For editing (moderator or teacher creates a rubric) */
38     const DISPLAY_EDIT_FULL     = 1;
39     /** Rubric display mode: Preview the rubric design with hidden fields */
40     const DISPLAY_EDIT_FROZEN   = 2;
41     /** Rubric display mode: Preview the rubric design (for person with manage permission) */
42     const DISPLAY_PREVIEW       = 3;
43     /** Rubric display mode: Preview the rubric (for people being graded) */
44     const DISPLAY_PREVIEW_GRADED= 8;
45     /** Rubric display mode: For evaluation, enabled (teacher grades a student) */
46     const DISPLAY_EVAL          = 4;
47     /** Rubric display mode: For evaluation, with hidden fields */
48     const DISPLAY_EVAL_FROZEN   = 5;
49     /** Rubric display mode: Teacher reviews filled rubric */
50     const DISPLAY_REVIEW        = 6;
51     /** Rubric display mode: Dispaly filled rubric (i.e. students see their grades) */
52     const DISPLAY_VIEW          = 7;
54     /**
55      * Extends the module settings navigation with the rubric grading settings
56      *
57      * This function is called when the context for the page is an activity module with the
58      * FEATURE_ADVANCED_GRADING, the user has the permission moodle/grade:managegradingforms
59      * and there is an area with the active grading method set to 'rubric'.
60      *
61      * @param settings_navigation $settingsnav {@link settings_navigation}
62      * @param navigation_node $node {@link navigation_node}
63      */
64     public function extend_settings_navigation(settings_navigation $settingsnav, navigation_node $node=null) {
65         $node->add(get_string('definerubric', 'gradingform_rubric'),
66             $this->get_editor_url(), settings_navigation::TYPE_CUSTOM,
67             null, null, new pix_icon('icon', '', 'gradingform_rubric'));
68     }
70     /**
71      * Extends the module navigation
72      *
73      * This function is called when the context for the page is an activity module with the
74      * FEATURE_ADVANCED_GRADING and there is an area with the active grading method set to the given plugin.
75      *
76      * @param global_navigation $navigation {@link global_navigation}
77      * @param navigation_node $node {@link navigation_node}
78      */
79     public function extend_navigation(global_navigation $navigation, navigation_node $node=null) {
80         if (has_capability('moodle/grade:managegradingforms', $this->get_context())) {
81             // no need for preview if user can manage forms, he will have link to manage.php in settings instead
82             return;
83         }
84         if ($this->is_form_defined() && ($options = $this->get_options()) && !empty($options['alwaysshowdefinition'])) {
85             $node->add(get_string('gradingof', 'gradingform_rubric', get_grading_manager($this->get_areaid())->get_area_title()),
86                     new moodle_url('/grade/grading/form/'.$this->get_method_name().'/preview.php', array('areaid' => $this->get_areaid())),
87                     settings_navigation::TYPE_CUSTOM);
88         }
89     }
91     /**
92      * Saves the rubric definition into the database
93      *
94      * @see parent::update_definition()
95      * @param stdClass $newdefinition rubric definition data as coming from gradingform_rubric_editrubric::get_data()
96      * @param int|null $usermodified optional userid of the author of the definition, defaults to the current user
97      */
98     public function update_definition(stdClass $newdefinition, $usermodified = null) {
99         $this->update_or_check_rubric($newdefinition, $usermodified, true);
100         if (isset($newdefinition->rubric['regrade']) && $newdefinition->rubric['regrade']) {
101             $this->mark_for_regrade();
102         }
103     }
105     /**
106      * Either saves the rubric definition into the database or check if it has been changed.
107      * Returns the level of changes:
108      * 0 - no changes
109      * 1 - only texts or criteria sortorders are changed, students probably do not require re-grading
110      * 2 - added levels but maximum score on rubric is the same, students still may not require re-grading
111      * 3 - removed criteria or added levels or changed number of points, students require re-grading but may be re-graded automatically
112      * 4 - removed levels - students require re-grading and not all students may be re-graded automatically
113      * 5 - added criteria - all students require manual re-grading
114      *
115      * @param stdClass $newdefinition rubric definition data as coming from gradingform_rubric_editrubric::get_data()
116      * @param int|null $usermodified optional userid of the author of the definition, defaults to the current user
117      * @param boolean $doupdate if true actually updates DB, otherwise performs a check
118      *
119      */
120     public function update_or_check_rubric(stdClass $newdefinition, $usermodified = null, $doupdate = false) {
121         global $DB;
123         // firstly update the common definition data in the {grading_definition} table
124         if ($this->definition === false) {
125             if (!$doupdate) {
126                 // if we create the new definition there is no such thing as re-grading anyway
127                 return 5;
128             }
129             // if definition does not exist yet, create a blank one
130             // (we need id to save files embedded in description)
131             parent::update_definition(new stdClass(), $usermodified);
132             parent::load_definition();
133         }
134         if (!isset($newdefinition->rubric['options'])) {
135             $newdefinition->rubric['options'] = self::get_default_options();
136         }
137         $newdefinition->options = json_encode($newdefinition->rubric['options']);
138         $editoroptions = self::description_form_field_options($this->get_context());
139         $newdefinition = file_postupdate_standard_editor($newdefinition, 'description', $editoroptions, $this->get_context(),
140             'grading', 'description', $this->definition->id);
142         // reload the definition from the database
143         $currentdefinition = $this->get_definition(true);
145         // update rubric data
146         $haschanges = array();
147         if (empty($newdefinition->rubric['criteria'])) {
148             $newcriteria = array();
149         } else {
150             $newcriteria = $newdefinition->rubric['criteria']; // new ones to be saved
151         }
152         $currentcriteria = $currentdefinition->rubric_criteria;
153         $criteriafields = array('sortorder', 'description', 'descriptionformat');
154         $levelfields = array('score', 'definition', 'definitionformat');
155         foreach ($newcriteria as $id => $criterion) {
156             // get list of submitted levels
157             $levelsdata = array();
158             if (array_key_exists('levels', $criterion)) {
159                 $levelsdata = $criterion['levels'];
160             }
161             $criterionmaxscore = null;
162             if (preg_match('/^NEWID\d+$/', $id)) {
163                 // insert criterion into DB
164                 $data = array('definitionid' => $this->definition->id, 'descriptionformat' => FORMAT_MOODLE); // TODO MDL-31235 format is not supported yet
165                 foreach ($criteriafields as $key) {
166                     if (array_key_exists($key, $criterion)) {
167                         $data[$key] = $criterion[$key];
168                     }
169                 }
170                 if ($doupdate) {
171                     $id = $DB->insert_record('gradingform_rubric_criteria', $data);
172                 }
173                 $haschanges[5] = true;
174             } else {
175                 // update criterion in DB
176                 $data = array();
177                 foreach ($criteriafields as $key) {
178                     if (array_key_exists($key, $criterion) && $criterion[$key] != $currentcriteria[$id][$key]) {
179                         $data[$key] = $criterion[$key];
180                     }
181                 }
182                 if (!empty($data)) {
183                     // update only if something is changed
184                     $data['id'] = $id;
185                     if ($doupdate) {
186                         $DB->update_record('gradingform_rubric_criteria', $data);
187                     }
188                     $haschanges[1] = true;
189                 }
190                 // remove deleted levels from DB and calculate the maximum score for this criteria
191                 foreach ($currentcriteria[$id]['levels'] as $levelid => $currentlevel) {
192                     if ($criterionmaxscore === null || $criterionmaxscore < $currentlevel['score']) {
193                         $criterionmaxscore = $currentlevel['score'];
194                     }
195                     if (!array_key_exists($levelid, $levelsdata)) {
196                         if ($doupdate) {
197                             $DB->delete_records('gradingform_rubric_levels', array('id' => $levelid));
198                         }
199                         $haschanges[4] = true;
200                     }
201                 }
202             }
203             foreach ($levelsdata as $levelid => $level) {
204                 if (isset($level['score'])) {
205                     $level['score'] = (float)$level['score'];
206                     if ($level['score']<0) {
207                         $level['score'] = 0;
208                     }
209                 }
210                 if (preg_match('/^NEWID\d+$/', $levelid)) {
211                     // insert level into DB
212                     $data = array('criterionid' => $id, 'definitionformat' => FORMAT_MOODLE); // TODO MDL-31235 format is not supported yet
213                     foreach ($levelfields as $key) {
214                         if (array_key_exists($key, $level)) {
215                             $data[$key] = $level[$key];
216                         }
217                     }
218                     if ($doupdate) {
219                         $levelid = $DB->insert_record('gradingform_rubric_levels', $data);
220                     }
221                     if ($criterionmaxscore !== null && $criterionmaxscore >= $level['score']) {
222                         // new level is added but the maximum score for this criteria did not change, re-grading may not be necessary
223                         $haschanges[2] = true;
224                     } else {
225                         $haschanges[3] = true;
226                     }
227                 } else {
228                     // update level in DB
229                     $data = array();
230                     foreach ($levelfields as $key) {
231                         if (array_key_exists($key, $level) && $level[$key] != $currentcriteria[$id]['levels'][$levelid][$key]) {
232                             $data[$key] = $level[$key];
233                         }
234                     }
235                     if (!empty($data)) {
236                         // update only if something is changed
237                         $data['id'] = $levelid;
238                         if ($doupdate) {
239                             $DB->update_record('gradingform_rubric_levels', $data);
240                         }
241                         if (isset($data['score'])) {
242                             $haschanges[3] = true;
243                         }
244                         $haschanges[1] = true;
245                     }
246                 }
247             }
248         }
249         // remove deleted criteria from DB
250         foreach (array_keys($currentcriteria) as $id) {
251             if (!array_key_exists($id, $newcriteria)) {
252                 if ($doupdate) {
253                     $DB->delete_records('gradingform_rubric_criteria', array('id' => $id));
254                     $DB->delete_records('gradingform_rubric_levels', array('criterionid' => $id));
255                 }
256                 $haschanges[3] = true;
257             }
258         }
259         foreach (array('status', 'description', 'descriptionformat', 'name', 'options') as $key) {
260             if (isset($newdefinition->$key) && $newdefinition->$key != $this->definition->$key) {
261                 $haschanges[1] = true;
262             }
263         }
264         if ($usermodified && $usermodified != $this->definition->usermodified) {
265             $haschanges[1] = true;
266         }
267         if (!count($haschanges)) {
268             return 0;
269         }
270         if ($doupdate) {
271             parent::update_definition($newdefinition, $usermodified);
272             $this->load_definition();
273         }
274         // return the maximum level of changes
275         $changelevels = array_keys($haschanges);
276         sort($changelevels);
277         return array_pop($changelevels);
278     }
280     /**
281      * Marks all instances filled with this rubric with the status INSTANCE_STATUS_NEEDUPDATE
282      */
283     public function mark_for_regrade() {
284         global $DB;
285         if ($this->has_active_instances()) {
286             $conditions = array('definitionid'  => $this->definition->id,
287                         'status'  => gradingform_instance::INSTANCE_STATUS_ACTIVE);
288             $DB->set_field('grading_instances', 'status', gradingform_instance::INSTANCE_STATUS_NEEDUPDATE, $conditions);
289         }
290     }
292     /**
293      * Loads the rubric form definition if it exists
294      *
295      * There is a new array called 'rubric_criteria' appended to the list of parent's definition properties.
296      */
297     protected function load_definition() {
298         global $DB;
299         $sql = "SELECT gd.*,
300                        rc.id AS rcid, rc.sortorder AS rcsortorder, rc.description AS rcdescription, rc.descriptionformat AS rcdescriptionformat,
301                        rl.id AS rlid, rl.score AS rlscore, rl.definition AS rldefinition, rl.definitionformat AS rldefinitionformat
302                   FROM {grading_definitions} gd
303              LEFT JOIN {gradingform_rubric_criteria} rc ON (rc.definitionid = gd.id)
304              LEFT JOIN {gradingform_rubric_levels} rl ON (rl.criterionid = rc.id)
305                  WHERE gd.areaid = :areaid AND gd.method = :method
306               ORDER BY rc.sortorder,rl.score";
307         $params = array('areaid' => $this->areaid, 'method' => $this->get_method_name());
309         $rs = $DB->get_recordset_sql($sql, $params);
310         $this->definition = false;
311         foreach ($rs as $record) {
312             // pick the common definition data
313             if ($this->definition === false) {
314                 $this->definition = new stdClass();
315                 foreach (array('id', 'name', 'description', 'descriptionformat', 'status', 'copiedfromid',
316                         'timecreated', 'usercreated', 'timemodified', 'usermodified', 'timecopied', 'options') as $fieldname) {
317                     $this->definition->$fieldname = $record->$fieldname;
318                 }
319                 $this->definition->rubric_criteria = array();
320             }
321             // pick the criterion data
322             if (!empty($record->rcid) and empty($this->definition->rubric_criteria[$record->rcid])) {
323                 foreach (array('id', 'sortorder', 'description', 'descriptionformat') as $fieldname) {
324                     $this->definition->rubric_criteria[$record->rcid][$fieldname] = $record->{'rc'.$fieldname};
325                 }
326                 $this->definition->rubric_criteria[$record->rcid]['levels'] = array();
327             }
328             // pick the level data
329             if (!empty($record->rlid)) {
330                 foreach (array('id', 'score', 'definition', 'definitionformat') as $fieldname) {
331                     $value = $record->{'rl'.$fieldname};
332                     if ($fieldname == 'score') {
333                         $value = (float)$value; // To prevent display like 1.00000
334                     }
335                     $this->definition->rubric_criteria[$record->rcid]['levels'][$record->rlid][$fieldname] = $value;
336                 }
337             }
338         }
339         $rs->close();
340         $options = $this->get_options();
341         if (!$options['sortlevelsasc']) {
342             foreach (array_keys($this->definition->rubric_criteria) as $rcid) {
343                 $this->definition->rubric_criteria[$rcid]['levels'] = array_reverse($this->definition->rubric_criteria[$rcid]['levels'], true);
344             }
345         }
346     }
348     /**
349      * Returns the default options for the rubric display
350      *
351      * @return array
352      */
353     public static function get_default_options() {
354         $options = array(
355             'sortlevelsasc' => 1,
356             'alwaysshowdefinition' => 1,
357             'showdescriptionteacher' => 1,
358             'showdescriptionstudent' => 1,
359             'showscoreteacher' => 1,
360             'showscorestudent' => 1,
361             'enableremarks' => 1,
362             'showremarksstudent' => 1
363         );
364         return $options;
365     }
367     /**
368      * Gets the options of this rubric definition, fills the missing options with default values
369      *
370      * @return array
371      */
372     public function get_options() {
373         $options = self::get_default_options();
374         if (!empty($this->definition->options)) {
375             $thisoptions = json_decode($this->definition->options);
376             foreach ($thisoptions as $option => $value) {
377                 $options[$option] = $value;
378             }
379         }
380         return $options;
381     }
383     /**
384      * Converts the current definition into an object suitable for the editor form's set_data()
385      *
386      * @param boolean $addemptycriterion whether to add an empty criterion if the rubric is completely empty (just being created)
387      * @return stdClass
388      */
389     public function get_definition_for_editing($addemptycriterion = false) {
391         $definition = $this->get_definition();
392         $properties = new stdClass();
393         $properties->areaid = $this->areaid;
394         if ($definition) {
395             foreach (array('id', 'name', 'description', 'descriptionformat', 'status') as $key) {
396                 $properties->$key = $definition->$key;
397             }
398             $options = self::description_form_field_options($this->get_context());
399             $properties = file_prepare_standard_editor($properties, 'description', $options, $this->get_context(),
400                 'grading', 'description', $definition->id);
401         }
402         $properties->rubric = array('criteria' => array(), 'options' => $this->get_options());
403         if (!empty($definition->rubric_criteria)) {
404             $properties->rubric['criteria'] = $definition->rubric_criteria;
405         } else if (!$definition && $addemptycriterion) {
406             $properties->rubric['criteria'] = array('addcriterion' => 1);
407         }
409         return $properties;
410     }
412     /**
413      * Returns the form definition suitable for cloning into another area
414      *
415      * @see parent::get_definition_copy()
416      * @param gradingform_controller $target the controller of the new copy
417      * @return stdClass definition structure to pass to the target's {@link update_definition()}
418      */
419     public function get_definition_copy(gradingform_controller $target) {
421         $new = parent::get_definition_copy($target);
422         $old = $this->get_definition_for_editing();
423         $new->description_editor = $old->description_editor;
424         $new->rubric = array('criteria' => array(), 'options' => $old->rubric['options']);
425         $newcritid = 1;
426         $newlevid = 1;
427         foreach ($old->rubric['criteria'] as $oldcritid => $oldcrit) {
428             unset($oldcrit['id']);
429             if (isset($oldcrit['levels'])) {
430                 foreach ($oldcrit['levels'] as $oldlevid => $oldlev) {
431                     unset($oldlev['id']);
432                     $oldcrit['levels']['NEWID'.$newlevid] = $oldlev;
433                     unset($oldcrit['levels'][$oldlevid]);
434                     $newlevid++;
435                 }
436             } else {
437                 $oldcrit['levels'] = array();
438             }
439             $new->rubric['criteria']['NEWID'.$newcritid] = $oldcrit;
440             $newcritid++;
441         }
443         return $new;
444     }
446     /**
447      * Options for displaying the rubric description field in the form
448      *
449      * @param object $context
450      * @return array options for the form description field
451      */
452     public static function description_form_field_options($context) {
453         global $CFG;
454         return array(
455             'maxfiles' => -1,
456             'maxbytes' => get_user_max_upload_file_size($context, $CFG->maxbytes),
457             'context'  => $context,
458         );
459     }
461     /**
462      * Formats the definition description for display on page
463      *
464      * @return string
465      */
466     public function get_formatted_description() {
467         if (!isset($this->definition->description)) {
468             return '';
469         }
470         $context = $this->get_context();
472         $options = self::description_form_field_options($this->get_context());
473         $description = file_rewrite_pluginfile_urls($this->definition->description, 'pluginfile.php', $context->id,
474             'grading', 'description', $this->definition->id, $options);
476         $formatoptions = array(
477             'noclean' => false,
478             'trusted' => false,
479             'filter' => true,
480             'context' => $context
481         );
482         return format_text($description, $this->definition->descriptionformat, $formatoptions);
483     }
485     /**
486      * Returns the rubric plugin renderer
487      *
488      * @param moodle_page $page the target page
489      * @return gradingform_rubric_renderer
490      */
491     public function get_renderer(moodle_page $page) {
492         return $page->get_renderer('gradingform_'. $this->get_method_name());
493     }
495     /**
496      * Returns the HTML code displaying the preview of the grading form
497      *
498      * @param moodle_page $page the target page
499      * @return string
500      */
501     public function render_preview(moodle_page $page) {
503         if (!$this->is_form_defined()) {
504             throw new coding_exception('It is the caller\'s responsibility to make sure that the form is actually defined');
505         }
507         $output = $this->get_renderer($page);
508         $criteria = $this->definition->rubric_criteria;
509         $options = $this->get_options();
510         $rubric = '';
511         if (has_capability('moodle/grade:managegradingforms', $page->context)) {
512             $showdescription = true;
513         } else {
514             $showdescription = $options['showdescriptionstudent'];
515         }
516         if ($showdescription) {
517             $rubric .= $output->box($this->get_formatted_description(), 'gradingform_rubric-description');
518         }
519         if (has_capability('moodle/grade:managegradingforms', $page->context)) {
520             $rubric .= $output->display_rubric_mapping_explained($this->get_min_max_score());
521             $rubric .= $output->display_rubric($criteria, $options, self::DISPLAY_PREVIEW, 'rubric');
522         } else {
523             $rubric .= $output->display_rubric($criteria, $options, self::DISPLAY_PREVIEW_GRADED, 'rubric');
524         }
526         return $rubric;
527     }
529     /**
530      * Deletes the rubric definition and all the associated information
531      */
532     protected function delete_plugin_definition() {
533         global $DB;
535         // get the list of instances
536         $instances = array_keys($DB->get_records('grading_instances', array('definitionid' => $this->definition->id), '', 'id'));
537         // delete all fillings
538         $DB->delete_records_list('gradingform_rubric_fillings', 'instanceid', $instances);
539         // delete instances
540         $DB->delete_records_list('grading_instances', 'id', $instances);
541         // get the list of criteria records
542         $criteria = array_keys($DB->get_records('gradingform_rubric_criteria', array('definitionid' => $this->definition->id), '', 'id'));
543         // delete levels
544         $DB->delete_records_list('gradingform_rubric_levels', 'criterionid', $criteria);
545         // delete critera
546         $DB->delete_records_list('gradingform_rubric_criteria', 'id', $criteria);
547     }
549     /**
550      * If instanceid is specified and grading instance exists and it is created by this rater for
551      * this item, this instance is returned.
552      * If there exists a draft for this raterid+itemid, take this draft (this is the change from parent)
553      * Otherwise new instance is created for the specified rater and itemid
554      *
555      * @param int $instanceid
556      * @param int $raterid
557      * @param int $itemid
558      * @return gradingform_instance
559      */
560     public function get_or_create_instance($instanceid, $raterid, $itemid) {
561         global $DB;
562         if ($instanceid &&
563                 $instance = $DB->get_record('grading_instances', array('id'  => $instanceid, 'raterid' => $raterid, 'itemid' => $itemid), '*', IGNORE_MISSING)) {
564             return $this->get_instance($instance);
565         }
566         if ($itemid && $raterid) {
567             $params = array('definitionid' => $this->definition->id, 'raterid' => $raterid, 'itemid' => $itemid);
568             if ($rs = $DB->get_records('grading_instances', $params, 'timemodified DESC', '*', 0, 1)) {
569                 $record = reset($rs);
570                 $currentinstance = $this->get_current_instance($raterid, $itemid);
571                 if ($record->status == gradingform_rubric_instance::INSTANCE_STATUS_INCOMPLETE &&
572                         (!$currentinstance || $record->timemodified > $currentinstance->get_data('timemodified'))) {
573                     $record->isrestored = true;
574                     return $this->get_instance($record);
575                 }
576             }
577         }
578         return $this->create_instance($raterid, $itemid);
579     }
581     /**
582      * Returns html code to be included in student's feedback.
583      *
584      * @param moodle_page $page
585      * @param int $itemid
586      * @param array $gradinginfo result of function grade_get_grades
587      * @param string $defaultcontent default string to be returned if no active grading is found
588      * @param boolean $cangrade whether current user has capability to grade in this context
589      * @return string
590      */
591     public function render_grade($page, $itemid, $gradinginfo, $defaultcontent, $cangrade) {
592         return $this->get_renderer($page)->display_instances($this->get_active_instances($itemid), $defaultcontent, $cangrade);
593     }
595     // ///// full-text search support /////////////////////////////////////////////
597     /**
598      * Prepare the part of the search query to append to the FROM statement
599      *
600      * @param string $gdid the alias of grading_definitions.id column used by the caller
601      * @return string
602      */
603     public static function sql_search_from_tables($gdid) {
604         return " LEFT JOIN {gradingform_rubric_criteria} rc ON (rc.definitionid = $gdid)
605                  LEFT JOIN {gradingform_rubric_levels} rl ON (rl.criterionid = rc.id)";
606     }
608     /**
609      * Prepare the parts of the SQL WHERE statement to search for the given token
610      *
611      * The returned array cosists of the list of SQL comparions and the list of
612      * respective parameters for the comparisons. The returned chunks will be joined
613      * with other conditions using the OR operator.
614      *
615      * @param string $token token to search for
616      * @return array
617      */
618     public static function sql_search_where($token) {
619         global $DB;
621         $subsql = array();
622         $params = array();
624         // search in rubric criteria description
625         $subsql[] = $DB->sql_like('rc.description', '?', false, false);
626         $params[] = '%'.$DB->sql_like_escape($token).'%';
628         // search in rubric levels definition
629         $subsql[] = $DB->sql_like('rl.definition', '?', false, false);
630         $params[] = '%'.$DB->sql_like_escape($token).'%';
632         return array($subsql, $params);
633     }
635     /**
636      * Calculates and returns the possible minimum and maximum score (in points) for this rubric
637      *
638      * @return array
639      */
640     public function get_min_max_score() {
641         if (!$this->is_form_available()) {
642             return null;
643         }
644         $returnvalue = array('minscore' => 0, 'maxscore' => 0);
645         foreach ($this->get_definition()->rubric_criteria as $id => $criterion) {
646             $scores = array();
647             foreach ($criterion['levels'] as $level) {
648                 $scores[] = $level['score'];
649             }
650             sort($scores);
651             $returnvalue['minscore'] += $scores[0];
652             $returnvalue['maxscore'] += $scores[sizeof($scores)-1];
653         }
654         return $returnvalue;
655     }
658 /**
659  * Class to manage one rubric grading instance.
660  *
661  * Stores information and performs actions like update, copy, validate, submit, etc.
662  *
663  * @copyright  2011 Marina Glancy
664  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
665  */
666 class gradingform_rubric_instance extends gradingform_instance {
668     /** @var array stores the rubric, has two keys: 'criteria' and 'options' */
669     protected $rubric;
671     /**
672      * Deletes this (INCOMPLETE) instance from database.
673      */
674     public function cancel() {
675         global $DB;
676         parent::cancel();
677         $DB->delete_records('gradingform_rubric_fillings', array('instanceid' => $this->get_id()));
678     }
680     /**
681      * Duplicates the instance before editing (optionally substitutes raterid and/or itemid with
682      * the specified values)
683      *
684      * @param int $raterid value for raterid in the duplicate
685      * @param int $itemid value for itemid in the duplicate
686      * @return int id of the new instance
687      */
688     public function copy($raterid, $itemid) {
689         global $DB;
690         $instanceid = parent::copy($raterid, $itemid);
691         $currentgrade = $this->get_rubric_filling();
692         foreach ($currentgrade['criteria'] as $criterionid => $record) {
693             $params = array('instanceid' => $instanceid, 'criterionid' => $criterionid,
694                 'levelid' => $record['levelid'], 'remark' => $record['remark'], 'remarkformat' => $record['remarkformat']);
695             $DB->insert_record('gradingform_rubric_fillings', $params);
696         }
697         return $instanceid;
698     }
700     /**
701      * Validates that rubric is fully completed and contains valid grade on each criterion
702      *
703      * @param array $elementvalue value of element as came in form submit
704      * @return boolean true if the form data is validated and contains no errors
705      */
706     public function validate_grading_element($elementvalue) {
707         $criteria = $this->get_controller()->get_definition()->rubric_criteria;
708         if (!isset($elementvalue['criteria']) || !is_array($elementvalue['criteria']) || sizeof($elementvalue['criteria']) < sizeof($criteria)) {
709             return false;
710         }
711         foreach ($criteria as $id => $criterion) {
712             if (!isset($elementvalue['criteria'][$id]['levelid'])
713                     || !array_key_exists($elementvalue['criteria'][$id]['levelid'], $criterion['levels'])) {
714                 return false;
715             }
716         }
717         return true;
718     }
720     /**
721      * Retrieves from DB and returns the data how this rubric was filled
722      *
723      * @param boolean $force whether to force DB query even if the data is cached
724      * @return array
725      */
726     public function get_rubric_filling($force = false) {
727         global $DB;
728         if ($this->rubric === null || $force) {
729             $records = $DB->get_records('gradingform_rubric_fillings', array('instanceid' => $this->get_id()));
730             $this->rubric = array('criteria' => array());
731             foreach ($records as $record) {
732                 $this->rubric['criteria'][$record->criterionid] = (array)$record;
733             }
734         }
735         return $this->rubric;
736     }
738     /**
739      * Updates the instance with the data received from grading form. This function may be
740      * called via AJAX when grading is not yet completed, so it does not change the
741      * status of the instance.
742      *
743      * @param array $data
744      */
745     public function update($data) {
746         global $DB;
747         $currentgrade = $this->get_rubric_filling();
748         parent::update($data);
749         foreach ($data['criteria'] as $criterionid => $record) {
750             if (!array_key_exists($criterionid, $currentgrade['criteria'])) {
751                 $newrecord = array('instanceid' => $this->get_id(), 'criterionid' => $criterionid,
752                     'levelid' => $record['levelid'], 'remarkformat' => FORMAT_MOODLE);
753                 if (isset($record['remark'])) {
754                     $newrecord['remark'] = $record['remark'];
755                 }
756                 $DB->insert_record('gradingform_rubric_fillings', $newrecord);
757             } else {
758                 $newrecord = array('id' => $currentgrade['criteria'][$criterionid]['id']);
759                 foreach (array('levelid', 'remark'/*, 'remarkformat' */) as $key) {
760                     // TODO MDL-31235 format is not supported yet
761                     if (isset($record[$key]) && $currentgrade['criteria'][$criterionid][$key] != $record[$key]) {
762                         $newrecord[$key] = $record[$key];
763                     }
764                 }
765                 if (count($newrecord) > 1) {
766                     $DB->update_record('gradingform_rubric_fillings', $newrecord);
767                 }
768             }
769         }
770         foreach ($currentgrade['criteria'] as $criterionid => $record) {
771             if (!array_key_exists($criterionid, $data['criteria'])) {
772                 $DB->delete_records('gradingform_rubric_fillings', array('id' => $record['id']));
773             }
774         }
775         $this->get_rubric_filling(true);
776     }
778     /**
779      * Calculates the grade to be pushed to the gradebook
780      *
781      * @return int the valid grade from $this->get_controller()->get_grade_range()
782      */
783     public function get_grade() {
784         global $DB, $USER;
785         $grade = $this->get_rubric_filling();
787         if (!($scores = $this->get_controller()->get_min_max_score()) || $scores['maxscore'] <= $scores['minscore']) {
788             return -1;
789         }
791         $graderange = array_keys($this->get_controller()->get_grade_range());
792         if (empty($graderange)) {
793             return -1;
794         }
795         sort($graderange);
796         $mingrade = $graderange[0];
797         $maxgrade = $graderange[sizeof($graderange) - 1];
799         $curscore = 0;
800         foreach ($grade['criteria'] as $id => $record) {
801             $curscore += $this->get_controller()->get_definition()->rubric_criteria[$id]['levels'][$record['levelid']]['score'];
802         }
803         return round(($curscore-$scores['minscore'])/($scores['maxscore']-$scores['minscore'])*($maxgrade-$mingrade), 0) + $mingrade;
804     }
806     /**
807      * Returns html for form element of type 'grading'.
808      *
809      * @param moodle_page $page
810      * @param MoodleQuickForm_grading $gradingformelement
811      * @return string
812      */
813     public function render_grading_element($page, $gradingformelement) {
814         global $USER;
815         if (!$gradingformelement->_flagFrozen) {
816             $module = array('name'=>'gradingform_rubric', 'fullpath'=>'/grade/grading/form/rubric/js/rubric.js');
817             $page->requires->js_init_call('M.gradingform_rubric.init', array(array('name' => $gradingformelement->getName())), true, $module);
818             $mode = gradingform_rubric_controller::DISPLAY_EVAL;
819         } else {
820             if ($gradingformelement->_persistantFreeze) {
821                 $mode = gradingform_rubric_controller::DISPLAY_EVAL_FROZEN;
822             } else {
823                 $mode = gradingform_rubric_controller::DISPLAY_REVIEW;
824             }
825         }
826         $criteria = $this->get_controller()->get_definition()->rubric_criteria;
827         $options = $this->get_controller()->get_options();
828         $value = $gradingformelement->getValue();
829         $html = '';
830         if ($value === null) {
831             $value = $this->get_rubric_filling();
832         } else if (!$this->validate_grading_element($value)) {
833             $html .= html_writer::tag('div', get_string('rubricnotcompleted', 'gradingform_rubric'), array('class' => 'gradingform_rubric-error'));
834         }
835         $currentinstance = $this->get_current_instance();
836         if ($currentinstance && $currentinstance->get_status() == gradingform_instance::INSTANCE_STATUS_NEEDUPDATE) {
837             $html .= html_writer::tag('div', get_string('needregrademessage', 'gradingform_rubric'), array('class' => 'gradingform_rubric-regrade'));
838         }
839         $haschanges = false;
840         if ($currentinstance) {
841             $curfilling = $currentinstance->get_rubric_filling();
842             foreach ($curfilling['criteria'] as $criterionid => $curvalues) {
843                 $value['criteria'][$criterionid]['savedlevelid'] = $curvalues['levelid'];
844                 $newremark = null;
845                 $newlevelid = null;
846                 if (isset($value['criteria'][$criterionid]['remark'])) $newremark = $value['criteria'][$criterionid]['remark'];
847                 if (isset($value['criteria'][$criterionid]['levelid'])) $newlevelid = $value['criteria'][$criterionid]['levelid'];
848                 if ($newlevelid != $curvalues['levelid'] || $newremark != $curvalues['remark']) {
849                     $haschanges = true;
850                 }
851             }
852         }
853         if ($this->get_data('isrestored') && $haschanges) {
854             $html .= html_writer::tag('div', get_string('restoredfromdraft', 'gradingform_rubric'), array('class' => 'gradingform_rubric-restored'));
855         }
856         if (!empty($options['showdescriptionteacher'])) {
857             $html .= html_writer::tag('div', $this->get_controller()->get_formatted_description(), array('class' => 'gradingform_rubric-description'));
858         }
859         $html .= $this->get_controller()->get_renderer($page)->display_rubric($criteria, $options, $mode, $gradingformelement->getName(), $value);
860         return $html;
861     }