[Summary view] [Print] [Text view]

   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       *
 311       * @return bool
 312       */
 313      public function is_changeable() {
 314          if ($this->setting->get_status() === backup_setting::NOT_LOCKED) {
 315              // Its not locked so its chanegable.
 316              return true;
 317          } else if ($this->setting->get_status() !== backup_setting::LOCKED_BY_HIERARCHY) {
 318              // Its not changeable because its locked by permission or config.
 319              return false;
 320          } else if ($this->setting->has_dependencies_on_settings()) {
 321              foreach ($this->setting->get_settings_depended_on() as $dependency) {
 322                  if ($dependency->is_locked() && $dependency->get_setting()->get_level() !== $this->setting->get_level()) {
 323                      // Its not changeable because one or more dependancies arn't changeable.
 324                      return false;
 325                  }
 326              }
 327              // Its changeable because all dependencies are changeable.
 328              return true;
 329          }
 330          // We should never get here but if we do return false to be safe.
 331          // The setting would need to be locked by hierarchy and not have any deps.
 332          return false;
 333      }
 334  
 335  }
 336  
 337  /**
 338   * A text input user interface element for backup settings
 339   *
 340   * @package core_backup
 341   * @copyright 2010 Sam Hemelryk
 342   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 343   */
 344  class backup_setting_ui_text extends backup_setting_ui {
 345      /**
 346       * @var int
 347       */
 348      protected $type = backup_setting::UI_HTML_TEXTFIELD;
 349  
 350      /**
 351       * Returns an array of properties suitable for generating a quickforms element
 352       * @param base_task $task
 353       * @param renderer_base $output
 354       * @return array (element, name, label, attributes)
 355       */
 356      public function get_element_properties(base_task $task = null, renderer_base $output = null) {
 357          $icon = $this->get_icon();
 358          $label = $this->get_label($task);
 359          if (!empty($icon)) {
 360              $label .= $output->render($icon);
 361          }
 362          // Name, label, attributes.
 363          return $this->apply_options(array(
 364              'element' => 'text',
 365              'name' => self::NAME_PREFIX.$this->name,
 366              'label' => $label,
 367              'attributes' => $this->attributes)
 368          );
 369      }
 370  
 371  }
 372  
 373  /**
 374   * A checkbox user interface element for backup settings (default)
 375   *
 376   * @package core_backup
 377   * @copyright 2010 Sam Hemelryk
 378   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 379   */
 380  class backup_setting_ui_checkbox extends backup_setting_ui {
 381  
 382      /**
 383       * @var int
 384       */
 385      protected $type = backup_setting::UI_HTML_CHECKBOX;
 386  
 387      /**
 388       * @var bool
 389       */
 390      protected $changeable = true;
 391  
 392      /**
 393       * The text to show next to the checkbox
 394       * @var string
 395       */
 396      protected $text;
 397  
 398      /**
 399       * Overridden constructor so we can take text argument
 400       *
 401       * @param backup_setting $setting
 402       * @param string $label
 403       * @param string $text
 404       * @param array $attributes
 405       * @param array $options
 406       */
 407      public function __construct(backup_setting $setting, $label = null, $text = null, array $attributes = array(), array $options = array()) {
 408          parent::__construct($setting, $label, $attributes, $options);
 409          $this->text = $text;
 410      }
 411  
 412      /**
 413       * Returns an array of properties suitable for generating a quickforms element
 414       * @param base_task $task
 415       * @param renderer_base $output
 416       * @return array (element, name, label, text, attributes);
 417       */
 418      public function get_element_properties(base_task $task = null, renderer_base $output = null) {
 419          // Name, label, text, attributes.
 420          $icon = $this->get_icon();
 421          $label = $this->get_label($task);
 422          if (!empty($icon)) {
 423              $label .= $output->render($icon);
 424          }
 425          return $this->apply_options(array(
 426              'element' => 'checkbox',
 427              'name' => self::NAME_PREFIX.$this->name,
 428              'label' => $label,
 429              'text' => $this->text,
 430              'attributes' => $this->attributes
 431          ));
 432      }
 433  
 434      /**
 435       * Sets the text for the element
 436       * @param string $text
 437       */
 438      public function set_text($text) {
 439          $this->text = $text;
 440      }
 441  
 442      /**
 443       * Gets the static value for the element
 444       * @global core_renderer $OUTPUT
 445       * @return string
 446       */
 447      public function get_static_value() {
 448          global $OUTPUT;
 449          // Checkboxes are always yes or no.
 450          if ($this->get_value()) {
 451              return $OUTPUT->pix_icon('i/valid', get_string('yes'));
 452          } else {
 453              return $OUTPUT->pix_icon('i/invalid', get_string('no'));
 454          }
 455      }
 456  
 457      /**
 458       * Returns true if the setting is changeable
 459       * @return bool
 460       */
 461      public function is_changeable() {
 462          if ($this->changeable === false) {
 463              return false;
 464          } else {
 465              return parent::is_changeable();
 466          }
 467      }
 468  
 469      /**
 470       * Sets whether the setting is changeable,
 471       * Note dependencies can still mark this setting changeable or not
 472       * @param bool $newvalue
 473       */
 474      public function set_changeable($newvalue) {
 475          $this->changeable = ($newvalue);
 476      }
 477  }
 478  
 479  /**
 480   * Radio button user interface element for backup settings
 481   *
 482   * @package core_backup
 483   * @copyright 2010 Sam Hemelryk
 484   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 485   */
 486  class backup_setting_ui_radio extends backup_setting_ui {
 487      /**
 488       * @var int
 489       */
 490      protected $type = backup_setting::UI_HTML_RADIOBUTTON;
 491  
 492      /**
 493       * The string shown next to the input
 494       * @var string
 495       */
 496      protected $text;
 497  
 498      /**
 499       * The value for the radio input
 500       * @var string
 501       */
 502      protected $value;
 503  
 504      /**
 505       * Constructor
 506       *
 507       * @param backup_setting $setting
 508       * @param string $label
 509       * @param string $text
 510       * @param string $value
 511       * @param array $attributes
 512       * @param array $options
 513       */
 514      public function __construct(backup_setting $setting, $label = null, $text = null, $value = null, array $attributes = array(), array $options = array()) {
 515          parent::__construct($setting, $label, $attributes, $options);
 516          $this->text = $text;
 517          $this->value = (string)$value;
 518      }
 519  
 520      /**
 521       * Returns an array of properties suitable for generating a quickforms element
 522       * @param base_task $task
 523       * @param renderer_base $output
 524       * @return array (element, name, label, text, value, attributes)
 525       */
 526      public function get_element_properties(base_task $task = null, renderer_base $output = null) {
 527          $icon = $this->get_icon();
 528          $label = $this->get_label($task);
 529          if (!empty($icon)) {
 530              $label .= $output->render($icon);
 531          }
 532          // Name, label, text, value, attributes.
 533          return $this->apply_options(array(
 534              'element' => 'radio',
 535              'name' => self::NAME_PREFIX.$this->name,
 536              'label' => $label,
 537              'text' => $this->text,
 538              'value' => $this->value,
 539              'attributes' => $this->attributes
 540          ));
 541      }
 542      /**
 543       * Sets the text next to this input
 544       * @param text $text
 545       */
 546      public function set_text($text) {
 547          $this->text = $text;
 548      }
 549      /**
 550       * Sets the value for the input
 551       * @param string $value
 552       */
 553      public function set_value($value) {
 554          $this->value = (string)$value;
 555      }
 556      /**
 557       * Gets the static value to show for the element
 558       */
 559      public function get_static_value() {
 560          return $this->value;
 561      }
 562  }
 563  
 564  /**
 565   * A select box, drop down user interface for backup settings
 566   *
 567   * @package core_backup
 568   * @copyright 2010 Sam Hemelryk
 569   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 570   */
 571  class backup_setting_ui_select extends backup_setting_ui {
 572      /**
 573       * @var int
 574       */
 575      protected $type = backup_setting::UI_HTML_DROPDOWN;
 576  
 577      /**
 578       * An array of options to display in the select
 579       * @var array
 580       */
 581      protected $values;
 582  
 583      /**
 584       * Constructor
 585       *
 586       * @param backup_setting $setting
 587       * @param string $label
 588       * @param array $values
 589       * @param array $attributes
 590       * @param array $options
 591       */
 592      public function __construct(backup_setting $setting, $label = null, $values = null, array $attributes = array(), array $options = array()) {
 593          parent::__construct($setting, $label, $attributes, $options);
 594          $this->values = $values;
 595      }
 596  
 597      /**
 598       * Returns an array of properties suitable for generating a quickforms element
 599       * @param base_task $task
 600       * @param renderer_base $output
 601       * @return array (element, name, label, options, attributes)
 602       */
 603      public function get_element_properties(base_task $task = null, renderer_base $output = null) {
 604          $icon = $this->get_icon();
 605          $label = $this->get_label($task);
 606          if (!empty($icon)) {
 607              $label .= $output->render($icon);
 608          }
 609          // Name, label, options, attributes.
 610          return $this->apply_options(array(
 611              'element' => 'select',
 612              'name' => self::NAME_PREFIX.$this->name,
 613              'label' => $label,
 614              'options' => $this->values,
 615              'attributes' => $this->attributes
 616          ));
 617      }
 618  
 619      /**
 620       * Sets the options for the select box
 621       * @param array $values Associative array of value => text options
 622       */
 623      public function set_values(array $values) {
 624          $this->values = $values;
 625      }
 626  
 627      /**
 628       * Gets the static value for this select element
 629       * @return string
 630       */
 631      public function get_static_value() {
 632          return $this->values[$this->get_value()];
 633      }
 634  
 635      /**
 636       * Returns true if the setting is changeable, false otherwise
 637       *
 638       * @return bool
 639       */
 640      public function is_changeable() {
 641          if (count($this->values) == 1) {
 642              return false;
 643          } else {
 644              return parent::is_changeable();
 645          }
 646      }
 647  }
 648  
 649  /**
 650   * A date selector user interface widget for backup settings.
 651   *
 652   * @package core_backup
 653   * @copyright 2010 Sam Hemelryk
 654   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 655   */
 656  class backup_setting_ui_dateselector extends backup_setting_ui_text {
 657  
 658      /**
 659       * Returns an array of properties suitable for generating a quickforms element
 660       * @param base_task $task
 661       * @param renderer_base $output
 662       * @return array (element, name, label, options, attributes)
 663       */
 664      public function get_element_properties(base_task $task = null, renderer_base $output = null) {
 665          if (!array_key_exists('optional', $this->attributes)) {
 666              $this->attributes['optional'] = false;
 667          }
 668          $properties = parent::get_element_properties($task, $output);
 669          $properties['element'] = 'date_selector';
 670          return $properties;
 671      }
 672  
 673      /**
 674       * Gets the static value for this select element
 675       * @return string
 676       */
 677      public function get_static_value() {
 678          $value = $this->get_value();
 679          if (!empty($value)) {
 680              return userdate($value);
 681          }
 682          return parent::get_static_value();
 683      }
 684  }
 685  
 686  /**
 687   * Base setting UI exception class.
 688   *
 689   * @package core_backup
 690   * @copyright 2010 Sam Hemelryk
 691   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 692   */
 693  class base_setting_ui_exception extends base_setting_exception {}
 694  
 695  /**
 696   * Backup setting UI exception class.
 697   *
 698   * @package core_backup
 699   * @copyright 2010 Sam Hemelryk
 700   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 701   */
 702  class backup_setting_ui_exception extends base_setting_ui_exception {};