CoreFiles by mySites.guru
ToolbarButton.php537 lines, 10,276 bytes, from Joomla_4.0.0-beta5-Beta-Full_Package.zip
Raw History Compare with 4.0.0-beta4
md5
af752a719ee92a72b1cbe9229e272264
sha1
a46816cf4f73263a43b151ad748046502337cebc
sha256
5cb0390703f53c23286451e913063608b66be0bd7673761d27afd9c952103a3b
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537
<?php
/**
 * Joomla! Content Management System
 *
 * @copyright  Copyright (C) 2005 - 2020 Open Source Matters, Inc. All rights reserved.
 * @license    GNU General Public License version 2 or later; see LICENSE.txt
 */

namespace Joomla\CMS\Toolbar;

\defined('JPATH_PLATFORM') or die;

use Joomla\CMS\Language\Text;
use Joomla\CMS\Layout\FileLayout;
use Joomla\Utilities\ArrayHelper;

/**
 * The ToolbarButton class.
 *
 * @method self text(string $value)
 * @method self task(string $value)
 * @method self icon(string $value)
 * @method self buttonClass(string $value)
 * @method self attributes(array $value)
 * @method self onclick(array $value)
 * @method self listCheck(bool $value)
 * @method self listCheckMessage(string $value)
 * @method self form(string $value)
 * @method self formValidation(bool $value)
 * @method string  getText()
 * @method string  getTask()
 * @method string  getIcon()
 * @method string  getButtonClass()
 * @method array   getAttributes()
 * @method string  getOnclick()
 * @method bool    getListCheck()
 * @method string  getListCheckMessage()
 * @method string  getForm()
 * @method bool    getFormValidation()
 *
 * @since  4.0.0
 */
abstract class ToolbarButton
{
	/**
	 * Name of this button.
	 *
	 * @var  string
	 *
	 * @since  4.0.0
	 */
	protected $name;

	/**
	 * Reference to the object that instantiated the element
	 *
	 * @var    Toolbar
	 *
	 * @since  4.0.0
	 */
	protected $parent;

	/**
	 * The layout path to render this button.
	 *
	 * @var  string
	 *
	 * @since  4.0.0
	 */
	protected $layout;

	/**
	 * Button options.
	 *
	 * @var  array
	 *
	 * @since  4.0.0
	 */
	protected $options = [];

	/**
	 * Used to track an ids, to avoid duplication
	 *
	 * @var    array
	 *
	 * @since  4.0.0
	 */
	protected static $idCounter = [];

	/**
	 * Init this class.
	 *
	 * @param   string  $name     Name of this button.
	 * @param   string  $text     The button text, will auto translate.
	 * @param   array   $options  Button options.
	 *
	 * @since  4.0.0
	 *
	 * @throws \InvalidArgumentException
	 */
	public function __construct(string $name = '', string $text = '', array $options = [])
	{
		$this->name($name)
			->text($text);

		$this->options = ArrayHelper::mergeRecursive($this->options, $options);
	}

	/**
	 * Prepare options for this button.
	 *
	 * @param   array  &$options  The options about this button.
	 *
	 * @return  void
	 *
	 * @since  4.0.0
	 */
	protected function prepareOptions(array &$options)
	{
		$options['name']  = $this->getName();
		$options['text']  = Text::_($this->getText());
		$options['class'] = $this->getIcon() ?: $this->fetchIconClass($this->getName());
		$options['id']    = $this->ensureUniqueId($this->fetchId());

		if (!empty($options['is_child']))
		{
			$options['tagName'] = 'button';
			$options['btnClass'] = ($options['button_class'] ?? '') . ' dropdown-item';
			$options['attributes']['type'] = 'button';

			if ($options['is_first_child'])
			{
				$options['btnClass'] .= ' first';
			}

			if ($options['is_last_child'])
			{
				$options['btnClass'] .= ' last';
			}
		}
		else
		{
			$options['tagName'] = 'button';
			$options['btnClass'] = ($options['button_class'] ?? 'btn btn-primary');
			$options['attributes']['type'] = 'button';
		}
	}

	/**
	 * Get the HTML to render the button
	 *
	 * @param   array  &$definition  Parameters to be passed
	 *
	 * @return  string
	 *
	 * @since   3.0
	 *
	 * @throws \Exception
	 */
	public function render(&$definition = null)
	{
		if ($definition === null)
		{
			$action = $this->renderButton($this->options);
		}
		// For B/C
		elseif (\is_array($definition))
		{
			$action = $this->fetchButton(...$definition);
		}
		else
		{
			throw new \InvalidArgumentException('Wrong argument: $definition, should be NULL or array.');
		}

		// Build the HTML Button
		$layout = new FileLayout('joomla.toolbar.base');

		return $layout->render(
			[
				'action' => $action,
				'options' => $this->options
			]
		);
	}

	/**
	 * Render button HTML.
	 *
	 * @param   array  &$options  The button options.
	 *
	 * @return  string  The button HTML.
	 *
	 * @since   4.0.0
	 */
	protected function renderButton(array &$options): string
	{
		$this->prepareOptions($options);

		// Prepare custom attributes.
		unset(
			$options['attributes']['id'],
			$options['attributes']['class']
		);

		$options['htmlAttributes'] = ArrayHelper::toString($options['attributes']);

		// Isolate button class from icon class
		$buttonClass = str_replace('fas fa-', '', $this->getName());
		$buttonClass = str_ireplace('fa-', '', $buttonClass);
		$iconclass = $options['btnClass'] ?? '';
		$options['btnClass'] = 'button-' . $buttonClass . ' ' . $iconclass;

		// Instantiate a new LayoutFile instance and render the layout
		$layout = new FileLayout($this->layout);

		return $layout->render($options);
	}

	/**
	 * Get the button CSS Id.
	 *
	 * @return  string  Button CSS Id
	 *
	 * @since   3.0
	 */
	protected function fetchId()
	{
		return $this->parent->getName() . '-' . str_ireplace(' ', '-', $this->getName());
	}

	/**
	 * Method to get the CSS class name for an icon identifier
	 *
	 * Can be redefined in the final class
	 *
	 * @param   string  $identifier  Icon identification string
	 *
	 * @return  string  CSS class name
	 *
	 * @since   3.0
	 */
	public function fetchIconClass($identifier)
	{
		// It's an ugly hack, but this allows templates to define the icon classes for the toolbar
		$layout = new FileLayout('joomla.toolbar.iconclass');

		return $layout->render(array('icon' => $identifier));
	}

	/**
	 * Get the button
	 *
	 * Defined in the final button class
	 *
	 * @return  string
	 *
	 * @since   3.0
	 *
	 * @deprecated  5.0 Use render() instead.
	 */
	abstract public function fetchButton();

	/**
	 * Get parent toolbar instance.
	 *
	 * @return  Toolbar
	 *
	 * @since   4.0.0
	 */
	public function getParent(): Toolbar
	{
		return $this->parent;
	}

	/**
	 * Set parent Toolbar instance.
	 *
	 * @param   Toolbar  $parent  The parent Toolbar instance to set.
	 *
	 * @return  static  Return self to support chaining.
	 *
	 * @since   4.0.0
	 */
	public function setParent(Toolbar $parent): self
	{
		$this->parent = $parent;

		return $this;
	}

	/**
	 * Get button options.
	 *
	 * @return  array
	 *
	 * @since  4.0.0
	 */
	public function getOptions(): array
	{
		return $this->options;
	}

	/**
	 * Set all options.
	 *
	 * @param   array  $options  The button options.
	 *
	 * @return  static  Return self to support chaining.
	 *
	 * @since  4.0.0
	 */
	public function setOptions(array $options): self
	{
		$this->options = $options;

		return $this;
	}

	/**
	 * Get single option value.
	 *
	 * @param   string  $name     The option name.
	 * @param   mixed   $default  The default value if this name not exists.
	 *
	 * @return  mixed
	 *
	 * @since  4.0.0
	 */
	public function getOption(string $name, $default = null)
	{
		return $this->options[$name] ?? $default;
	}

	/**
	 * Set option value.
	 *
	 * @param   string  $name   The option name to store value.
	 * @param   mixed   $value  The option value.
	 *
	 * @return  static
	 *
	 * @since  4.0.0
	 */
	public function setOption(string $name, $value): self
	{
		$this->options[$name] = $value;

		return $this;
	}

	/**
	 * Get button name.
	 *
	 * @return  string
	 *
	 * @since  4.0.0
	 */
	public function getName(): string
	{
		return $this->name;
	}

	/**
	 * Set button name.
	 *
	 * @param   string  $name  The button name.
	 *
	 * @return  static  Return self to support chaining.
	 *
	 * @since  4.0.0
	 */
	public function name(string $name): self
	{
		$this->name = $name;

		return $this;
	}

	/**
	 * Get layout path.
	 *
	 * @return  string
	 *
	 * @since  4.0.0
	 */
	public function getLayout(): string
	{
		return $this->layout;
	}

	/**
	 * Set layout path.
	 *
	 * @param   string  $layout  The layout path name to render.
	 *
	 * @return  static  Return self to support chaining.
	 *
	 * @since  4.0.0
	 */
	public function layout(string $layout): self
	{
		$this->layout = $layout;

		return $this;
	}

	/**
	 * Make sure the id is unique
	 *
	 * @param   string  $id  The id string.
	 *
	 * @return  string
	 *
	 * @since   4.0.0
	 */
	protected function ensureUniqueId(string $id): string
	{
		if (\array_key_exists($id, static::$idCounter))
		{
			static::$idCounter[$id]++;

			$id .= static::$idCounter[$id];
		}
		else
		{
			static::$idCounter[$id] = 0;
		}

		return $id;
	}

	/**
	 * Magiix method to adapt option accessors.
	 *
	 * @param   string  $name  The method name.
	 * @param   array   $args  The method arguments.
	 *
	 * @return  mixed
	 *
	 * @throws \LogicException
	 *
	 * @since  4.0.0
	 */
	public function __call(string $name, array $args)
	{
		// Getter
		if (stripos($name, 'get') === 0)
		{
			$fieldName = static::findOptionName(lcfirst(substr($name, 3)));

			if ($fieldName !== false)
			{
				return $this->getOption($fieldName);
			}
		}
		// Setter
		else
		{
			$fieldName = static::findOptionName($name);

			if ($fieldName !== false)
			{
				if (!\array_key_exists(0, $args))
				{
					throw new \InvalidArgumentException(
						sprintf(
							'%s::%s() miss first argument.',
							\get_called_class(),
							$name
						)
					);
				}

				return $this->setOption($fieldName, $args[0]);
			}
		}

		throw new \BadMethodCallException(
			sprintf(
				'Method %s() not found in class: %s',
				$name,
				\get_called_class()
			)
		);
	}

	/**
	 * Find field option name from accessors.
	 *
	 * @param   string  $name  The field name.
	 *
	 * @return  boolean|string
	 *
	 * @since  4.0.0
	 */
	private static function findOptionName(string $name)
	{
		$accessors = static::getAccessors();

		if (\in_array($name, $accessors, true))
		{
			return $accessors[array_search($name, $accessors, true)];
		}

		// Getter with alias
		if (isset($accessors[$name]))
		{
			return $accessors[$name];
		}

		return false;
	}

	/**
	 * Method to configure available option accessors.
	 *
	 * @return  array
	 *
	 * @since  4.0.0
	 */
	protected static function getAccessors(): array
	{
		return [
			'text',
			'task',
			'icon',
			'attributes',
			'onclick',
			'buttonClass' => 'button_class',
			'listCheck',
			'listCheckMessage',
			'form',
			'formValidation',
		];
	}
}

The same content is in 2 releases, Joomla 4.0.0-beta4 to 4.0.0-beta5. See them all, or every version of this file.