Widget.php 3.77 KB
Newer Older
Alexander Kochetov committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
<?php
/**
 * @link http://www.yiiframework.com/
 * @copyright Copyright (c) 2008 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */

namespace yii\jui;

use yii\helpers\Json;

/**
 * \yii\jui\Widget is the base class for all jQuery UI widgets.
 *
 * @author Alexander Kochetov <creocoder@gmail.com>
 * @since 2.0
 */
class Widget extends \yii\base\Widget
{
	/**
Qiang Xue committed
21 22
	 * @var string the jQuery UI theme. This refers to an asset bundle class
	 * representing the JUI theme. The default theme is the official "Smoothness" theme.
Alexander Kochetov committed
23
	 */
Qiang Xue committed
24
	public static $theme = 'yii\jui\ThemeAsset';
Alexander Kochetov committed
25 26 27
	/**
	 * @var array the HTML attributes for the widget container tag.
	 */
Alexander Makarov committed
28
	public $options = [];
Alexander Kochetov committed
29 30 31 32 33 34
	/**
	 * @var array the options for the underlying jQuery UI widget.
	 * Please refer to the corresponding jQuery UI widget Web page for possible options.
	 * For example, [this page](http://api.jqueryui.com/accordion/) shows
	 * how to use the "Accordion" widget and the supported options (e.g. "header").
	 */
Alexander Makarov committed
35
	public $clientOptions = [];
Alexander Kochetov committed
36 37 38 39 40 41
	/**
	 * @var array the event handlers for the underlying jQuery UI widget.
	 * Please refer to the corresponding jQuery UI widget Web page for possible events.
	 * For example, [this page](http://api.jqueryui.com/accordion/) shows
	 * how to use the "Accordion" widget and the supported events (e.g. "create").
	 */
Alexander Makarov committed
42
	public $clientEvents = [];
Alexander Kochetov committed
43

44 45 46 47
	/**
	 * @var array event names mapped to what should be specified in .on(
	 * If empty, it is assumed that event passed to clientEvents is prefixed with widget name.
	 */
48
	protected $clientEventMap = [];
Alexander Kochetov committed
49 50 51 52 53 54 55 56 57 58 59 60 61 62

	/**
	 * Initializes the widget.
	 * If you override this method, make sure you call the parent implementation first.
	 */
	public function init()
	{
		parent::init();
		if (!isset($this->options['id'])) {
			$this->options['id'] = $this->getId();
		}
	}

	/**
63
	 * Registers a specific jQuery UI widget assets
Qiang Xue committed
64
	 * @param string $assetBundle the asset bundle for the widget
Alexander Kochetov committed
65
	 */
66
	protected function registerAssets($assetBundle)
Alexander Kochetov committed
67
	{
Qiang Xue committed
68
		/** @var \yii\web\AssetBundle $assetBundle */
69
		$assetBundle::register($this->getView());
Qiang Xue committed
70
		/** @var \yii\web\AssetBundle $themeAsset */
71
		$themeAsset = static::$theme;
72 73
		$themeAsset::register($this->getView());
	}
Alexander Kochetov committed
74

75 76 77
	/**
	 * Registers a specific jQuery UI widget options
	 * @param string $name the name of the jQuery UI widget
78
	 * @param string $id the ID of the widget
79
	 */
80
	protected function registerClientOptions($name, $id)
81
	{
Alexander Kochetov committed
82 83 84
		if ($this->clientOptions !== false) {
			$options = empty($this->clientOptions) ? '' : Json::encode($this->clientOptions);
			$js = "jQuery('#$id').$name($options);";
85
			$this->getView()->registerJs($js);
Alexander Kochetov committed
86
		}
87
	}
Alexander Kochetov committed
88

89 90 91
	/**
	 * Registers a specific jQuery UI widget events
	 * @param string $name the name of the jQuery UI widget
92
	 * @param string $id the ID of the widget
93
	 */
94
	protected function registerClientEvents($name, $id)
95
	{
Alexander Kochetov committed
96
		if (!empty($this->clientEvents)) {
Alexander Makarov committed
97
			$js = [];
Alexander Kochetov committed
98
			foreach ($this->clientEvents as $event => $handler) {
99 100
				if (isset($this->clientEventMap[$event])) {
					$eventName = $this->clientEventMap[$event];
101 102 103 104
				} else {
					$eventName = $name.$event;
				}
				$js[] = "jQuery('#$id').on('$eventName', $handler);";
Alexander Kochetov committed
105
			}
106
			$this->getView()->registerJs(implode("\n", $js));
Alexander Kochetov committed
107 108
		}
	}
109 110 111 112 113

	/**
	 * Registers a specific jQuery UI widget asset bundle, initializes it with client options and registers related events
	 * @param string $name the name of the jQuery UI widget
	 * @param string $assetBundle the asset bundle for the widget
114
	 * @param string $id the ID of the widget. If null, it will use the `id` value of [[options]].
115
	 */
116
	protected function registerWidget($name, $assetBundle, $id = null)
117
	{
118 119 120
		if ($id === null) {
			$id = $this->options['id'];
		}
121
		$this->registerAssets($assetBundle);
122 123
		$this->registerClientOptions($name, $id);
		$this->registerClientEvents($name, $id);
124
	}
Alexander Kochetov committed
125
}