MDL-30998: updated docblocks for backup of advanced grading
[moodle.git] / grade / grading / form / rubric / edit_form.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  * The form used at the rubric editor page is defined here
20  *
21  * @package    gradingform
22  * @subpackage rubric
23  * @copyright  2011 Marina Glancy <marina@moodle.com>
24  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25  */
27 defined('MOODLE_INTERNAL') || die();
29 require_once($CFG->dirroot.'/lib/formslib.php');
30 require_once(dirname(__FILE__).'/rubriceditor.php');
31 MoodleQuickForm::registerElementType('rubriceditor', $CFG->dirroot.'/grade/grading/form/rubric/rubriceditor.php', 'MoodleQuickForm_rubriceditor');
33 /**
34  * Defines the rubric edit form
35  */
36 class gradingform_rubric_editrubric extends moodleform {
38     /**
39      * Form element definition
40      */
41     public function definition() {
42         $form = $this->_form;
44         $form->addElement('hidden', 'areaid');
45         $form->setType('areaid', PARAM_INT);
47         $form->addElement('hidden', 'returnurl');
49         // name
50         $form->addElement('text', 'name', get_string('name', 'gradingform_rubric'), array('size'=>52));
51         $form->addRule('name', get_string('required'), 'required');
52         $form->setType('name', PARAM_TEXT);
54         // description
55         $options = gradingform_rubric_controller::description_form_field_options($this->_customdata['context']);
56         $form->addElement('editor', 'description_editor', get_string('description', 'gradingform_rubric'), null, $options);
57         $form->setType('description_editor', PARAM_RAW);
59         // rubric completion status
60         $choices = array();
61         $choices[gradingform_controller::DEFINITION_STATUS_DRAFT]    = html_writer::tag('span', get_string('statusdraft', 'core_grading'), array('class' => 'status draft'));
62         $choices[gradingform_controller::DEFINITION_STATUS_READY]    = html_writer::tag('span', get_string('statusready', 'core_grading'), array('class' => 'status ready'));
63         $form->addElement('select', 'status', get_string('rubricstatus', 'gradingform_rubric'), $choices)->freeze();
65         // rubric editor
66         $element = $form->addElement('rubriceditor', 'rubric', get_string('rubric', 'gradingform_rubric'));
67         $form->setType('rubric', PARAM_RAW);
68         //$element->freeze(); // TODO freeze rubric editor if needed
70         $buttonarray = array();
71         $buttonarray[] = &$form->createElement('submit', 'saverubric', get_string('saverubric', 'gradingform_rubric'));
72         if ($this->_customdata['allowdraft']) {
73             $buttonarray[] = &$form->createElement('submit', 'saverubricdraft', get_string('saverubricdraft', 'gradingform_rubric'));
74         }
75         $editbutton = &$form->createElement('submit', 'editrubric', ' ');
76         $editbutton->freeze();
77         $buttonarray[] = &$editbutton;
78         $buttonarray[] = &$form->createElement('cancel');
79         $form->addGroup($buttonarray, 'buttonar', '', array(' '), false);
80         $form->closeHeaderBefore('buttonar');
81     }
83     /**
84      * Setup the form depending on current values. This method is called after definition(),
85      * data submission and set_data().
86      * All form setup that is dependent on form values should go in here.
87      *
88      * We remove the element status if there is no current status (i.e. rubric is only being created)
89      * so the users do not get confused
90      */
91     public function definition_after_data() {
92         $form = $this->_form;
93         $el = $form->getElement('status');
94         if (!$el->getValue()) {
95             $form->removeElement('status');
96         } else {
97             $vals = array_values($el->getValue());
98             if ($vals[0] == gradingform_controller::DEFINITION_STATUS_READY) {
99                 $this->findButton('saverubric')->setValue(get_string('save', 'gradingform_rubric'));
100             }
101         }
102     }
104     /**
105      * Form vlidation.
106      * If there are errors return array of errors ("fieldname"=>"error message"),
107      * otherwise true if ok.
108      *
109      * @param array $data array of ("fieldname"=>value) of submitted data
110      * @param array $files array of uploaded files "element_name"=>tmp_file_path
111      * @return array of "element_name"=>"error_description" if there are errors,
112      *               or an empty array if everything is OK (true allowed for backwards compatibility too).
113      */
114     public function validation($data, $files) {
115         $err = parent::validation($data, $files);
116         $err = array();
117         $form = $this->_form;
118         $rubricel = $form->getElement('rubric');
119         if ($rubricel->non_js_button_pressed($data['rubric'])) {
120             // if JS is disabled and button such as 'Add criterion' is pressed - prevent from submit
121             $err['rubricdummy'] = 1;
122         } else if (isset($data['editrubric'])) {
123             // continue editing
124             $err['rubricdummy'] = 1;
125         } else if (isset($data['saverubric']) && $data['saverubric']) {
126             // If user attempts to make rubric active - it needs to be validated
127             if ($rubricel->validate($data['rubric']) !== false) {
128                 $err['rubricdummy'] = 1;
129             }
130         }
131         return $err;
132     }
134     /**
135      * Return submitted data if properly submitted or returns NULL if validation fails or
136      * if there is no submitted data.
137      *
138      * @return object submitted data; NULL if not valid or not submitted or cancelled
139      */
140     public function get_data() {
141         $data = parent::get_data();
142         if (!empty($data->saverubric)) {
143             $data->status = gradingform_controller::DEFINITION_STATUS_READY;
144         } else if (!empty($data->saverubricdraft)) {
145             $data->status = gradingform_controller::DEFINITION_STATUS_DRAFT;
146         }
147         return $data;
148     }
150     /**
151      * Check if there are changes in the rubric and it is needed to ask user whether to
152      * mark the current grades for re-grading. User may confirm re-grading and continue,
153      * return to editing or cancel the changes
154      *
155      * @param gradingform_rubric_controller $controller
156      */
157     public function need_confirm_regrading($controller) {
158         $data = $this->get_data();
159         if (isset($data->rubric['regrade'])) {
160             // we have already displayed the confirmation on the previous step
161             return false;
162         }
163         if (!isset($data->saverubric) || !$data->saverubric) {
164             // we only need confirmation when button 'Save rubric' is pressed
165             return false;
166         }
167         if (!$controller->has_active_instances()) {
168             // nothing to re-grade, confirmation not needed
169             return false;
170         }
171         $changelevel = $controller->update_or_check_rubric($data);
172         if ($changelevel == 0) {
173             // no changes in the rubric, no confirmation needed
174             return false;
175         }
177         // freeze form elements and pass the values in hidden fields
178         // TODO description_editor does not freeze the normal way!
179         $form = $this->_form;
180         foreach (array('rubric', 'name'/*, 'description_editor'*/) as $fieldname) {
181             $el =& $form->getElement($fieldname);
182             $el->freeze();
183             $el->setPersistantFreeze(true);
184             if ($fieldname == 'rubric') {
185                 $el->add_regrade_confirmation($changelevel);
186             }
187         }
189         // replace button text 'saverubric' and unfreeze 'Back to edit' button
190         $this->findButton('saverubric')->setValue(get_string('continue'));
191         $el =& $this->findButton('editrubric');
192         $el->setValue(get_string('backtoediting', 'gradingform_rubric'));
193         $el->unfreeze();
195         return true;
196     }
198     /**
199      * Returns a form element (submit button) with the name $elementname
200      *
201      * @param string $elementname
202      * @return HTML_QuickForm_element
203      */
204     protected function &findButton($elementname) {
205         $form = $this->_form;
206         $buttonar =& $form->getElement('buttonar');
207         $elements =& $buttonar->getElements();
208         foreach ($elements as $el) {
209             if ($el->getName() == $elementname) {
210                 return $el;
211             }
212         }
213         return null;
214     }