See Release Notes
Long Term Support Release
Differences Between: [Versions 39 and 310] [Versions 39 and 311] [Versions 39 and 400] [Versions 39 and 401] [Versions 39 and 402] [Versions 39 and 403]
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/>. 16 17 /** 18 * This file contains the setting user interface classes that all backup/restore 19 * settings use to represent the UI they have. 20 * 21 * @package core_backup 22 * @copyright 2010 Sam Hemelryk 23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 24 */ 25 26 /** 27 * Abstract class used to represent the user interface that a setting has. 28 * 29 * @todo extend as required for restore 30 * @package core_backup 31 * @copyright 2010 Sam Hemelryk 32 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 33 */ 34 class 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; 59 /** 60 * An icon to display next to this setting in the UI 61 * @var pix_icon 62 */ 63 protected $icon = false; 64 /** 65 * The setting this UI belongs to (parent reference) 66 * @var base_setting|backup_setting 67 */ 68 protected $setting; 69 70 /** 71 * Constructors are sooooo cool 72 * @param base_setting $setting 73 */ 74 public function __construct(base_setting $setting) { 75 $this->setting = $setting; 76 } 77 78 /** 79 * Destroy all circular references. It helps PHP 5.2 a lot! 80 */ 81 public function destroy() { 82 // No need to destroy anything recursively here, direct reset. 83 $this->setting = null; 84 } 85 86 /** 87 * Gets the name of this item including its prefix 88 * @return string 89 */ 90 public function get_name() { 91 return self::NAME_PREFIX.$this->name; 92 } 93 94 /** 95 * Gets the name of this item including its prefix 96 * @return string 97 */ 98 public function get_label() { 99 return $this->label; 100 } 101 102 /** 103 * Gets the type of this element 104 * @return int 105 */ 106 public function get_type() { 107 return $this->type; 108 } 109 110 /** 111 * Gets the HTML attributes for this item 112 * @return array 113 */ 114 public function get_attributes() { 115 return $this->attributes; 116 } 117 118 /** 119 * Gets the value of this setting 120 * @return mixed 121 */ 122 public function get_value() { 123 return $this->setting->get_value(); 124 } 125 126 /** 127 * Gets the value to display in a static quickforms element 128 * @return mixed 129 */ 130 public function get_static_value() { 131 return $this->setting->get_value(); 132 } 133 134 /** 135 * Gets the the PARAM_XXXX validation to be applied to the setting 136 * 137 * return string The PARAM_XXXX constant of null if the setting type is not defined 138 */ 139 public function get_param_validation() { 140 return $this->setting->get_param_validation(); 141 } 142 143 /** 144 * Sets the label. 145 * 146 * @throws base_setting_ui_exception when the label is not valid. 147 * @param string $label 148 */ 149 public function set_label($label) { 150 $label = (string)$label; 151 if ($label === '' || $label !== clean_param($label, PARAM_TEXT)) { 152 throw new base_setting_ui_exception('setting_invalid_ui_label'); 153 } 154 $this->label = $label; 155 } 156 157 /** 158 * Disables the UI for this element 159 */ 160 public function disable() { 161 $this->attributes['disabled'] = 'disabled'; 162 } 163 164 /** 165 * Sets the icon to display next to this item 166 * 167 * @param pix_icon $icon 168 */ 169 public function set_icon(pix_icon $icon) { 170 $this->icon = $icon; 171 } 172 173 /** 174 * Returns the icon to display next to this item, or false if there isn't one. 175 * 176 * @return pix_icon|false 177 */ 178 public function get_icon() { 179 if (!empty($this->icon)) { 180 return $this->icon; 181 } 182 return false; 183 } 184 } 185 186 /** 187 * Abstract class to represent the user interface backup settings have 188 * 189 * @package core_backup 190 * @copyright 2010 Sam Hemelryk 191 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 192 */ 193 abstract class backup_setting_ui extends base_setting_ui { 194 /** 195 * An array of options relating to this setting 196 * @var array 197 */ 198 protected $options = array(); 199 200 /** 201 * JAC... Just Another Constructor 202 * 203 * @param backup_setting $setting 204 * @param string $label The label to display with the setting ui 205 * @param array $attributes Array of HTML attributes to apply to the element 206 * @param array $options Array of options to apply to the setting ui object 207 */ 208 public function __construct(backup_setting $setting, $label = null, array $attributes = null, array $options = null) { 209 parent::__construct($setting); 210 // Improve the inputs name by appending the level to the name. 211 switch ($setting->get_level()) { 212 case backup_setting::ROOT_LEVEL : 213 $this->name = 'root_'.$setting->get_name(); 214 break; 215 case backup_setting::COURSE_LEVEL : 216 $this->name = 'course_'.$setting->get_name(); 217 break; 218 case backup_setting::SECTION_LEVEL : 219 $this->name = 'section_'.$setting->get_name(); 220 break; 221 case backup_setting::ACTIVITY_LEVEL : 222 $this->name = 'activity_'.$setting->get_name(); 223 break; 224 } 225 $this->label = $label; 226 if (is_array($attributes)) { 227 $this->attributes = $attributes; 228 } 229 if (is_array($options)) { 230 $this->options = $options; 231 } 232 } 233 234 /** 235 * Creates a new backup setting ui based on the setting it is given 236 * 237 * @throws backup_setting_ui_exception if the setting type is not supported, 238 * @param backup_setting $setting 239 * @param int $type The backup_setting UI type. One of backup_setting::UI_*; 240 * @param string $label The label to display with the setting ui 241 * @param array $attributes Array of HTML attributes to apply to the element 242 * @param array $options Array of options to apply to the setting ui object 243 * @return backup_setting_ui_text|backup_setting_ui_checkbox|backup_setting_ui_select|backup_setting_ui_radio 244 */ 245 final public static function make(backup_setting $setting, $type, $label, array $attributes = null, array $options = null) { 246 // Base the decision we make on the type that was sent. 247 switch ($type) { 248 case backup_setting::UI_HTML_CHECKBOX : 249 return new backup_setting_ui_checkbox($setting, $label, null, (array)$attributes, (array)$options); 250 case backup_setting::UI_HTML_DROPDOWN : 251 return new backup_setting_ui_select($setting, $label, null, (array)$attributes, (array)$options); 252 case backup_setting::UI_HTML_RADIOBUTTON : 253 return new backup_setting_ui_radio($setting, $label, null, null, (array)$attributes, (array)$options); 254 case backup_setting::UI_HTML_TEXTFIELD : 255 return new backup_setting_ui_text($setting, $label, $attributes, $options); 256 default: 257 throw new backup_setting_ui_exception('setting_invalid_ui_type'); 258 } 259 } 260 261 /** 262 * Get element properties that can be used to make a quickform element 263 * 264 * @param base_task $task 265 * @param renderer_base $output 266 * @return array 267 */ 268 abstract public function get_element_properties(base_task $task = null, renderer_base $output = null); 269 270 /** 271 * Applies config options to a given properties array and then returns it 272 * @param array $properties 273 * @return array 274 */ 275 public function apply_options(array $properties) { 276 if (!empty($this->options['size'])) { 277 $properties['attributes']['size'] = $this->options['size']; 278 } 279 return $properties; 280 } 281 282 /** 283 * Gets the label for this item 284 * @param base_task $task Optional, if provided and the setting is an include 285 * $task is used to set the setting label 286 * @return string 287 */ 288 public function get_label(base_task $task = null) { 289 // If a task has been provided and the label is not already set meaningfully 290 // we will attempt to improve it. 291 if (!is_null($task) && $this->label == $this->setting->get_name() && strpos($this->setting->get_name(), '_include') !== false) { 292 if ($this->setting->get_level() == backup_setting::SECTION_LEVEL) { 293 $this->label = get_string('includesection', 'backup', $task->get_name()); 294 } else if ($this->setting->get_level() == backup_setting::ACTIVITY_LEVEL) { 295 $this->label = $task->get_name(); 296 } 297 } 298 return $this->label; 299 } 300 301 /** 302 * Returns true if the setting is changeable. 303 * 304 * A setting is changeable if it meets either of the two following conditions. 305 * 306 * 1. The setting is not locked 307 * 2. The setting is locked but only by settings that are of the same level (same page) 308 * 309 * Condition 2 is really why we have this function 310 * @param int $level Optional, if provided only depedency_settings below or equal to this level are considered, 311 * when checking if the ui_setting is changeable. Although dependencies might cause a lock on this setting, 312 * they could be changeable in the same view. 313 * @return bool 314 */ 315 public function is_changeable($level = null) { 316 if ($this->setting->get_status() === backup_setting::NOT_LOCKED) { 317 // Its not locked so its chanegable. 318 return true; 319 } else if ($this->setting->get_status() !== backup_setting::LOCKED_BY_HIERARCHY) { 320 // Its not changeable because its locked by permission or config. 321 return false; 322 } else if ($this->setting->has_dependencies_on_settings()) { 323 foreach ($this->setting->get_settings_depended_on() as $dependency) { 324 if ($level && $dependency->get_setting()->get_level() >= $level) { 325 continue; 326 } 327 if ($dependency->is_locked() && $dependency->get_setting()->get_level() !== $this->setting->get_level()) { 328 // Its not changeable because one or more dependancies arn't changeable. 329 return false; 330 } 331 } 332 // Its changeable because all dependencies are changeable. 333 return true; 334 } 335 // We should never get here but if we do return false to be safe. 336 // The setting would need to be locked by hierarchy and not have any deps. 337 return false; 338 } 339 340 } 341 342 /** 343 * A text input user interface element for backup settings 344 * 345 * @package core_backup 346 * @copyright 2010 Sam Hemelryk 347 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 348 */ 349 class backup_setting_ui_text extends backup_setting_ui { 350 /** 351 * @var int 352 */ 353 protected $type = backup_setting::UI_HTML_TEXTFIELD; 354 355 /** 356 * Returns an array of properties suitable for generating a quickforms element 357 * @param base_task $task 358 * @param renderer_base $output 359 * @return array (element, name, label, attributes) 360 */ 361 public function get_element_properties(base_task $task = null, renderer_base $output = null) { 362 $icon = $this->get_icon(); 363 $context = context_course::instance($task->get_courseid()); 364 $label = format_string($this->get_label($task), true, array('context' => $context)); 365 if (!empty($icon)) { 366 $label .= $output->render($icon); 367 } 368 // Name, label, attributes. 369 return $this->apply_options(array( 370 'element' => 'text', 371 'name' => self::NAME_PREFIX.$this->name, 372 'label' => $label, 373 'attributes' => $this->attributes) 374 ); 375 } 376 377 } 378 379 /** 380 * A checkbox user interface element for backup settings (default) 381 * 382 * @package core_backup 383 * @copyright 2010 Sam Hemelryk 384 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 385 */ 386 class backup_setting_ui_checkbox extends backup_setting_ui { 387 388 /** 389 * @var int 390 */ 391 protected $type = backup_setting::UI_HTML_CHECKBOX; 392 393 /** 394 * @var bool 395 */ 396 protected $changeable = true; 397 398 /** 399 * The text to show next to the checkbox 400 * @var string 401 */ 402 protected $text; 403 404 /** 405 * Overridden constructor so we can take text argument 406 * 407 * @param backup_setting $setting 408 * @param string $label 409 * @param string $text 410 * @param array $attributes 411 * @param array $options 412 */ 413 public function __construct(backup_setting $setting, $label = null, $text = null, array $attributes = array(), array $options = array()) { 414 parent::__construct($setting, $label, $attributes, $options); 415 $this->text = $text; 416 } 417 418 /** 419 * Returns an array of properties suitable for generating a quickforms element 420 * @param base_task $task 421 * @param renderer_base $output 422 * @return array (element, name, label, text, attributes); 423 */ 424 public function get_element_properties(base_task $task = null, renderer_base $output = null) { 425 // Name, label, text, attributes. 426 $icon = $this->get_icon(); 427 $context = context_course::instance($task->get_courseid()); 428 $label = format_string($this->get_label($task), true, array('context' => $context)); 429 if (!empty($icon)) { 430 $label .= $output->render($icon); 431 } 432 return $this->apply_options(array( 433 'element' => 'checkbox', 434 'name' => self::NAME_PREFIX.$this->name, 435 'label' => $label, 436 'text' => $this->text, 437 'attributes' => $this->attributes 438 )); 439 } 440 441 /** 442 * Sets the text for the element 443 * @param string $text 444 */ 445 public function set_text($text) { 446 $this->text = $text; 447 } 448 449 /** 450 * Gets the static value for the element 451 * @global core_renderer $OUTPUT 452 * @return string 453 */ 454 public function get_static_value() { 455 global $OUTPUT; 456 // Checkboxes are always yes or no. 457 if ($this->get_value()) { 458 return $OUTPUT->pix_icon('i/valid', get_string('yes')); 459 } else { 460 return $OUTPUT->pix_icon('i/invalid', get_string('no')); 461 } 462 } 463 464 /** 465 * Returns true if the setting is changeable 466 * @param int $level Optional, if provided only depedency_settings below or equal to this level are considered, 467 * when checking if the ui_setting is changeable. Although dependencies might cause a lock on this setting, 468 * they could be changeable in the same view. 469 * @return bool 470 */ 471 public function is_changeable($level = null) { 472 if ($this->changeable === false) { 473 return false; 474 } else { 475 return parent::is_changeable($level); 476 } 477 } 478 479 /** 480 * Sets whether the setting is changeable, 481 * Note dependencies can still mark this setting changeable or not 482 * @param bool $newvalue 483 */ 484 public function set_changeable($newvalue) { 485 $this->changeable = ($newvalue); 486 } 487 } 488 489 /** 490 * Radio button user interface element for backup settings 491 * 492 * @package core_backup 493 * @copyright 2010 Sam Hemelryk 494 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 495 */ 496 class backup_setting_ui_radio extends backup_setting_ui { 497 /** 498 * @var int 499 */ 500 protected $type = backup_setting::UI_HTML_RADIOBUTTON; 501 502 /** 503 * The string shown next to the input 504 * @var string 505 */ 506 protected $text; 507 508 /** 509 * The value for the radio input 510 * @var string 511 */ 512 protected $value; 513 514 /** 515 * Constructor 516 * 517 * @param backup_setting $setting 518 * @param string $label 519 * @param string $text 520 * @param string $value 521 * @param array $attributes 522 * @param array $options 523 */ 524 public function __construct(backup_setting $setting, $label = null, $text = null, $value = null, array $attributes = array(), array $options = array()) { 525 parent::__construct($setting, $label, $attributes, $options); 526 $this->text = $text; 527 $this->value = (string)$value; 528 } 529 530 /** 531 * Returns an array of properties suitable for generating a quickforms element 532 * @param base_task $task 533 * @param renderer_base $output 534 * @return array (element, name, label, text, value, attributes) 535 */ 536 public function get_element_properties(base_task $task = null, renderer_base $output = null) { 537 $icon = $this->get_icon(); 538 $context = context_course::instance($task->get_courseid()); 539 $label = format_string($this->get_label($task), true, array('context' => $context)); 540 if (!empty($icon)) { 541 $label .= $output->render($icon); 542 } 543 // Name, label, text, value, attributes. 544 return $this->apply_options(array( 545 'element' => 'radio', 546 'name' => self::NAME_PREFIX.$this->name, 547 'label' => $label, 548 'text' => $this->text, 549 'value' => $this->value, 550 'attributes' => $this->attributes 551 )); 552 } 553 /** 554 * Sets the text next to this input 555 * @param text $text 556 */ 557 public function set_text($text) { 558 $this->text = $text; 559 } 560 /** 561 * Sets the value for the input 562 * @param string $value 563 */ 564 public function set_value($value) { 565 $this->value = (string)$value; 566 } 567 /** 568 * Gets the static value to show for the element 569 */ 570 public function get_static_value() { 571 return $this->value; 572 } 573 } 574 575 /** 576 * A select box, drop down user interface for backup settings 577 * 578 * @package core_backup 579 * @copyright 2010 Sam Hemelryk 580 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 581 */ 582 class backup_setting_ui_select extends backup_setting_ui { 583 /** 584 * @var int 585 */ 586 protected $type = backup_setting::UI_HTML_DROPDOWN; 587 588 /** 589 * An array of options to display in the select 590 * @var array 591 */ 592 protected $values; 593 594 /** 595 * Constructor 596 * 597 * @param backup_setting $setting 598 * @param string $label 599 * @param array $values 600 * @param array $attributes 601 * @param array $options 602 */ 603 public function __construct(backup_setting $setting, $label = null, $values = null, array $attributes = array(), array $options = array()) { 604 parent::__construct($setting, $label, $attributes, $options); 605 $this->values = $values; 606 } 607 608 /** 609 * Returns an array of properties suitable for generating a quickforms element 610 * @param base_task $task 611 * @param renderer_base $output 612 * @return array (element, name, label, options, attributes) 613 */ 614 public function get_element_properties(base_task $task = null, renderer_base $output = null) { 615 $icon = $this->get_icon(); 616 $context = context_course::instance($task->get_courseid()); 617 $label = format_string($this->get_label($task), true, array('context' => $context)); 618 if (!empty($icon)) { 619 $label .= $output->render($icon); 620 } 621 // Name, label, options, attributes. 622 return $this->apply_options(array( 623 'element' => 'select', 624 'name' => self::NAME_PREFIX.$this->name, 625 'label' => $label, 626 'options' => $this->values, 627 'attributes' => $this->attributes 628 )); 629 } 630 631 /** 632 * Sets the options for the select box 633 * @param array $values Associative array of value => text options 634 */ 635 public function set_values(array $values) { 636 $this->values = $values; 637 } 638 639 /** 640 * Gets the static value for this select element 641 * @return string 642 */ 643 public function get_static_value() { 644 return $this->values[$this->get_value()]; 645 } 646 647 /** 648 * Returns true if the setting is changeable, false otherwise 649 * 650 * @param int $level Optional, if provided only depedency_settings below or equal to this level are considered, 651 * when checking if the ui_setting is changeable. Although dependencies might cause a lock on this setting, 652 * they could be changeable in the same view. 653 * @return bool 654 */ 655 public function is_changeable($level = null) { 656 if (count($this->values) == 1) { 657 return false; 658 } else { 659 return parent::is_changeable($level); 660 } 661 } 662 663 /** 664 * Returns the list of available values 665 * @return array 666 */ 667 public function get_values() { 668 return $this->values; 669 } 670 } 671 672 /** 673 * A date selector user interface widget for backup settings. 674 * 675 * @package core_backup 676 * @copyright 2010 Sam Hemelryk 677 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 678 */ 679 class backup_setting_ui_dateselector extends backup_setting_ui_text { 680 681 /** 682 * Returns an array of properties suitable for generating a quickforms element 683 * @param base_task $task 684 * @param renderer_base $output 685 * @return array (element, name, label, options, attributes) 686 */ 687 public function get_element_properties(base_task $task = null, renderer_base $output = null) { 688 if (!array_key_exists('optional', $this->attributes)) { 689 $this->attributes['optional'] = false; 690 } 691 $properties = parent::get_element_properties($task, $output); 692 $properties['element'] = 'date_selector'; 693 return $properties; 694 } 695 696 /** 697 * Gets the static value for this select element 698 * @return string 699 */ 700 public function get_static_value() { 701 $value = $this->get_value(); 702 if (!empty($value)) { 703 return userdate($value); 704 } 705 return parent::get_static_value(); 706 } 707 } 708 709 /** 710 * A wrapper for defaultcustom form element - can have either text or date_selector type 711 * 712 * @package core_backup 713 * @copyright 2017 Marina Glancy 714 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 715 */ 716 class backup_setting_ui_defaultcustom extends backup_setting_ui_text { 717 718 /** 719 * Constructor 720 * 721 * @param backup_setting $setting 722 * @param string $label The label to display with the setting ui 723 * @param array $attributes Array of HTML attributes to apply to the element 724 * @param array $options Array of options to apply to the setting ui object 725 */ 726 public function __construct(backup_setting $setting, $label = null, array $attributes = null, array $options = null) { 727 if (!is_array($attributes)) { 728 $attributes = []; 729 } 730 $attributes += ['customlabel' => get_string('overwrite', 'backup'), 731 'type' => 'text']; 732 parent::__construct($setting, $label, $attributes, $options); 733 } 734 735 /** 736 * Returns an array of properties suitable for generating a quickforms element 737 * @param base_task $task 738 * @param renderer_base $output 739 * @return array (element, name, label, options, attributes) 740 */ 741 public function get_element_properties(base_task $task = null, renderer_base $output = null) { 742 return ['element' => 'defaultcustom'] + parent::get_element_properties($task, $output); 743 } 744 745 /** 746 * Gets the static value for this select element 747 * @return string 748 */ 749 public function get_static_value() { 750 $value = $this->get_value(); 751 if ($value === false) { 752 $value = $this->attributes['defaultvalue']; 753 } 754 if (!empty($value)) { 755 if ($this->attributes['type'] === 'date_selector' || 756 $this->attributes['type'] === 'date_time_selector') { 757 return userdate($value); 758 } 759 } 760 return $value; 761 } 762 } 763 764 /** 765 * Base setting UI exception class. 766 * 767 * @package core_backup 768 * @copyright 2010 Sam Hemelryk 769 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 770 */ 771 class base_setting_ui_exception extends base_setting_exception {} 772 773 /** 774 * Backup setting UI exception class. 775 * 776 * @package core_backup 777 * @copyright 2010 Sam Hemelryk 778 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 779 */ 780 class backup_setting_ui_exception extends base_setting_ui_exception {};
title
Description
Body
title
Description
Body
title
Description
Body
title
Body