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