[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * Joomla! Content Management System
   5   *
   6   * @copyright  (C) 2017 Open Source Matters, Inc. <https://www.joomla.org>
   7   * @license    GNU General Public License version 2 or later; see LICENSE.txt
   8   */
   9  
  10  namespace Joomla\CMS\Button;
  11  
  12  use Joomla\CMS\Language\Text;
  13  use Joomla\CMS\Layout\FileLayout;
  14  use Joomla\CMS\Layout\LayoutHelper;
  15  use Joomla\Registry\Registry;
  16  use Joomla\Utilities\ArrayHelper;
  17  
  18  // phpcs:disable PSR1.Files.SideEffects
  19  \defined('_JEXEC') or die;
  20  // phpcs:enable PSR1.Files.SideEffects
  21  
  22  /**
  23   * The TaskButton class.
  24   *
  25   * @since  4.0.0
  26   */
  27  class ActionButton
  28  {
  29      /**
  30       * The button states profiles.
  31       *
  32       * @var  array
  33       *
  34       * @since  4.0.0
  35       */
  36      protected $states = [];
  37  
  38      /**
  39       * Default options for unknown state.
  40       *
  41       * @var  array
  42       *
  43       * @since  4.0.0
  44       */
  45      protected $unknownState = [
  46          'value'   => null,
  47          'task'    => '',
  48          'icon'    => 'question',
  49          'title'   => 'Unknown state',
  50          'options' => [
  51              'disabled'  => false,
  52              'only_icon' => false,
  53              'tip' => true,
  54              'tip_title' => '',
  55              'task_prefix' => '',
  56              'checkbox_name' => 'cb',
  57          ],
  58      ];
  59  
  60      /**
  61       * Options of this button set.
  62       *
  63       * @var  Registry
  64       *
  65       * @since  4.0.0
  66       */
  67      protected $options;
  68  
  69      /**
  70       * The layout path to render.
  71       *
  72       * @var  string
  73       *
  74       * @since  4.0.0
  75       */
  76      protected $layout = 'joomla.button.action-button';
  77  
  78      /**
  79       * ActionButton constructor.
  80       *
  81       * @param   array  $options  The options for all buttons in this group.
  82       *
  83       * @since   4.0.0
  84       */
  85      public function __construct(array $options = [])
  86      {
  87          $this->options = new Registry($options);
  88  
  89          // Replace some dynamic values
  90          $this->unknownState['title'] = Text::_('JLIB_HTML_UNKNOWN_STATE');
  91  
  92          $this->preprocess();
  93      }
  94  
  95      /**
  96       * Configure this object.
  97       *
  98       * @return  void
  99       *
 100       * @since   4.0.0
 101       */
 102      protected function preprocess()
 103      {
 104          // Implement this method.
 105      }
 106  
 107      /**
 108       * Add a state profile.
 109       *
 110       * @param   integer  $value    The value of this state.
 111       * @param   string   $task     The task you want to execute after click this button.
 112       * @param   string   $icon     The icon to display for user.
 113       * @param   string   $title    Title text will show if we enable tooltips.
 114       * @param   array    $options  The button options, will override group options.
 115       *
 116       * @return  static  Return self to support chaining.
 117       *
 118       * @since   4.0.0
 119       */
 120      public function addState(int $value, string $task, string $icon = 'ok', string $title = '', array $options = []): self
 121      {
 122          // Force type to prevent null data
 123          $this->states[$value] = [
 124              'value'   => $value,
 125              'task'    => $task,
 126              'icon'    => $icon,
 127              'title'   => $title,
 128              'options' => $options
 129          ];
 130  
 131          return $this;
 132      }
 133  
 134      /**
 135       * Get state profile by value name.
 136       *
 137       * @param   integer  $value  The value name we want to get.
 138       *
 139       * @return  array|null  Return state profile or NULL.
 140       *
 141       * @since   4.0.0
 142       */
 143      public function getState(int $value): ?array
 144      {
 145          return $this->states[$value] ?? null;
 146      }
 147  
 148      /**
 149       * Remove a state by value name.
 150       *
 151       * @param   integer  $value  Remove state by this value.
 152       *
 153       * @return  static  Return to support chaining.
 154       *
 155       * @since   4.0.0
 156       */
 157      public function removeState(int $value): self
 158      {
 159          if (isset($this->states[$value])) {
 160              unset($this->states[$value]);
 161          }
 162  
 163          return $this;
 164      }
 165  
 166      /**
 167       * Render action button by item value.
 168       *
 169       * @param   integer|null  $value    Current value of this item.
 170       * @param   integer|null  $row      The row number of this item.
 171       * @param   array         $options  The options to override group options.
 172       *
 173       * @return  string  Rendered HTML.
 174       *
 175       * @since   4.0.0
 176       *
 177       * @throws  \InvalidArgumentException
 178       */
 179      public function render(?int $value = null, ?int $row = null, array $options = []): string
 180      {
 181          $data = $this->getState($value) ?? $this->unknownState;
 182  
 183          $data = ArrayHelper::mergeRecursive(
 184              $this->unknownState,
 185              $data,
 186              [
 187                  'options' => $this->options->toArray()
 188              ],
 189              [
 190                  'options' => $options
 191              ]
 192          );
 193  
 194          $data['row'] = $row;
 195          $data['icon'] = $this->fetchIconClass($data['icon']);
 196  
 197          return LayoutHelper::render($this->layout, $data);
 198      }
 199  
 200      /**
 201       * Render to string.
 202       *
 203       * @return  string
 204       *
 205       * @since  4.0.0
 206       */
 207      public function __toString(): string
 208      {
 209          try {
 210              return $this->render();
 211          } catch (\Throwable $e) {
 212              return (string) $e;
 213          }
 214      }
 215  
 216      /**
 217       * Method to get property layout.
 218       *
 219       * @return  string
 220       *
 221       * @since  4.0.0
 222       */
 223      public function getLayout(): string
 224      {
 225          return $this->layout;
 226      }
 227  
 228      /**
 229       * Method to set property template.
 230       *
 231       * @param   string  $layout  The layout path.
 232       *
 233       * @return  static  Return self to support chaining.
 234       *
 235       * @since   4.0.0
 236       */
 237      public function setLayout(string $layout): self
 238      {
 239          $this->layout = $layout;
 240  
 241          return $this;
 242      }
 243  
 244      /**
 245       * Method to get property options.
 246       *
 247       * @return  array
 248       *
 249       * @since  4.0.0
 250       */
 251      public function getOptions(): array
 252      {
 253          return (array) $this->options->toArray();
 254      }
 255  
 256      /**
 257       * Method to set property options.
 258       *
 259       * @param   array  $options  The options of this button group.
 260       *
 261       * @return  static  Return self to support chaining.
 262       *
 263       * @since   4.0.0
 264       */
 265      public function setOptions(array $options): self
 266      {
 267          $this->options = new Registry($options);
 268  
 269          return $this;
 270      }
 271  
 272      /**
 273       * Get an option value.
 274       *
 275       * @param   string  $name     The option name.
 276       * @param   mixed   $default  Default value if not exists.
 277       *
 278       * @return  mixed  Return option value or default value.
 279       *
 280       * @since   4.0.0
 281       */
 282      public function getOption(string $name, $default = null)
 283      {
 284          return $this->options->get($name, $default);
 285      }
 286  
 287      /**
 288       * Set option value.
 289       *
 290       * @param   string  $name   The option name.
 291       * @param   mixed   $value  The option value.
 292       *
 293       * @return  static  Return self to support chaining.
 294       *
 295       * @since   4.0.0
 296       */
 297      public function setOption(string $name, $value): self
 298      {
 299          $this->options->set($name, $value);
 300  
 301          return $this;
 302      }
 303  
 304      /**
 305       * Method to get the CSS class name for an icon identifier.
 306       *
 307       * Can be redefined in the final class.
 308       *
 309       * @param   string  $identifier  Icon identification string.
 310       *
 311       * @return  string  CSS class name.
 312       *
 313       * @since   4.0.0
 314       */
 315      public function fetchIconClass(string $identifier): string
 316      {
 317          // It's an ugly hack, but this allows templates to define the icon classes for the toolbar
 318          $layout = new FileLayout('joomla.button.iconclass');
 319  
 320          return $layout->render(array('icon' => $identifier));
 321      }
 322  }