MDL-30998: updated docblocks for backup of advanced grading
[moodle.git] / grade / grading / form / rubric / rubriceditor.php
CommitLineData
c586d2bf
MG
1<?php
2
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/>.
17
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 */
24
25defined('MOODLE_INTERNAL') || die();
26
27require_once("HTML/QuickForm/input.php");
28
c586d2bf 29class MoodleQuickForm_rubriceditor extends HTML_QuickForm_input {
3c2b3cb3 30 /** help message */
c586d2bf 31 public $_helpbutton = '';
3c2b3cb3
MG
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;
c586d2bf
MG
40
41 function MoodleQuickForm_rubriceditor($elementName=null, $elementLabel=null, $attributes=null) {
42 parent::HTML_QuickForm_input($elementName, $elementLabel, $attributes);
43 }
44
3c2b3cb3
MG
45 /**
46 * get html for help button
47 *
48 * @access public
49 * @return string html for help button
50 */
51 public function getHelpButton() {
c586d2bf
MG
52 return $this->_helpbutton;
53 }
54
3c2b3cb3
MG
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() {
c586d2bf
MG
61 return 'default';
62 }
63
0136124e
MG
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 */
3c2b3cb3 71 public function add_regrade_confirmation($changelevel) {
0136124e
MG
72 $this->regradeconfirmation = $changelevel;
73 }
74
75 /**
76 * Returns html string to display this element
77 *
78 * @return string
79 */
3c2b3cb3 80 public function toHtml() {
c586d2bf
MG
81 global $PAGE;
82 $html = $this->_getTabs();
ab156741 83 $renderer = $PAGE->get_renderer('gradingform_rubric');
2ae7faf1 84 $data = $this->prepare_data(null, $this->wasvalidated);
c586d2bf 85 if (!$this->_flagFrozen) {
ab156741
MG
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(),
39c6f4b6
MG
93 'criteriontemplate' => $renderer->criterion_template($mode, $data['options'], $this->getName()),
94 'leveltemplate' => $renderer->level_template($mode, $data['options'], $this->getName())
ab156741
MG
95 )),
96 true, $module);
c586d2bf 97 } else {
39c6f4b6 98 // Rubric is frozen, no javascript needed
c586d2bf 99 if ($this->_persistantFreeze) {
ab156741
MG
100 $mode = gradingform_rubric_controller::DISPLAY_EDIT_FROZEN;
101 } else {
102 $mode = gradingform_rubric_controller::DISPLAY_PREVIEW;
c586d2bf 103 }
c586d2bf 104 }
0136124e
MG
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 }
2ae7faf1
MG
111 if ($this->validationerrors) {
112 $html .= $renderer->notification($this->validationerrors, 'error');
113 }
39c6f4b6 114 $html .= $renderer->display_rubric($data['criteria'], $data['options'], $mode, $this->getName());
c586d2bf
MG
115 return $html;
116 }
117
39c6f4b6
MG
118 /**
119 * Prepares the data passed in $_POST:
120 * - processes the pressed buttons 'addlevel', 'addcriterion', 'moveup', 'movedown', 'delete' (when JavaScript is disabled)
2ae7faf1 121 * sets $this->nonjsbuttonpressed to true/false if such button was pressed
39c6f4b6
MG
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
2ae7faf1
MG
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
39c6f4b6
MG
126 *
127 * @param array $value
2ae7faf1 128 * @param boolean $withvalidation whether to enable data validation
39c6f4b6
MG
129 * @return array
130 */
3c2b3cb3 131 protected function prepare_data($value = null, $withvalidation = false) {
39c6f4b6
MG
132 if (null === $value) {
133 $value = $this->getValue();
134 }
2ae7faf1
MG
135 if ($this->nonjsbuttonpressed === null) {
136 $this->nonjsbuttonpressed = false;
137 }
138 $totalscore = 0;
139 $errors = array();
39c6f4b6
MG
140 $return = array('criteria' => array(), 'options' => gradingform_rubric_controller::get_default_options());
141 if (!isset($value['criteria'])) {
142 $value['criteria'] = array();
2ae7faf1 143 $errors['err_nocriteria'] = 1;
39c6f4b6 144 }
2ae7faf1 145 // If options are present in $value, replace default values with submitted values
39c6f4b6
MG
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 }
c586d2bf 155 }
0136124e
MG
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 }
2ae7faf1
MG
164
165 // iterate through criteria
c586d2bf
MG
166 $lastaction = null;
167 $lastid = null;
39c6f4b6 168 foreach ($value['criteria'] as $id => $criterion) {
c586d2bf 169 if ($id == 'addcriterion') {
39c6f4b6 170 $id = $this->get_next_id(array_keys($value['criteria']));
ffbf4370
MG
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) {
a19d1057 176 $criterion['levels']['NEWID'.($i++)]['score'] = $lastlevel['score'];
ffbf4370
MG
177 }
178 } else {
a19d1057 179 $criterion['levels']['NEWID'.($i++)]['score'] = 0;
ffbf4370
MG
180 }
181 // add more levels so there are at least 3 in the new criterion. Increment by 1 the score for each next one
a19d1057
MG
182 for ($i=$i; $i<3; $i++) {
183 $criterion['levels']['NEWID'.$i]['score'] = $criterion['levels']['NEWID'.($i-1)]['score'] + 1;
ffbf4370
MG
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 }
2ae7faf1 189 $this->nonjsbuttonpressed = true;
c586d2bf
MG
190 }
191 $levels = array();
2ae7faf1 192 $maxscore = null;
c586d2bf
MG
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 );
ffbf4370
MG
201 foreach ($criterion['levels'] as $lastlevel) {
202 if ($level['score'] < $lastlevel['score'] + 1) {
203 $level['score'] = $lastlevel['score'] + 1;
204 }
205 }
2ae7faf1 206 $this->nonjsbuttonpressed = true;
c586d2bf
MG
207 }
208 if (!array_key_exists('delete', $level)) {
2ae7faf1 209 if ($withvalidation) {
3c2b3cb3 210 if (!strlen(trim($level['definition']))) {
2ae7faf1
MG
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 }
c586d2bf 220 $levels[$levelid] = $level;
2ae7faf1
MG
221 if ($maxscore === null || (float)$level['score'] > $maxscore) {
222 $maxscore = (float)$level['score'];
223 }
224 } else {
225 $this->nonjsbuttonpressed = true;
c586d2bf
MG
226 }
227 }
228 }
2ae7faf1 229 $totalscore += (float)$maxscore;
c586d2bf 230 $criterion['levels'] = $levels;
2ae7faf1
MG
231 if ($withvalidation && !array_key_exists('delete', $criterion)) {
232 if (count($levels)<2) {
233 $errors['err_mintwolevels'] = 1;
234 $criterion['error_levels'] = true;
235 }
3c2b3cb3 236 if (!strlen(trim($criterion['description']))) {
2ae7faf1
MG
237 $errors['err_nodescription'] = 1;
238 $criterion['error_description'] = true;
239 }
240 }
c586d2bf
MG
241 if (array_key_exists('moveup', $criterion) || $lastaction == 'movedown') {
242 unset($criterion['moveup']);
243 if ($lastid !== null) {
39c6f4b6
MG
244 $lastcriterion = $return['criteria'][$lastid];
245 unset($return['criteria'][$lastid]);
246 $return['criteria'][$id] = $criterion;
247 $return['criteria'][$lastid] = $lastcriterion;
c586d2bf 248 } else {
39c6f4b6 249 $return['criteria'][$id] = $criterion;
c586d2bf
MG
250 }
251 $lastaction = null;
252 $lastid = $id;
2ae7faf1 253 $this->nonjsbuttonpressed = true;
c586d2bf 254 } else if (array_key_exists('delete', $criterion)) {
2ae7faf1 255 $this->nonjsbuttonpressed = true;
c586d2bf
MG
256 } else {
257 if (array_key_exists('movedown', $criterion)) {
258 unset($criterion['movedown']);
259 $lastaction = 'movedown';
2ae7faf1 260 $this->nonjsbuttonpressed = true;
c586d2bf 261 }
39c6f4b6 262 $return['criteria'][$id] = $criterion;
c586d2bf
MG
263 $lastid = $id;
264 }
265 }
2ae7faf1
MG
266
267 if ($totalscore <= 0) {
268 $errors['err_totalscore'] = 1;
269 }
270
271 // add sort order field to criteria
c586d2bf 272 $csortorder = 1;
39c6f4b6
MG
273 foreach (array_keys($return['criteria']) as $id) {
274 $return['criteria'][$id]['sortorder'] = $csortorder++;
c586d2bf 275 }
2ae7faf1
MG
276
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 }
c586d2bf
MG
290 return $return;
291 }
292
3c2b3cb3
MG
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) {
c586d2bf
MG
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 }
308
2ae7faf1
MG
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 */
3c2b3cb3 318 public function non_js_button_pressed($value) {
2ae7faf1
MG
319 if ($this->nonjsbuttonpressed === null) {
320 $this->prepare_data($value);
c586d2bf 321 }
2ae7faf1 322 return $this->nonjsbuttonpressed;
c586d2bf
MG
323 }
324
2ae7faf1
MG
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 */
3c2b3cb3 333 public function validate($value) {
2ae7faf1
MG
334 if (!$this->wasvalidated) {
335 $this->prepare_data($value, true);
c586d2bf 336 }
2ae7faf1 337 return $this->validationerrors;
c586d2bf
MG
338 }
339
39c6f4b6
MG
340 /**
341 * Prepares the data for saving
2ae7faf1 342 * @see prepare_data()
39c6f4b6
MG
343 *
344 * @param array $submitValues
345 * @param boolean $assoc
346 * @return array
347 */
3c2b3cb3 348 public function exportValue(&$submitValues, $assoc = false) {
2ae7faf1 349 $value = $this->prepare_data($this->_findValue($submitValues));
39c6f4b6
MG
350 return $this->_prepareValue($value, $assoc);
351 }
c586d2bf 352}