MDL-46335 backup: fixed casting issue with setting labels
[moodle.git] / backup / util / ui / backup_ui_setting.class.php
CommitLineData
1904e9b3
SH
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 * This file contains the setting user interface classes that all backup/restore
20 * settings use to represent the UI they have.
21 *
22 * @package moodlecore
23 * @copyright 2010 Sam Hemelryk
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
26
27/**
28 * Abstract class used to represent the user interface that a setting has.
29 *
30 * @todo extend as required for restore
31 * @copyright 2010 Sam Hemelryk
32 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
33 */
17f04f53
SH
34class base_setting_ui {
35 /**
36 * Prefix applied to all inputs/selects
37 */
38 const NAME_PREFIX = 'setting_';
39 /**
40 * The name of the setting
41 * @var string
42 */
43 protected $name;
44 /**
45 * The label for the setting
46 * @var string
47 */
48 protected $label;
49 /**
50 * An array of HTML attributes to apply to this setting
51 * @var array
52 */
53 protected $attributes = array();
54 /**
55 * The backup_setting UI type this relates to. One of backup_setting::UI_*;
56 * @var int
57 */
58 protected $type;
83c000d9
SH
59 /**
60 * An icon to display next to this setting in the UI
61 * @var pix_icon
62 */
63 protected $icon = false;
1904e9b3 64 /**
39bc4c6f
SH
65 * The setting this UI belongs to (parent reference)
66 * @var base_setting|backup_setting
1904e9b3
SH
67 */
68 protected $setting;
69 /**
70 * Constructors are sooooo cool
71 * @param base_setting $setting
72 */
73 public function __construct(base_setting $setting) {
74 $this->setting = $setting;
75 }
287e8040
EL
76
77 /**
78 * Destroy all circular references. It helps PHP 5.2 a lot!
79 */
80 public function destroy() {
81 // No need to destroy anything recursively here, direct reset
82 $this->setting = null;
83 }
84
1904e9b3 85 /**
17f04f53
SH
86 * Gets the name of this item including its prefix
87 * @return string
1904e9b3 88 */
17f04f53
SH
89 public function get_name() {
90 return self::NAME_PREFIX.$this->name;
91 }
1904e9b3 92 /**
17f04f53
SH
93 * Gets the name of this item including its prefix
94 * @return string
1904e9b3 95 */
17f04f53
SH
96 public function get_label() {
97 return $this->label;
98 }
1904e9b3 99 /**
17f04f53
SH
100 * Gets the type of this element
101 * @return int
1904e9b3 102 */
17f04f53
SH
103 public function get_type() {
104 return $this->type;
105 }
1904e9b3 106 /**
17f04f53
SH
107 * Gets the HTML attributes for this item
108 * @return array
1904e9b3 109 */
17f04f53
SH
110 public function get_attributes() {
111 return $this->attributes;
112 }
1904e9b3 113 /**
17f04f53
SH
114 * Gets the value of this setting
115 * @return mixed
1904e9b3 116 */
17f04f53
SH
117 public function get_value() {
118 return $this->setting->get_value();
119 }
1904e9b3 120 /**
17f04f53
SH
121 * Gets the value to display in a static quickforms element
122 * @return mixed
1904e9b3 123 */
17f04f53
SH
124 public function get_static_value() {
125 return $this->setting->get_value();
126 }
5ae69b2a
EL
127
128 /**
129 * Gets the the PARAM_XXXX validation to be applied to the setting
130 *
131 * return string The PARAM_XXXX constant of null if the setting type is not defined
132 */
133 public function get_param_validation() {
134 return $this->setting->get_param_validation();
135 }
136
17f04f53
SH
137 /**
138 * Sets the label
139 * @param string $label
140 */
141 public function set_label($label) {
a8266e2f
SH
142 $label = (string)$label;
143 if ($label === '' || $label !== clean_param($label, PARAM_TEXT)) {
86e0afcf
SH
144 throw new base_setting_ui_exception('setting_invalid_ui_label');
145 }
17f04f53
SH
146 $this->label = $label;
147 }
148 /**
149 * Disables the UI for this element
150 */
151 public function disable() {
152 $this->attributes['disabled'] = 'disabled';
153 }
83c000d9
SH
154
155 /**
156 * Sets the icon to display next to this item
157 *
158 * @param pix_icon $icon
159 */
160 public function set_icon(pix_icon $icon) {
161 $this->icon = $icon;
162 }
163
164 /**
165 * Returns the icon to display next to this item, or false if there isn't one.
166 *
167 * @return pix_icon|false
168 */
169 public function get_icon() {
170 if (!empty($this->icon)) {
171 return $this->icon;
172 }
173 return false;
174 }
17f04f53
SH
175}
176
177/**
178 * Abstract class to represent the user interface backup settings have
940a91a6 179 *
17f04f53
SH
180 * @copyright 2010 Sam Hemelryk
181 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
182 */
183abstract class backup_setting_ui extends base_setting_ui {
1904e9b3
SH
184 /**
185 * An array of options relating to this setting
186 * @var array
187 */
188 protected $options = array();
189
190 /**
191 * JAC... Just Another Constructor
192 *
193 * @param backup_setting $setting
194 * @param string|null $label The label to display with the setting ui
195 * @param array|null $attributes Array of HTML attributes to apply to the element
196 * @param array|null $options Array of options to apply to the setting ui object
197 */
198 public function __construct(backup_setting $setting, $label = null, array $attributes = null, array $options = null) {
199 parent::__construct($setting);
200 // Improve the inputs name by appending the level to the name
201 switch ($setting->get_level()) {
202 case backup_setting::ROOT_LEVEL :
203 $this->name = 'root_'.$setting->get_name();
204 break;
205 case backup_setting::COURSE_LEVEL :
206 $this->name = 'course_'.$setting->get_name();
207 break;
208 case backup_setting::SECTION_LEVEL :
209 $this->name = 'section_'.$setting->get_name();
210 break;
211 case backup_setting::ACTIVITY_LEVEL :
212 $this->name = 'activity_'.$setting->get_name();
213 break;
214 }
215 $this->label = $label;
216 if (is_array($attributes)) {
217 $this->attributes = $attributes;
218 }
219 if (is_array($options)) {
220 $this->options = $options;
221 }
222 }
223 /**
224 * Creates a new backup setting ui based on the setting it is given
225 *
86e0afcf
SH
226 * Throws an exception if an invalid type is provided.
227 *
1904e9b3
SH
228 * @param backup_setting $setting
229 * @param int $type The backup_setting UI type. One of backup_setting::UI_*;
230 * @param string $label The label to display with the setting ui
231 * @param array $attributes Array of HTML attributes to apply to the element
232 * @param array $options Array of options to apply to the setting ui object
940a91a6 233 *
86e0afcf 234 * @return backup_setting_ui_text|backup_setting_ui_checkbox|backup_setting_ui_select|backup_setting_ui_radio
1904e9b3
SH
235 */
236 final public static function make(backup_setting $setting, $type, $label, array $attributes = null, array $options=null) {
237 // Base the decision we make on the type that was sent
238 switch ($type) {
239 case backup_setting::UI_HTML_CHECKBOX :
240 return new backup_setting_ui_checkbox($setting, $label, null, (array)$attributes, (array)$options);
241 case backup_setting::UI_HTML_DROPDOWN :
242 return new backup_setting_ui_select($setting, $label, null, (array)$attributes, (array)$options);
243 case backup_setting::UI_HTML_RADIOBUTTON :
244 return new backup_setting_ui_radio($setting, $label, null, null, (array)$attributes, (array)$options);
245 case backup_setting::UI_HTML_TEXTFIELD :
246 return new backup_setting_ui_text($setting, $label, $attributes, $options);
247 default:
86e0afcf 248 throw new backup_setting_ui_exception('setting_invalid_ui_type');
1904e9b3
SH
249 }
250 }
17f04f53
SH
251 /**
252 * Get element properties that can be used to make a quickform element
253 * @return array
254 */
83c000d9 255 abstract public function get_element_properties(base_task $task=null, renderer_base $output=null);
1904e9b3
SH
256 /**
257 * Applies config options to a given properties array and then returns it
258 * @param array $properties
259 * @return array
260 */
261 public function apply_options(array $properties) {
8f87420a
SH
262 if (!empty($this->options['size'])) {
263 $properties['attributes']['size'] = $this->options['size'];
264 }
1904e9b3
SH
265 return $properties;
266 }
1904e9b3
SH
267 /**
268 * Gets the label for this item
269 * @param backup_task|null $task Optional, if provided and the setting is an include
270 * $task is used to set the setting label
271 * @return string
272 */
785d6603 273 public function get_label(base_task $task=null) {
1904e9b3
SH
274 // If a task has been provided and the label is not already set meaniningfully
275 // we will attempt to improve it.
276 if (!is_null($task) && $this->label == $this->setting->get_name() && strpos($this->setting->get_name(), '_include')!==false) {
277 if ($this->setting->get_level() == backup_setting::SECTION_LEVEL) {
278 $this->label = get_string('includesection', 'backup', $task->get_name());
279 } else if ($this->setting->get_level() == backup_setting::ACTIVITY_LEVEL) {
573cdf85 280 $this->label = $task->get_name();
1904e9b3
SH
281 }
282 }
283 return $this->label;
284 }
61ebef8f
SH
285 /**
286 * Returns true if the setting is changeable.
287 *
288 * A setting is changeable if it meets either of the two following conditions.
289 *
290 * 1. The setting is not locked
291 * 2. The setting is locked but only by settings that are of the same level (same page)
292 *
293 * Condition 2 is really why we have this function
294 *
295 * @return bool
296 */
297 public function is_changeable() {
298 if ($this->setting->get_status() === backup_setting::NOT_LOCKED) {
299 // Its not locked so its chanegable
300 return true;
301 } else if ($this->setting->get_status() !== backup_setting::LOCKED_BY_HIERARCHY) {
302 // Its not changeable because its locked by permission or config
303 return false;
304 } else if ($this->setting->has_dependencies_on_settings()) {
305 foreach ($this->setting->get_settings_depended_on() as $dependency) {
306 if ($dependency->is_locked() && $dependency->get_setting()->get_level() !== $this->setting->get_level()) {
307 // Its not changeable because one or more dependancies arn't
308 // changeable.
309 return false;
310 }
311 }
312 // Its changeable because all dependencies are changeable.
313 return true;
314 }
315 // We should never get here but if we do return false to be safe.
316 // The setting would need to be locked by hierarchy and not have any deps
317 return false;
318 }
319
1904e9b3
SH
320}
321
322/**
323 * A text input user interface element for backup settings
324 *
325 * @copyright 2010 Sam Hemelryk
326 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
327 */
328class backup_setting_ui_text extends backup_setting_ui {
329 /**
330 * @var int
331 */
332 protected $type = backup_setting::UI_HTML_TEXTFIELD;
333 /**
334 * Returns an array of properties suitable for generating a quickforms element
335 * @param backup_task|null $task
336 * @return array (element, name, label, attributes)
337 */
83c000d9
SH
338 public function get_element_properties(base_task $task=null, renderer_base $output=null) {
339 // name, label, text, attributes
340 $icon = $this->get_icon();
341 $label = $this->get_label($task);
342 if (!empty($icon)) {
d9f95015 343 $label .= $output->render($icon);
83c000d9 344 }
1904e9b3 345 // name, label, attributes
83c000d9 346 return $this->apply_options(array('element'=>'text','name'=>self::NAME_PREFIX.$this->name, 'label'=>$label, 'attributes'=>$this->attributes));
1904e9b3
SH
347 }
348
349}
350
351/**
352 * A checkbox user interface element for backup settings (default)
353 *
354 * @copyright 2010 Sam Hemelryk
355 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
356 */
357class backup_setting_ui_checkbox extends backup_setting_ui {
358 /**
359 * @var int
360 */
361 protected $type = backup_setting::UI_HTML_CHECKBOX;
573cdf85
SH
362 /**
363 * @var bool
364 */
365 protected $changeable = true;
1904e9b3
SH
366 /**
367 * The text to show next to the checkbox
368 * @var string
369 */
370 protected $text;
371 /**
372 * Overridden constructor so we can take text argument
373 * @param backup_setting $setting
374 * @param string $label
375 * @param string $text
376 * @param array $attributes
377 * @param array $options
378 */
379 public function __construct(backup_setting $setting, $label = null, $text=null, array $attributes = array(), array $options = array()) {
380 parent::__construct($setting, $label, $attributes, $options);
381 $this->text = $text;
382 }
383 /**
384 * Returns an array of properties suitable for generating a quickforms element
385 * @param backup_task|null $task
386 * @return array (element, name, label, text, attributes);
387 */
83c000d9 388 public function get_element_properties(base_task $task=null, renderer_base $output=null) {
1904e9b3 389 // name, label, text, attributes
940a91a6 390
83c000d9
SH
391 $icon = $this->get_icon();
392 $label = $this->get_label($task);
393 if (!empty($icon)) {
d9f95015 394 $label .= $output->render($icon);
83c000d9
SH
395 }
396 return $this->apply_options(array('element'=>'checkbox','name'=>self::NAME_PREFIX.$this->name, 'label'=>$label, 'text'=>$this->text, 'attributes'=>$this->attributes));
1904e9b3
SH
397 }
398 /**
399 * Sets the text for the element
400 * @param string $text
401 */
402 public function set_text($text) {
940a91a6 403 $this->text = $text;
1904e9b3
SH
404 }
405 /**
406 * Gets the static value for the element
83c000d9 407 * @global core_renderer $OUTPUT
1904e9b3
SH
408 * @return string
409 */
410 public function get_static_value() {
83c000d9 411 global $OUTPUT;
1904e9b3
SH
412 // Checkboxes are always yes or no
413 if ($this->get_value()) {
c3847443 414 return $OUTPUT->pix_icon('i/valid', get_string('yes'));
1904e9b3 415 } else {
c3847443 416 return $OUTPUT->pix_icon('i/invalid', get_string('no'));
1904e9b3
SH
417 }
418 }
573cdf85
SH
419
420 /**
421 * Returns true if the setting is changeable
422 * @return bool
423 */
424 public function is_changeable() {
425 if ($this->changeable===false) {
426 return false;
427 } else {
428 return parent::is_changeable();
429 }
430 }
431
432 /**
433 * Sets whether the setting is changeable,
434 * Note dependencies can still mark this setting changeable or not
435 * @param bool $newvalue
436 */
437 public function set_changeable($newvalue) {
438 $this->changeable = ($newvalue);
439 }
1904e9b3
SH
440}
441
442/**
443 * Radio button user interface element for backup settings
444 *
445 * @copyright 2010 Sam Hemelryk
446 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
447 */
448class backup_setting_ui_radio extends backup_setting_ui {
449 /**
450 * @var int
451 */
452 protected $type = backup_setting::UI_HTML_RADIOBUTTON;
453 /**
454 * The string shown next to the input
455 * @var string
456 */
457 protected $text;
458 /**
459 * The value for the radio input
460 * @var string
461 */
462 protected $value;
463 /**
464 *
465 * @param backup_setting $setting
466 * @param string $label
467 * @param string $text
468 * @param string $value
469 * @param array $attributes
470 * @param array $options
471 */
472 public function __construct(backup_setting $setting, $label = null, $text=null, $value=null, array $attributes = array(), array $options = array()) {
473 parent::__construct($setting, $label, $attributes, $options);
474 $this->text = $text;
475 $this->value = (string)$value;
476 }
477 /**
478 * Returns an array of properties suitable for generating a quickforms element
479 * @param backup_task|null $task
480 * @return array (element, name, label, text, value, attributes)
481 */
83c000d9
SH
482 public function get_element_properties(base_task $task=null, renderer_base $output=null) {
483 // name, label, text, attributes
484 $icon = $this->get_icon();
485 $label = $this->get_label($task);
486 if (!empty($icon)) {
d9f95015 487 $label .= $output->render($icon);
83c000d9 488 }
1904e9b3 489 // name, label, text, value, attributes
83c000d9 490 return $this->apply_options(array('element'=>'radio','name'=>self::NAME_PREFIX.$this->name, 'label'=>$label, 'text'=>$this->text, 'value'=>$this->value, 'attributes'=>$this->attributes));
1904e9b3
SH
491 }
492 /**
493 * Sets the text next to this input
494 * @param text $text
495 */
496 public function set_text($text) {
940a91a6 497 $this->text = $text;
1904e9b3
SH
498 }
499 /**
500 * Sets the value for the input
501 * @param string $value
502 */
503 public function set_value($value) {
940a91a6 504 $this->value = (string)$value;
1904e9b3
SH
505 }
506 /**
507 * Gets the static value to show for the element
508 */
509 public function get_static_value() {
510 return $this->value;
511 }
512}
513
514/**
515 * A select box, drop down user interface for backup settings
516 *
517 * @copyright 2010 Sam Hemelryk
518 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
519 */
520class backup_setting_ui_select extends backup_setting_ui {
521 /**
522 * @var int
523 */
524 protected $type = backup_setting::UI_HTML_DROPDOWN;
525 /**
526 * An array of options to display in the select
527 * @var array
528 */
529 protected $values;
530 /**
531 *
532 * @param backup_setting $setting
533 * @param string $label
534 * @param array $values
535 * @param array $attributes
536 * @param array $options
537 */
538 public function __construct(backup_setting $setting, $label = null, $values=null, array $attributes = array(), array $options = array()) {
539 parent::__construct($setting, $label, $attributes, $options);
540 $this->values = $values;
541 }
542 /**
543 * Returns an array of properties suitable for generating a quickforms element
544 * @param backup_task|null $task
545 * @return array (element, name, label, options, attributes)
546 */
83c000d9
SH
547 public function get_element_properties(base_task $task = null, renderer_base $output=null) {
548 // name, label, text, attributes
549 $icon = $this->get_icon();
550 $label = $this->get_label($task);
551 if (!empty($icon)) {
d9f95015 552 $label .= $output->render($icon);
83c000d9 553 }
1904e9b3 554 // name, label, options, attributes
83c000d9 555 return $this->apply_options(array('element'=>'select','name'=>self::NAME_PREFIX.$this->name, 'label'=>$label, 'options'=>$this->values, 'attributes'=>$this->attributes));
1904e9b3
SH
556 }
557 /**
558 * Sets the options for the select box
559 * @param array $values Associative array of value=>text options
560 */
561 public function set_values(array $values) {
562 $this->values = $values;
563 }
564 /**
565 * Gets the static value for this select element
566 * @return string
567 */
568 public function get_static_value() {
569 return $this->values[$this->get_value()];
570 }
573cdf85
SH
571 /**
572 * Returns true if the setting is changeable, false otherwise
573 *
574 * @return bool
575 */
785d6603
SH
576 public function is_changeable() {
577 if (count($this->values) == 1) {
578 return false;
579 } else {
580 return parent::is_changeable();
581 }
582 }
583}
584
585class backup_setting_ui_dateselector extends backup_setting_ui_text {
83c000d9 586 public function get_element_properties(base_task $task = null, renderer_base $output=null) {
785d6603
SH
587 if (!array_key_exists('optional', $this->attributes)) {
588 $this->attributes['optional'] = false;
589 }
83c000d9 590 $properties = parent::get_element_properties($task, $output);
785d6603
SH
591 $properties['element'] = 'date_selector';
592 return $properties;
593 }
594 public function get_static_value() {
595 $value = $this->get_value();
596 if (!empty($value)) {
597 return userdate($value);
598 }
599 return parent::get_static_value();
600 }
86e0afcf
SH
601}
602
603class base_setting_ui_exception extends base_setting_exception {}
287e8040 604class backup_setting_ui_exception extends base_setting_ui_exception {};