[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * Joomla! Content Management System
   5   *
   6   * @copyright  (C) 2006 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\Toolbar;
  11  
  12  use Joomla\CMS\Factory;
  13  use Joomla\CMS\Language\Text;
  14  use Joomla\CMS\Layout\FileLayout;
  15  use Joomla\CMS\Log\Log;
  16  use Joomla\CMS\Toolbar\Button\BasicButton;
  17  use Joomla\CMS\Toolbar\Button\ConfirmButton;
  18  use Joomla\CMS\Toolbar\Button\CustomButton;
  19  use Joomla\CMS\Toolbar\Button\DropdownButton;
  20  use Joomla\CMS\Toolbar\Button\HelpButton;
  21  use Joomla\CMS\Toolbar\Button\InlinehelpButton;
  22  use Joomla\CMS\Toolbar\Button\LinkButton;
  23  use Joomla\CMS\Toolbar\Button\PopupButton;
  24  use Joomla\CMS\Toolbar\Button\SeparatorButton;
  25  use Joomla\CMS\Toolbar\Button\StandardButton;
  26  
  27  // phpcs:disable PSR1.Files.SideEffects
  28  \defined('JPATH_PLATFORM') or die;
  29  // phpcs:enable PSR1.Files.SideEffects
  30  
  31  /**
  32   * ToolBar handler
  33   *
  34   * @method  StandardButton  standardButton(string $name = '', string $text = '', string $task = '')
  35   * @method  SeparatorButton  separatorButton(string $name = '', string $text = '', string $task = '')
  36   * @method  PopupButton  popupButton(string $name = '', string $text = '', string $task = '')
  37   * @method  LinkButton  linkButton(string $name = '', string $text = '', string $task = '')
  38   * @method  HelpButton  helpButton(string $name = '', string $text = '', string $task = '')
  39   * @method  InlinehelpButton  inlinehelpButton(string $name = '', string $text = '', string $task = '')
  40   * @method  CustomButton  customButton(string $name = '', string $text = '', string $task = '')
  41   * @method  ConfirmButton  confirmButton(string $name = '', string $text = '', string $task = '')
  42   * @method  BasicButton  basicButton(string $name = '', string $text = '', string $task = '')
  43   * @method  DropdownButton  dropdownButton(string $name = '', string $text = '', string $task = '')
  44   *
  45   * @since  1.5
  46   */
  47  class Toolbar
  48  {
  49      use CoreButtonsTrait;
  50  
  51      /**
  52       * Toolbar name
  53       *
  54       * @var    string
  55       * @since  1.5
  56       */
  57      protected $_name = '';
  58  
  59      /**
  60       * Toolbar array
  61       *
  62       * @var    array
  63       * @since  1.5
  64       */
  65      protected $_bar = [];
  66  
  67      /**
  68       * Directories, where button types can be stored.
  69       *
  70       * @var    array
  71       * @since  1.5
  72       */
  73      protected $_buttonPath = [];
  74  
  75      /**
  76       * Stores the singleton instances of various toolbar.
  77       *
  78       * @var    Toolbar[]
  79       * @since  2.5
  80       */
  81      protected static $instances = array();
  82  
  83      /**
  84       * Factory for creating Toolbar API objects
  85       *
  86       * @var    ToolbarFactoryInterface
  87       * @since  4.0.0
  88       */
  89      protected $factory;
  90  
  91      /**
  92       * Constructor
  93       *
  94       * @param   string                   $name     The toolbar name.
  95       * @param   ToolbarFactoryInterface  $factory  The toolbar factory.
  96       *
  97       * @since   1.5
  98       */
  99      public function __construct($name = 'toolbar', ToolbarFactoryInterface $factory = null)
 100      {
 101          $this->_name = $name;
 102  
 103          // At 5.0, require the factory to be injected
 104          if (!$factory) {
 105              @trigger_error(
 106                  sprintf(
 107                      'As of Joomla! 5.0, a %1$s must be provided to a %2$s object when creating it.',
 108                      ToolbarFactoryInterface::class,
 109                      \get_class($this)
 110                  ),
 111                  E_USER_DEPRECATED
 112              );
 113  
 114              $factory = new ContainerAwareToolbarFactory();
 115              $factory->setContainer(Factory::getContainer());
 116          }
 117  
 118          $this->setFactory($factory);
 119  
 120          // Set base path to find buttons.
 121          $this->_buttonPath[] = __DIR__ . '/Button';
 122      }
 123  
 124      /**
 125       * Returns the global Toolbar object, only creating it if it doesn't already exist.
 126       *
 127       * @param   string  $name  The name of the toolbar.
 128       *
 129       * @return  Toolbar  The Toolbar object.
 130       *
 131       * @since       1.5
 132       * @deprecated  5.0 Use the ToolbarFactoryInterface instead
 133       *
 134       * @throws \Joomla\DI\Exception\KeyNotFoundException
 135       */
 136      public static function getInstance($name = 'toolbar')
 137      {
 138          if (empty(self::$instances[$name])) {
 139              self::$instances[$name] = Factory::getContainer()->get(ToolbarFactoryInterface::class)->createToolbar($name);
 140          }
 141  
 142          return self::$instances[$name];
 143      }
 144  
 145      /**
 146       * Set the factory instance
 147       *
 148       * @param   ToolbarFactoryInterface  $factory  The factory instance
 149       *
 150       * @return  $this
 151       *
 152       * @since   4.0.0
 153       */
 154      public function setFactory(ToolbarFactoryInterface $factory): self
 155      {
 156          $this->factory = $factory;
 157  
 158          return $this;
 159      }
 160  
 161      /**
 162       * Append a button to toolbar.
 163       *
 164       * @param   ToolbarButton  $button  The button instance.
 165       * @param   array          $args    The more arguments.
 166       *
 167       * @return  ToolbarButton|boolean  Return button instance to help chaining configure. If using legacy arguments
 168       *                                 returns true
 169       *
 170       * @since   1.5
 171       */
 172      public function appendButton($button, ...$args)
 173      {
 174          if ($button instanceof ToolbarButton) {
 175              $button->setParent($this);
 176  
 177              $this->_bar[] = $button;
 178  
 179              return $button;
 180          }
 181  
 182          // B/C
 183          array_unshift($args, $button);
 184          $this->_bar[] = $args;
 185  
 186          @trigger_error(
 187              sprintf(
 188                  '%s::appendButton() should only accept %s instance in Joomla 5.0.',
 189                  static::class,
 190                  ToolbarButton::class
 191              ),
 192              E_USER_DEPRECATED
 193          );
 194  
 195          return true;
 196      }
 197  
 198      /**
 199       * Get the list of toolbar links.
 200       *
 201       * @return  array
 202       *
 203       * @since   1.6
 204       */
 205      public function getItems()
 206      {
 207          return $this->_bar;
 208      }
 209  
 210      /**
 211       * Set the button list.
 212       *
 213       * @param   ToolbarButton[]  $items  The button list array.
 214       *
 215       * @return  static
 216       *
 217       * @since   4.0.0
 218       */
 219      public function setItems(array $items): self
 220      {
 221          $this->_bar = $items;
 222  
 223          return $this;
 224      }
 225  
 226      /**
 227       * Get the name of the toolbar.
 228       *
 229       * @return  string
 230       *
 231       * @since   1.6
 232       */
 233      public function getName()
 234      {
 235          return $this->_name;
 236      }
 237  
 238      /**
 239       * Prepend a button to toolbar.
 240       *
 241       * @param   ToolbarButton  $button  The button instance.
 242       * @param   array          $args    The more arguments.
 243       *
 244       * @return  ToolbarButton|boolean  Return button instance to help chaining configure. If using legacy arguments
 245       *                                 returns true
 246       *
 247       * @since   1.5
 248       */
 249      public function prependButton($button, ...$args)
 250      {
 251          if ($button instanceof ToolbarButton) {
 252              $button->setParent($this);
 253  
 254              array_unshift($this->_bar, $button);
 255  
 256              return $button;
 257          }
 258  
 259          // B/C
 260          array_unshift($args, $button);
 261          array_unshift($this->_bar, $args);
 262  
 263          @trigger_error(
 264              sprintf(
 265                  '%s::prependButton() should only accept %s instance in Joomla 5.0.',
 266                  static::class,
 267                  ToolbarButton::class
 268              ),
 269              E_USER_DEPRECATED
 270          );
 271  
 272          return true;
 273      }
 274  
 275      /**
 276       * Render a toolbar.
 277       *
 278       * @param   array  $options  The options of toolbar.
 279       *
 280       * @return  string  HTML for the toolbar.
 281       *
 282       * @throws \Exception
 283       * @since   1.5
 284       */
 285      public function render(array $options = [])
 286      {
 287          $html = [];
 288  
 289          $isChild = !empty($options['is_child']);
 290  
 291          // Start toolbar div.
 292          if (!$isChild) {
 293              $layout = new FileLayout('joomla.toolbar.containeropen');
 294  
 295              $html[] = $layout->render(['id' => $this->_name]);
 296          }
 297  
 298          $len = count($this->_bar);
 299  
 300          // Render each button in the toolbar.
 301          foreach ($this->_bar as $i => $button) {
 302              if ($button instanceof ToolbarButton) {
 303                  // Child dropdown only support new syntax
 304                  $button->setOption('is_child', $isChild);
 305                  $button->setOption('is_first_child', $i === 0);
 306                  $button->setOption('is_last_child', $i === $len - 1);
 307                  $html[] = $button->render();
 308              } else {
 309                  // B/C
 310                  $html[] = $this->renderButton($button);
 311              }
 312          }
 313  
 314          // End toolbar div.
 315          if (!$isChild) {
 316              $layout = new FileLayout('joomla.toolbar.containerclose');
 317  
 318              $html[] = $layout->render([]);
 319          }
 320  
 321          return implode('', $html);
 322      }
 323  
 324      /**
 325       * Render a button.
 326       *
 327       * @param   array  &$node  A toolbar node.
 328       *
 329       * @return  string
 330       *
 331       * @since   1.5
 332       * @throws  \Exception
 333       */
 334      public function renderButton(&$node)
 335      {
 336          // Get the button type.
 337          $type = $node[0];
 338  
 339          $button = $this->loadButtonType($type);
 340  
 341          // Check for error.
 342          if ($button === false) {
 343              throw new \UnexpectedValueException(Text::sprintf('JLIB_HTML_BUTTON_NOT_DEFINED', $type));
 344          }
 345  
 346          $button->setParent($this);
 347  
 348          return $button->render($node);
 349      }
 350  
 351      /**
 352       * Loads a button type.
 353       *
 354       * @param   string   $type  Button Type
 355       * @param   boolean  $new   False by default
 356       *
 357       * @return  false|ToolbarButton
 358       *
 359       * @since   1.5
 360       */
 361      public function loadButtonType($type, $new = false)
 362      {
 363          // For B/C, catch the exceptions thrown by the factory
 364          try {
 365              return $this->factory->createButton($this, $type);
 366          } catch (\InvalidArgumentException $e) {
 367              Log::add($e->getMessage(), Log::WARNING, 'jerror');
 368  
 369              return false;
 370          }
 371      }
 372  
 373      /**
 374       * Add a directory where Toolbar should search for button types in LIFO order.
 375       *
 376       * You may either pass a string or an array of directories.
 377       *
 378       * Toolbar will be searching for an element type in the same order you
 379       * added them. If the parameter type cannot be found in the custom folders,
 380       * it will look in libraries/joomla/html/toolbar/button.
 381       *
 382       * @param   mixed  $path  Directory or directories to search.
 383       *
 384       * @return  void
 385       *
 386       * @since       1.5
 387       * @deprecated  5.0  ToolbarButton classes should be autoloaded
 388       */
 389      public function addButtonPath($path)
 390      {
 391          @trigger_error(
 392              sprintf(
 393                  'Registering lookup paths for toolbar buttons is deprecated and will be removed in Joomla 5.0.'
 394                  . ' %1$s objects should be autoloaded or a custom %2$s implementation supporting path lookups provided.',
 395                  ToolbarButton::class,
 396                  ToolbarFactoryInterface::class
 397              ),
 398              E_USER_DEPRECATED
 399          );
 400  
 401          // Loop through the path directories.
 402          foreach ((array) $path as $dir) {
 403              // No surrounding spaces allowed!
 404              $dir = trim($dir);
 405  
 406              // Add trailing separators as needed.
 407              if (substr($dir, -1) !== DIRECTORY_SEPARATOR) {
 408                  // Directory
 409                  $dir .= DIRECTORY_SEPARATOR;
 410              }
 411  
 412              // Add to the top of the search dirs.
 413              array_unshift($this->_buttonPath, $dir);
 414          }
 415      }
 416  
 417      /**
 418       * Get the lookup paths for button objects
 419       *
 420       * @return  array
 421       *
 422       * @since   4.0.0
 423       * @deprecated  5.0  ToolbarButton classes should be autoloaded
 424       */
 425      public function getButtonPath(): array
 426      {
 427          @trigger_error(
 428              sprintf(
 429                  'Lookup paths for %s objects is deprecated and will be removed in Joomla 5.0.',
 430                  ToolbarButton::class
 431              ),
 432              E_USER_DEPRECATED
 433          );
 434  
 435          return $this->_buttonPath;
 436      }
 437  
 438      /**
 439       * Create child toolbar.
 440       *
 441       * @param   string  $name  The toolbar name.
 442       *
 443       * @return  static
 444       *
 445       * @since   4.0.0
 446       */
 447      public function createChild($name): self
 448      {
 449          return new static($name, $this->factory);
 450      }
 451  
 452      /**
 453       * Magic method proxy.
 454       *
 455       * @param   string  $name  The method name.
 456       * @param   array   $args  The method arguments.
 457       *
 458       * @return  ToolbarButton
 459       *
 460       * @throws  \Exception
 461       *
 462       * @since   4.0.0
 463       */
 464      public function __call($name, $args)
 465      {
 466          if (strtolower(substr($name, -6)) === 'button') {
 467              $type = substr($name, 0, -6);
 468  
 469              $button = $this->factory->createButton($this, $type);
 470  
 471              $button->name($args[0] ?? '')
 472                  ->text($args[1] ?? '')
 473                  ->task($args[2] ?? '');
 474  
 475              return $this->appendButton($button);
 476          }
 477  
 478          throw new \BadMethodCallException(
 479              sprintf(
 480                  'Method %s() not found in class: %s',
 481                  $name,
 482                  static::class
 483              )
 484          );
 485      }
 486  }