MDL-30998: updated docblocks for backup of advanced grading
[moodle.git] / grade / grading / form / rubric / rubriceditor.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  * @package    gradingform
20  * @subpackage rubric
21  * @copyright  2011 Marina Glancy
22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 defined('MOODLE_INTERNAL') || die();
27 require_once("HTML/QuickForm/input.php");
29 class MoodleQuickForm_rubriceditor extends HTML_QuickForm_input {
30     /** help message */
31     public $_helpbutton = '';
32     /** stores the result of the last validation: null - undefined, false - no errors, string - error(s) text */
33     protected $validationerrors = null;
34     /** if element has already been validated **/
35     protected $wasvalidated = false;
36     /** If non-submit (JS) button was pressed: null - unknown, true/false - button was/wasn't pressed */
37     protected $nonjsbuttonpressed = false;
38     /** Message to display in front of the editor (that there exist grades on this rubric being edited) */
39     protected $regradeconfirmation = false;
41     function MoodleQuickForm_rubriceditor($elementName=null, $elementLabel=null, $attributes=null) {
42         parent::HTML_QuickForm_input($elementName, $elementLabel, $attributes);
43     }
45     /**
46      * get html for help button
47      *
48      * @access   public
49      * @return  string html for help button
50      */
51     public function getHelpButton() {
52         return $this->_helpbutton;
53     }
55     /**
56      * The renderer will take care itself about different display in normal and frozen states
57      *
58      * @return string
59      */
60     public function getElementTemplateType() {
61         return 'default';
62     }
64     /**
65      * Specifies that confirmation about re-grading needs to be added to this rubric editor.
66      * $changelevel is saved in $this->regradeconfirmation and retrieved in toHtml()
67      *
68      * @see gradingform_rubric_controller::update_or_check_rubric()
69      * @param int $changelevel
70      */
71     public function add_regrade_confirmation($changelevel) {
72         $this->regradeconfirmation = $changelevel;
73     }
75     /**
76      * Returns html string to display this element
77      *
78      * @return string
79      */
80     public function toHtml() {
81         global $PAGE;
82         $html = $this->_getTabs();
83         $renderer = $PAGE->get_renderer('gradingform_rubric');
84         $data = $this->prepare_data(null, $this->wasvalidated);
85         if (!$this->_flagFrozen) {
86             $mode = gradingform_rubric_controller::DISPLAY_EDIT_FULL;
87             $module = array('name'=>'gradingform_rubriceditor', 'fullpath'=>'/grade/grading/form/rubric/js/rubriceditor.js',
88                 'strings' => array(array('confirmdeletecriterion', 'gradingform_rubric'), array('confirmdeletelevel', 'gradingform_rubric'),
89                     array('criterionempty', 'gradingform_rubric'), array('levelempty', 'gradingform_rubric')
90                     ));
91             $PAGE->requires->js_init_call('M.gradingform_rubriceditor.init', array(
92                 array('name' => $this->getName(),
93                     'criteriontemplate' => $renderer->criterion_template($mode, $data['options'], $this->getName()),
94                     'leveltemplate' => $renderer->level_template($mode, $data['options'], $this->getName())
95                    )),
96                 true, $module);
97         } else {
98             // Rubric is frozen, no javascript needed
99             if ($this->_persistantFreeze) {
100                 $mode = gradingform_rubric_controller::DISPLAY_EDIT_FROZEN;
101             } else {
102                 $mode = gradingform_rubric_controller::DISPLAY_PREVIEW;
103             }
104         }
105         if ($this->regradeconfirmation) {
106             if (!isset($data['regrade'])) {
107                 $data['regrade'] = 1;
108             }
109             $html .= $renderer->display_regrade_confirmation($this->getName(), $this->regradeconfirmation, $data['regrade']);
110         }
111         if ($this->validationerrors) {
112             $html .= $renderer->notification($this->validationerrors, 'error');
113         }
114         $html .= $renderer->display_rubric($data['criteria'], $data['options'], $mode, $this->getName());
115         return $html;
116     }
118     /**
119      * Prepares the data passed in $_POST:
120      * - processes the pressed buttons 'addlevel', 'addcriterion', 'moveup', 'movedown', 'delete' (when JavaScript is disabled)
121      *   sets $this->nonjsbuttonpressed to true/false if such button was pressed
122      * - if options not passed (i.e. we create a new rubric) fills the options array with the default values
123      * - if options are passed completes the options array with unchecked checkboxes
124      * - if $withvalidation is set, adds 'error_xxx' attributes to elements that contain errors and creates an error string
125      *   and stores it in $this->validationerrors
126      *
127      * @param array $value
128      * @param boolean $withvalidation whether to enable data validation
129      * @return array
130      */
131     protected function prepare_data($value = null, $withvalidation = false) {
132         if (null === $value) {
133             $value = $this->getValue();
134         }
135         if ($this->nonjsbuttonpressed === null) {
136             $this->nonjsbuttonpressed = false;
137         }
138         $totalscore = 0;
139         $errors = array();
140         $return = array('criteria' => array(), 'options' => gradingform_rubric_controller::get_default_options());
141         if (!isset($value['criteria'])) {
142             $value['criteria'] = array();
143             $errors['err_nocriteria'] = 1;
144         }
145         // If options are present in $value, replace default values with submitted values
146         if (!empty($value['options'])) {
147             foreach (array_keys($return['options']) as $option) {
148                 // special treatment for checkboxes
149                 if (!empty($value['options'][$option])) {
150                     $return['options'][$option] = $value['options'][$option];
151                 } else {
152                     $return['options'][$option] = null;
153                 }
154             }
155         }
156         if (is_array($value)) {
157             // for other array keys of $value no special treatmeant neeeded, copy them to return value as is
158             foreach (array_keys($value) as $key) {
159                 if ($key != 'options' && $key != 'criteria') {
160                     $return[$key] = $value[$key];
161                 }
162             }
163         }
165         // iterate through criteria
166         $lastaction = null;
167         $lastid = null;
168         foreach ($value['criteria'] as $id => $criterion) {
169             if ($id == 'addcriterion') {
170                 $id = $this->get_next_id(array_keys($value['criteria']));
171                 $criterion = array('description' => '', 'levels' => array());
172                 $i = 0;
173                 // when adding new criterion copy the number of levels and their scores from the last criterion
174                 if (!empty($value['criteria'][$lastid]['levels'])) {
175                     foreach ($value['criteria'][$lastid]['levels'] as $lastlevel) {
176                         $criterion['levels']['NEWID'.($i++)]['score'] = $lastlevel['score'];
177                     }
178                 } else {
179                     $criterion['levels']['NEWID'.($i++)]['score'] = 0;
180                 }
181                 // add more levels so there are at least 3 in the new criterion. Increment by 1 the score for each next one
182                 for ($i=$i; $i<3; $i++) {
183                     $criterion['levels']['NEWID'.$i]['score'] = $criterion['levels']['NEWID'.($i-1)]['score'] + 1;
184                 }
185                 // set other necessary fields (definition) for the levels in the new criterion
186                 foreach (array_keys($criterion['levels']) as $i) {
187                     $criterion['levels'][$i]['definition'] = '';
188                 }
189                 $this->nonjsbuttonpressed = true;
190             }
191             $levels = array();
192             $maxscore = null;
193             if (array_key_exists('levels', $criterion)) {
194                 foreach ($criterion['levels'] as $levelid => $level) {
195                     if ($levelid == 'addlevel') {
196                         $levelid = $this->get_next_id(array_keys($criterion['levels']));
197                         $level = array(
198                             'definition' => '',
199                             'score' => 0,
200                         );
201                         foreach ($criterion['levels'] as $lastlevel) {
202                             if ($level['score'] < $lastlevel['score'] + 1) {
203                                 $level['score'] = $lastlevel['score'] + 1;
204                             }
205                         }
206                         $this->nonjsbuttonpressed = true;
207                     }
208                     if (!array_key_exists('delete', $level)) {
209                         if ($withvalidation) {
210                             if (!strlen(trim($level['definition']))) {
211                                 $errors['err_nodefinition'] = 1;
212                                 $level['error_definition'] = true;
213                             }
214                             if (!preg_match('#^[\+]?\d*$#', trim($level['score'])) && !preg_match('#^[\+]?\d*[\.,]\d+$#', trim($level['score']))) {
215                                 // TODO why we can't allow negative score for rubric?
216                                 $errors['err_scoreformat'] = 1;
217                                 $level['error_score'] = true;
218                             }
219                         }
220                         $levels[$levelid] = $level;
221                         if ($maxscore === null || (float)$level['score'] > $maxscore) {
222                             $maxscore = (float)$level['score'];
223                         }
224                     } else {
225                         $this->nonjsbuttonpressed = true;
226                     }
227                 }
228             }
229             $totalscore += (float)$maxscore;
230             $criterion['levels'] = $levels;
231             if ($withvalidation && !array_key_exists('delete', $criterion)) {
232                 if (count($levels)<2) {
233                     $errors['err_mintwolevels'] = 1;
234                     $criterion['error_levels'] = true;
235                 }
236                 if (!strlen(trim($criterion['description']))) {
237                     $errors['err_nodescription'] = 1;
238                     $criterion['error_description'] = true;
239                 }
240             }
241             if (array_key_exists('moveup', $criterion) || $lastaction == 'movedown') {
242                 unset($criterion['moveup']);
243                 if ($lastid !== null) {
244                     $lastcriterion = $return['criteria'][$lastid];
245                     unset($return['criteria'][$lastid]);
246                     $return['criteria'][$id] = $criterion;
247                     $return['criteria'][$lastid] = $lastcriterion;
248                 } else {
249                     $return['criteria'][$id] = $criterion;
250                 }
251                 $lastaction = null;
252                 $lastid = $id;
253                 $this->nonjsbuttonpressed = true;
254             } else if (array_key_exists('delete', $criterion)) {
255                 $this->nonjsbuttonpressed = true;
256             } else {
257                 if (array_key_exists('movedown', $criterion)) {
258                     unset($criterion['movedown']);
259                     $lastaction = 'movedown';
260                     $this->nonjsbuttonpressed = true;
261                 }
262                 $return['criteria'][$id] = $criterion;
263                 $lastid = $id;
264             }
265         }
267         if ($totalscore <= 0) {
268             $errors['err_totalscore'] = 1;
269         }
271         // add sort order field to criteria
272         $csortorder = 1;
273         foreach (array_keys($return['criteria']) as $id) {
274             $return['criteria'][$id]['sortorder'] = $csortorder++;
275         }
277         // create validation error string (if needed)
278         if ($withvalidation) {
279             if (count($errors)) {
280                 $rv = array();
281                 foreach ($errors as $error => $v) {
282                     $rv[] = get_string($error, 'gradingform_rubric');
283                 }
284                 $this->validationerrors = join('<br/ >', $rv);
285             } else {
286                 $this->validationerrors = false;
287             }
288             $this->wasvalidated = true;
289         }
290         return $return;
291     }
293     /**
294      * Scans array $ids to find the biggest element ! NEWID*, increments it by 1 and returns
295      *
296      * @param array $ids
297      * @return string
298      */
299     protected function get_next_id($ids) {
300         $maxid = 0;
301         foreach ($ids as $id) {
302             if (preg_match('/^NEWID(\d+)$/', $id, $matches) && ((int)$matches[1]) > $maxid) {
303                 $maxid = (int)$matches[1];
304             }
305         }
306         return 'NEWID'.($maxid+1);
307     }
309     /**
310      * Checks if a submit button was pressed which is supposed to be processed on client side by JS
311      * but user seem to have disabled JS in the browser.
312      * (buttons 'add criteria', 'add level', 'move up', 'move down', etc.)
313      * In this case the form containing this element is prevented from being submitted
314      *
315      * @param array $value
316      * @return boolean true if non-submit button was pressed and not processed by JS
317      */
318     public function non_js_button_pressed($value) {
319         if ($this->nonjsbuttonpressed === null) {
320             $this->prepare_data($value);
321         }
322         return $this->nonjsbuttonpressed;
323     }
325     /**
326      * Validates that rubric has at least one criterion, at least two levels within one criterion,
327      * each level has a valid score, all levels have filled definitions and all criteria
328      * have filled descriptions
329      *
330      * @param array $value
331      * @return string|false error text or false if no errors found
332      */
333     public function validate($value) {
334         if (!$this->wasvalidated) {
335             $this->prepare_data($value, true);
336         }
337         return $this->validationerrors;
338     }
340     /**
341      * Prepares the data for saving
342      * @see prepare_data()
343      *
344      * @param array $submitValues
345      * @param boolean $assoc
346      * @return array
347      */
348     public function exportValue(&$submitValues, $assoc = false) {
349         $value =  $this->prepare_data($this->_findValue($submitValues));
350         return $this->_prepareValue($value, $assoc);
351     }