Widget.php 4.69 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
<?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
{
20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53
    /**
     * @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.
     */
    public static $theme = 'yii\jui\ThemeAsset';
    /**
     * @var array the HTML attributes for the widget container tag.
     * @see \yii\helpers\Html::renderTagAttributes() for details on how attributes are being rendered.
     */
    public $options = [];
    /**
     * @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").
     */
    public $clientOptions = [];
    /**
     * @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").
     * Keys are the event names and values are javascript code that is passed to the `.on()` function
     * as the event handler.
     *
     * For example you could write the following in your widget configuration:
     *
     * ```php
     * 'clientEvents' => [
     *     'change' => 'function () { alert('event "change" occured.'); }'
     * ],
     * ```
     */
    public $clientEvents = [];
Alexander Kochetov committed
54

55 56 57 58 59
    /**
     * @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.
     */
    protected $clientEventMap = [];
Alexander Kochetov committed
60

61 62 63 64 65 66 67 68 69 70 71
    /**
     * 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();
        }
    }
72

73 74 75 76 77 78
    /**
     * Registers a specific jQuery UI widget assets
     * @param string $assetBundle the asset bundle for the widget
     */
    protected function registerAssets($assetBundle)
    {
79
        /* @var $assetBundle \yii\web\AssetBundle */
80
        $assetBundle::register($this->getView());
81
        /* @var $themeAsset \yii\web\AssetBundle */
82 83 84
        $themeAsset = static::$theme;
        $themeAsset::register($this->getView());
    }
Alexander Kochetov committed
85

86 87 88
    /**
     * Registers a specific jQuery UI widget options
     * @param string $name the name of the jQuery UI widget
89
     * @param string $id the ID of the widget
90 91 92 93 94 95 96 97 98
     */
    protected function registerClientOptions($name, $id)
    {
        if ($this->clientOptions !== false) {
            $options = empty($this->clientOptions) ? '' : Json::encode($this->clientOptions);
            $js = "jQuery('#$id').$name($options);";
            $this->getView()->registerJs($js);
        }
    }
Alexander Kochetov committed
99

100 101 102
    /**
     * Registers a specific jQuery UI widget events
     * @param string $name the name of the jQuery UI widget
103
     * @param string $id the ID of the widget
104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119
     */
    protected function registerClientEvents($name, $id)
    {
        if (!empty($this->clientEvents)) {
            $js = [];
            foreach ($this->clientEvents as $event => $handler) {
                if (isset($this->clientEventMap[$event])) {
                    $eventName = $this->clientEventMap[$event];
                } else {
                    $eventName = strtolower($name . $event);
                }
                $js[] = "jQuery('#$id').on('$eventName', $handler);";
            }
            $this->getView()->registerJs(implode("\n", $js));
        }
    }
Alexander Kochetov committed
120

121 122
    /**
     * Registers a specific jQuery UI widget asset bundle, initializes it with client options and registers related events
123
     * @param string $name the name of the jQuery UI widget
124
     * @param string $assetBundle the asset bundle for the widget
125
     * @param string $id the ID of the widget. If null, it will use the `id` value of [[options]].
126 127 128 129 130 131 132 133 134 135
     */
    protected function registerWidget($name, $assetBundle, $id = null)
    {
        if ($id === null) {
            $id = $this->options['id'];
        }
        $this->registerAssets($assetBundle);
        $this->registerClientOptions($name, $id);
        $this->registerClientEvents($name, $id);
    }
Alexander Kochetov committed
136
}