MDL-61625 persistent form: Add missing param to the constructor
[moodle.git] / lib / classes / form / persistent.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  * Persistent form abstract.
19  *
20  * @package    core
21  * @copyright  2015 Frédéric Massart - FMCorz.net
22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 namespace core\form;
26 defined('MOODLE_INTERNAL') || die();
28 use coding_exception;
29 use moodleform;
30 use stdClass;
32 require_once($CFG->libdir.'/formslib.php');
34 /**
35  * Persistent form abstract class.
36  *
37  * This provides some shortcuts to validate objects based on the persistent model.
38  *
39  * Note that all mandatory fields (non-optional) of your model should be included in the
40  * form definition. Mandatory fields which are not editable by the user should be
41  * as hidden and constant.
42  *
43  *    $mform->addElement('hidden', 'userid');
44  *    $mform->setType('userid', PARAM_INT);
45  *    $mform->setConstant('userid', $this->_customdata['userid']);
46  *
47  * You may exclude some fields from the validation should your form include other
48  * properties such as files. To do so use the $foreignfields property.
49  *
50  * @package    core
51  * @copyright  2015 Frédéric Massart - FMCorz.net
52  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
53  */
54 abstract class persistent extends moodleform {
56     /** @var string The fully qualified classname. */
57     protected static $persistentclass = null;
59     /** @var array Fields to remove when getting the final data. */
60     protected static $fieldstoremove = array('submitbutton');
62     /** @var array Fields to remove from the persistent validation. */
63     protected static $foreignfields = array();
65     /** @var \core\peristent Reference to the persistent. */
66     private $persistent = null;
68     /**
69      * Constructor.
70      *
71      * The 'persistent' has to be passed as custom data when 'editing'.
72      *
73      * Note that in order for your persistent to be reloaded after form submission you should
74      * either override the URL to include the ID to your resource, or add the ID to the form
75      * fields.
76      *
77      * @param mixed $action
78      * @param mixed $customdata
79      * @param string $method
80      * @param string $target
81      * @param mixed $attributes
82      * @param bool $editable
83      * @param array $ajaxformdata
84      */
85     public function __construct($action = null, $customdata = null, $method = 'post', $target = '',
86                                 $attributes = null, $editable = true, $ajaxformdata=null) {
87         if (empty(static::$persistentclass)) {
88             throw new coding_exception('Static property $persistentclass must be set.');
89         } else if (!is_subclass_of(static::$persistentclass, 'core\\persistent')) {
90             throw new coding_exception('Static property $persistentclass is not valid.');
91         } else if (!array_key_exists('persistent', $customdata)) {
92             throw new coding_exception('The custom data \'persistent\' key must be set, even if it is null.');
93         }
95         // Make a copy of the persistent passed, this ensures validation and object reference issues.
96         $persistendata = new stdClass();
97         $persistent = isset($customdata['persistent']) ? $customdata['persistent'] : null;
98         if ($persistent) {
99             if (!($persistent instanceof static::$persistentclass)) {
100                 throw new coding_exception('Invalid persistent');
101             }
102             $persistendata = $persistent->to_record();
103             unset($persistent);
104         }
106         $this->persistent = new static::$persistentclass();
107         $this->persistent->from_record($persistendata);
109         unset($customdata['persistent']);
110         parent::__construct($action, $customdata, $method, $target, $attributes, $editable, $ajaxformdata);
112         // Load the defaults.
113         $this->set_data($this->get_default_data());
114     }
116     /**
117      * Convert some fields.
118      *
119      * @param  stdClass $data The whole data set.
120      * @return stdClass The amended data set.
121      */
122     protected static function convert_fields(stdClass $data) {
123         $class = static::$persistentclass;
124         $properties = $class::get_formatted_properties();
126         foreach ($data as $field => $value) {
127             // Replace formatted properties.
128             if (isset($properties[$field])) {
129                 $formatfield = $properties[$field];
130                 $data->$formatfield = $data->{$field}['format'];
131                 $data->$field = $data->{$field}['text'];
132             }
133         }
135         return $data;
136     }
138     /**
139      * After definition hook.
140      *
141      * Automatically try to set the types of simple fields using the persistent properties definition.
142      * This only applies to hidden, text and url types. Groups are also ignored as they are most likely custom.
143      *
144      * @return void
145      */
146     protected function after_definition() {
147         parent::after_definition();
148         $mform = $this->_form;
150         $class = static::$persistentclass;
151         $properties = $class::properties_definition();
153         foreach ($mform->_elements as $element) {
154             $name = $element->getName();
156             if (isset($mform->_types[$name])) {
157                 // We already have a PARAM_* type for this field.
158                 continue;
160             } else if (!isset($properties[$name]) || in_array($name, static::$fieldstoremove)
161                     || in_array($name, static::$foreignfields)) {
162                 // Ignoring foreign and unknown fields.
163                 continue;
164             }
166             // Set the type on the element.
167             switch ($element->getType()) {
168                 case 'hidden':
169                 case 'text':
170                 case 'url':
171                     $mform->setType($name, $properties[$name]['type']);
172                     break;
173             }
174         }
175     }
177     /**
178      * Define extra validation mechanims.
179      *
180      * The data here:
181      * - does not include {@link self::$fieldstoremove}.
182      * - does include {@link self::$foreignfields}.
183      * - was converted to map persistent-like data, e.g. array $description to string $description + int $descriptionformat.
184      *
185      * You can modify the $errors parameter in order to remove some validation errors should you
186      * need to. However, the best practice is to return new or overriden errors. Only modify the
187      * errors passed by reference when you have no other option.
188      *
189      * Do not add any logic here, it is only intended to be used by child classes.
190      *
191      * @param  stdClass $data Data to validate.
192      * @param  array $files Array of files.
193      * @param  array $errors Currently reported errors.
194      * @return array of additional errors, or overridden errors.
195      */
196     protected function extra_validation($data, $files, array &$errors) {
197         return array();
198     }
200     /**
201      * Filter out the foreign fields of the persistent.
202      *
203      * This can be overridden to filter out more complex fields.
204      *
205      * @param stdClass $data The data to filter the fields out of.
206      * @return stdClass.
207      */
208     protected function filter_data_for_persistent($data) {
209         return (object) array_diff_key((array) $data, array_flip((array) static::$foreignfields));
210     }
212     /**
213      * Get the default data.
214      *
215      * This is the data that is prepopulated in the form at it loads, we automatically
216      * fetch all the properties of the persistent however some needs to be converted
217      * to map the form structure.
218      *
219      * Extend this class if you need to add more conversion.
220      *
221      * @return stdClass
222      */
223     protected function get_default_data() {
224         $data = $this->get_persistent()->to_record();
225         $class = static::$persistentclass;
226         $properties = $class::get_formatted_properties();
227         $allproperties = $class::properties_definition();
229         foreach ($data as $field => $value) {
230             // Clean data if it is to be displayed in a form.
231             if (isset($allproperties[$field]['type'])) {
232                 $data->$field = clean_param($data->$field, $allproperties[$field]['type']);
233             }
235             if (isset($properties[$field])) {
236                 $data->$field = array(
237                     'text' => $data->$field,
238                     'format' => $data->{$properties[$field]}
239                 );
240                 unset($data->{$properties[$field]});
241             }
242         }
244         return $data;
245     }
247     /**
248      * Get form data.
249      *
250      * Conveniently removes non-desired properties and add the ID property.
251      *
252      * @return object|null
253      */
254     public function get_data() {
255         $data = parent::get_data();
256         if (is_object($data)) {
257             foreach (static::$fieldstoremove as $field) {
258                 unset($data->{$field});
259             }
260             $data = static::convert_fields($data);
262             // Ensure that the ID is set.
263             $data->id = $this->persistent->get('id');
264         }
265         return $data;
266     }
268     /**
269      * Return the persistent object associated with this form instance.
270      *
271      * @return core\persistent
272      */
273     final protected function get_persistent() {
274         return $this->persistent;
275     }
277     /**
278      * Get the submitted form data.
279      *
280      * Conveniently removes non-desired properties.
281      *
282      * @return object|null
283      */
284     public function get_submitted_data() {
285         $data = parent::get_submitted_data();
286         if (is_object($data)) {
287             foreach (static::$fieldstoremove as $field) {
288                 unset($data->{$field});
289             }
290             $data = static::convert_fields($data);
291         }
292         return $data;
293     }
295     /**
296      * Form validation.
297      *
298      * If you need extra validation, use {@link self::extra_validation()}.
299      *
300      * @param  array $data
301      * @param  array $files
302      * @return array
303      */
304     public final function validation($data, $files) {
305         $errors = parent::validation($data, $files);
306         $data = $this->get_submitted_data();
308         // Only validate compatible fields.
309         $persistentdata = $this->filter_data_for_persistent($data);
310         $persistent = $this->get_persistent();
311         $persistent->from_record((object) $persistentdata);
312         $errors = array_merge($errors, $persistent->get_errors());
314         // Apply extra validation.
315         $extraerrors = $this->extra_validation($data, $files, $errors);
316         $errors = array_merge($errors, (array) $extraerrors);
318         return $errors;
319     }