Widget.php 6.66 KB
Newer Older
Qiang Xue committed
1 2 3
<?php
/**
 * @link http://www.yiiframework.com/
Qiang Xue committed
4
 * @copyright Copyright (c) 2008 Yii Software LLC
Qiang Xue committed
5 6 7 8 9
 * @license http://www.yiiframework.com/license/
 */

namespace yii\base;

Qiang Xue committed
10
use Yii;
11
use ReflectionClass;
Qiang Xue committed
12

Qiang Xue committed
13 14 15
/**
 * Widget is the base class for widgets.
 *
16
 * @property string $id ID of the widget.
Qiang Xue committed
17 18
 * @property \yii\web\View $view The view object that can be used to render views or view files. Note that the
 * type of this property differs in getter and setter. See [[getView()]] and [[setView()]] for details.
19 20
 * @property string $viewPath The directory containing the view files for this widget. This property is
 * read-only.
21
 *
Qiang Xue committed
22 23 24
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @since 2.0
 */
25
class Widget extends Component implements ViewContextInterface
Qiang Xue committed
26
{
27 28 29 30 31 32 33 34 35 36 37
	/**
	 * @var integer a counter used to generate [[id]] for widgets.
	 * @internal
	 */
	public static $counter = 0;
	/**
	 * @var string the prefix to the automatically generated widget IDs.
	 * @see [[getId()]]
	 */
	public static $autoIdPrefix = 'w';

38 39 40 41 42
	/**
	 * @var Widget[] the widgets that are currently being rendered (not ended). This property
	 * is maintained by [[begin()]] and [[end()]] methods.
	 * @internal
	 */
43
	public static $stack = [];
44

45
	
46 47 48 49 50
	/**
	 * Begins a widget.
	 * This method creates an instance of the calling class. It will apply the configuration
	 * to the created instance. A matching [[end()]] call should be called later.
	 * @param array $config name-value pairs that will be used to initialize the object properties
Qiang Xue committed
51
	 * @return static the newly created widget instance
52
	 */
Alexander Makarov committed
53
	public static function begin($config = [])
54 55 56
	{
		$config['class'] = get_called_class();
		/** @var Widget $widget */
57
		$widget = Yii::createObject($config);
58
		self::$stack[] = $widget;
59 60 61 62 63 64
		return $widget;
	}

	/**
	 * Ends a widget.
	 * Note that the rendering result of the widget is directly echoed out.
Qiang Xue committed
65
	 * @return static the widget instance that is ended.
66 67 68 69
	 * @throws InvalidCallException if [[begin()]] and [[end()]] calls are not properly nested
	 */
	public static function end()
	{
70 71
		if (!empty(self::$stack)) {
			$widget = array_pop(self::$stack);
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88
			if (get_class($widget) === get_called_class()) {
				$widget->run();
				return $widget;
			} else {
				throw new InvalidCallException("Expecting end() of " . get_class($widget) . ", found " . get_called_class());
			}
		} else {
			throw new InvalidCallException("Unexpected " . get_called_class() . '::end() call. A matching begin() is not found.');
		}
	}

	/**
	 * Creates a widget instance and runs it.
	 * The widget rendering result is returned by this method.
	 * @param array $config name-value pairs that will be used to initialize the object properties
	 * @return string the rendering result of the widget.
	 */
Alexander Makarov committed
89
	public static function widget($config = [])
90 91 92 93 94
	{
		ob_start();
		ob_implicit_flush(false);
		/** @var Widget $widget */
		$config['class'] = get_called_class();
95
		$widget = Yii::createObject($config);
Alexander Makarov committed
96 97
		$out = $widget->run();
		return ob_get_clean() . $out;
98
	}
Qiang Xue committed
99

100 101
	private $_id;
	
Qiang Xue committed
102 103 104 105 106 107 108 109
	/**
	 * Returns the ID of the widget.
	 * @param boolean $autoGenerate whether to generate an ID if it is not set previously
	 * @return string ID of the widget.
	 */
	public function getId($autoGenerate = true)
	{
		if ($autoGenerate && $this->_id === null) {
110
			$this->_id = self::$autoIdPrefix . self::$counter++;
Qiang Xue committed
111 112 113 114 115 116 117 118 119 120 121 122 123
		}
		return $this->_id;
	}

	/**
	 * Sets the ID of the widget.
	 * @param string $value id of the widget.
	 */
	public function setId($value)
	{
		$this->_id = $value;
	}

124 125 126 127 128 129 130
	private $_view;
	
	/**
	 * Returns the view object that can be used to render views or view files.
	 * The [[render()]] and [[renderFile()]] methods will use
	 * this view object to implement the actual view rendering.
	 * If not set, it will default to the "view" application component.
131
	 * @return \yii\web\View the view object that can be used to render views or view files.
132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149
	 */
	public function getView()
	{
		if ($this->_view === null) {
			$this->_view = Yii::$app->getView();
		}
		return $this->_view;
	}

	/**
	 * Sets the view object to be used by this widget.
	 * @param View $view the view object that can be used to render views or view files.
	 */
	public function setView($view)
	{
		$this->_view = $view;
	}

Qiang Xue committed
150 151
	/**
	 * Executes the widget.
Alexander Makarov committed
152
	 * @return string the result of widget execution to be outputted.
Qiang Xue committed
153 154 155 156 157 158 159
	 */
	public function run()
	{
	}

	/**
	 * Renders a view.
Qiang Xue committed
160 161 162 163 164 165 166 167 168 169 170 171
	 * The view to be rendered can be specified in one of the following formats:
	 *
	 * - path alias (e.g. "@app/views/site/index");
	 * - absolute path within application (e.g. "//site/index"): the view name starts with double slashes.
	 *   The actual view file will be looked for under the [[Application::viewPath|view path]] of the application.
	 * - absolute path within module (e.g. "/site/index"): the view name starts with a single slash.
	 *   The actual view file will be looked for under the [[Module::viewPath|view path]] of the currently
	 *   active module.
	 * - relative path (e.g. "index"): the actual view file will be looked for under [[viewPath]].
	 *
	 * If the view name does not contain a file extension, it will use the default one `.php`.

Qiang Xue committed
172 173 174 175
	 * @param string $view the view name. Please refer to [[findViewFile()]] on how to specify a view name.
	 * @param array $params the parameters (name-value pairs) that should be made available in the view.
	 * @return string the rendering result.
	 * @throws InvalidParamException if the view file does not exist.
Qiang Xue committed
176
	 */
Alexander Makarov committed
177
	public function render($view, $params = [])
Qiang Xue committed
178
	{
179
		return $this->getView()->render($view, $params, $this);
Qiang Xue committed
180 181 182
	}

	/**
Qiang Xue committed
183 184 185 186 187
	 * Renders a view file.
	 * @param string $file the view file to be rendered. This can be either a file path or a path alias.
	 * @param array $params the parameters (name-value pairs) that should be made available in the view.
	 * @return string the rendering result.
	 * @throws InvalidParamException if the view file does not exist.
Qiang Xue committed
188
	 */
Alexander Makarov committed
189
	public function renderFile($file, $params = [])
Qiang Xue committed
190
	{
191
		return $this->getView()->renderFile($file, $params, $this);
Qiang Xue committed
192
	}
Qiang Xue committed
193 194 195 196 197 198 199 200

	/**
	 * Returns the directory containing the view files for this widget.
	 * The default implementation returns the 'views' subdirectory under the directory containing the widget class file.
	 * @return string the directory containing the view files for this widget.
	 */
	public function getViewPath()
	{
201
		$class = new ReflectionClass($this);
Qiang Xue committed
202 203
		return dirname($class->getFileName()) . DIRECTORY_SEPARATOR . 'views';
	}
Qiang Xue committed
204 205 206

	/**
	 * Finds the view file based on the given view name.
207 208
	 * File will be searched under [[viewPath]] directory.
	 * @param string $view the view name.
Qiang Xue committed
209 210
	 * @return string the view file path. Note that the file may not exist.
	 */
211
	public function findViewFile($view)
Qiang Xue committed
212
	{
213
		return $this->getViewPath() . DIRECTORY_SEPARATOR . $view;
Qiang Xue committed
214
	}
Zander Baldwin committed
215
}