Widget.php 6.3 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 17
 * @property string $id ID of the widget.
 * @property View $view The view object that can be used to render views or view files.
18 19
 * @property string $viewPath The directory containing the view files for this widget. This property is
 * read-only.
20
 *
Qiang Xue committed
21 22 23
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @since 2.0
 */
24
class Widget extends Component implements ViewContextInterface
Qiang Xue committed
25 26
{
	/**
27 28
	 * @var integer a counter used to generate [[id]] for widgets.
	 * @internal
Qiang Xue committed
29
	 */
30 31 32 33 34 35
	public static $_counter = 0;
	/**
	 * @var Widget[] the widgets that are currently being rendered (not ended). This property
	 * is maintained by [[begin()]] and [[end()]] methods.
	 * @internal
	 */
Alexander Makarov committed
36
	public static $_stack = [];
37

38
	
39 40 41 42 43 44 45
	/**
	 * 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
	 * @return Widget the newly created widget instance
	 */
Alexander Makarov committed
46
	public static function begin($config = [])
47 48 49
	{
		$config['class'] = get_called_class();
		/** @var Widget $widget */
50
		$widget = Yii::createObject($config);
51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81
		self::$_stack[] = $widget;
		return $widget;
	}

	/**
	 * Ends a widget.
	 * Note that the rendering result of the widget is directly echoed out.
	 * @return Widget the widget instance that is ended.
	 * @throws InvalidCallException if [[begin()]] and [[end()]] calls are not properly nested
	 */
	public static function end()
	{
		if (!empty(self::$_stack)) {
			$widget = array_pop(self::$_stack);
			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
82
	public static function widget($config = [])
83 84 85 86 87
	{
		ob_start();
		ob_implicit_flush(false);
		/** @var Widget $widget */
		$config['class'] = get_called_class();
88
		$widget = Yii::createObject($config);
89 90 91
		$widget->run();
		return ob_get_clean();
	}
Qiang Xue committed
92

93 94
	private $_id;
	
Qiang Xue committed
95 96 97 98 99 100 101 102
	/**
	 * 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) {
Qiang Xue committed
103
			$this->_id = 'w' . self::$_counter++;
Qiang Xue committed
104 105 106 107 108 109 110 111 112 113 114 115 116
		}
		return $this->_id;
	}

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

117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142
	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.
	 * @return View the view object that can be used to render views or view files.
	 */
	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
143 144 145 146 147 148 149 150 151
	/**
	 * Executes the widget.
	 */
	public function run()
	{
	}

	/**
	 * Renders a view.
Qiang Xue committed
152 153 154 155 156 157 158 159 160 161 162 163
	 * 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
164 165 166 167
	 * @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
168
	 */
Alexander Makarov committed
169
	public function render($view, $params = [])
Qiang Xue committed
170
	{
171
		return $this->getView()->render($view, $params, $this);
Qiang Xue committed
172 173 174
	}

	/**
Qiang Xue committed
175 176 177 178 179
	 * 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
180
	 */
Alexander Makarov committed
181
	public function renderFile($file, $params = [])
Qiang Xue committed
182
	{
183
		return $this->getView()->renderFile($file, $params, $this);
Qiang Xue committed
184
	}
Qiang Xue committed
185 186 187 188 189 190 191 192

	/**
	 * 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()
	{
193
		$class = new ReflectionClass($this);
Qiang Xue committed
194 195
		return dirname($class->getFileName()) . DIRECTORY_SEPARATOR . 'views';
	}
Qiang Xue committed
196 197 198

	/**
	 * Finds the view file based on the given view name.
199 200
	 * File will be searched under [[viewPath]] directory.
	 * @param string $view the view name.
Qiang Xue committed
201 202
	 * @return string the view file path. Note that the file may not exist.
	 */
203
	public function findViewFile($view)
Qiang Xue committed
204
	{
205
		return $this->getViewPath() . DIRECTORY_SEPARATOR . $view;
Qiang Xue committed
206
	}
Zander Baldwin committed
207
}