You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

209 lines
6.9KB

  1. <?php
  2. /**
  3. * @link http://www.yiiframework.com/
  4. * @copyright Copyright (c) 2008 Yii Software LLC
  5. * @license http://www.yiiframework.com/license/
  6. */
  7. namespace yii\base;
  8. use Yii;
  9. use ReflectionClass;
  10. /**
  11. * Widget is the base class for widgets.
  12. *
  13. * @property string $id ID of the widget.
  14. * @property \yii\web\View $view The view object that can be used to render views or view files. Note that the
  15. * type of this property differs in getter and setter. See [[getView()]] and [[setView()]] for details.
  16. * @property string $viewPath The directory containing the view files for this widget. This property is
  17. * read-only.
  18. *
  19. * @author Qiang Xue <qiang.xue@gmail.com>
  20. * @since 2.0
  21. */
  22. class Widget extends Component implements ViewContextInterface
  23. {
  24. /**
  25. * @var integer a counter used to generate [[id]] for widgets.
  26. * @internal
  27. */
  28. public static $counter = 0;
  29. /**
  30. * @var string the prefix to the automatically generated widget IDs.
  31. * @see getId()
  32. */
  33. public static $autoIdPrefix = 'w';
  34. /**
  35. * @var Widget[] the widgets that are currently being rendered (not ended). This property
  36. * is maintained by [[begin()]] and [[end()]] methods.
  37. * @internal
  38. */
  39. public static $stack = [];
  40. /**
  41. * Begins a widget.
  42. * This method creates an instance of the calling class. It will apply the configuration
  43. * to the created instance. A matching [[end()]] call should be called later.
  44. * @param array $config name-value pairs that will be used to initialize the object properties
  45. * @return static the newly created widget instance
  46. */
  47. public static function begin($config = [])
  48. {
  49. $config['class'] = get_called_class();
  50. /* @var $widget Widget */
  51. $widget = Yii::createObject($config);
  52. static::$stack[] = $widget;
  53. return $widget;
  54. }
  55. /**
  56. * Ends a widget.
  57. * Note that the rendering result of the widget is directly echoed out.
  58. * @return static the widget instance that is ended.
  59. * @throws InvalidCallException if [[begin()]] and [[end()]] calls are not properly nested
  60. */
  61. public static function end()
  62. {
  63. if (!empty(static::$stack)) {
  64. $widget = array_pop(static::$stack);
  65. if (get_class($widget) === get_called_class()) {
  66. echo $widget->run();
  67. return $widget;
  68. } else {
  69. throw new InvalidCallException("Expecting end() of " . get_class($widget) . ", found " . get_called_class());
  70. }
  71. } else {
  72. throw new InvalidCallException("Unexpected " . get_called_class() . '::end() call. A matching begin() is not found.');
  73. }
  74. }
  75. /**
  76. * Creates a widget instance and runs it.
  77. * The widget rendering result is returned by this method.
  78. * @param array $config name-value pairs that will be used to initialize the object properties
  79. * @return string the rendering result of the widget.
  80. */
  81. public static function widget($config = [])
  82. {
  83. ob_start();
  84. ob_implicit_flush(false);
  85. /* @var $widget Widget */
  86. $config['class'] = get_called_class();
  87. $widget = Yii::createObject($config);
  88. $out = $widget->run();
  89. return ob_get_clean() . $out;
  90. }
  91. private $_id;
  92. /**
  93. * Returns the ID of the widget.
  94. * @param boolean $autoGenerate whether to generate an ID if it is not set previously
  95. * @return string ID of the widget.
  96. */
  97. public function getId($autoGenerate = true)
  98. {
  99. if ($autoGenerate && $this->_id === null) {
  100. $this->_id = static::$autoIdPrefix . static::$counter++;
  101. }
  102. return $this->_id;
  103. }
  104. /**
  105. * Sets the ID of the widget.
  106. * @param string $value id of the widget.
  107. */
  108. public function setId($value)
  109. {
  110. $this->_id = $value;
  111. }
  112. private $_view;
  113. /**
  114. * Returns the view object that can be used to render views or view files.
  115. * The [[render()]] and [[renderFile()]] methods will use
  116. * this view object to implement the actual view rendering.
  117. * If not set, it will default to the "view" application component.
  118. * @return \yii\web\View the view object that can be used to render views or view files.
  119. */
  120. public function getView()
  121. {
  122. if ($this->_view === null) {
  123. $this->_view = Yii::$app->getView();
  124. }
  125. return $this->_view;
  126. }
  127. /**
  128. * Sets the view object to be used by this widget.
  129. * @param View $view the view object that can be used to render views or view files.
  130. */
  131. public function setView($view)
  132. {
  133. $this->_view = $view;
  134. }
  135. /**
  136. * Executes the widget.
  137. * @return string the result of widget execution to be outputted.
  138. */
  139. public function run()
  140. {
  141. }
  142. /**
  143. * Renders a view.
  144. * The view to be rendered can be specified in one of the following formats:
  145. *
  146. * - path alias (e.g. "@app/views/site/index");
  147. * - absolute path within application (e.g. "//site/index"): the view name starts with double slashes.
  148. * The actual view file will be looked for under the [[Application::viewPath|view path]] of the application.
  149. * - absolute path within module (e.g. "/site/index"): the view name starts with a single slash.
  150. * The actual view file will be looked for under the [[Module::viewPath|view path]] of the currently
  151. * active module.
  152. * - relative path (e.g. "index"): the actual view file will be looked for under [[viewPath]].
  153. *
  154. * If the view name does not contain a file extension, it will use the default one `.php`.
  155. *
  156. * @param string $view the view name.
  157. * @param array $params the parameters (name-value pairs) that should be made available in the view.
  158. * @return string the rendering result.
  159. * @throws InvalidParamException if the view file does not exist.
  160. */
  161. public function render($view, $params = [])
  162. {
  163. return $this->getView()->render($view, $params, $this);
  164. }
  165. /**
  166. * Renders a view file.
  167. * @param string $file the view file to be rendered. This can be either a file path or a path alias.
  168. * @param array $params the parameters (name-value pairs) that should be made available in the view.
  169. * @return string the rendering result.
  170. * @throws InvalidParamException if the view file does not exist.
  171. */
  172. public function renderFile($file, $params = [])
  173. {
  174. return $this->getView()->renderFile($file, $params, $this);
  175. }
  176. /**
  177. * Returns the directory containing the view files for this widget.
  178. * The default implementation returns the 'views' subdirectory under the directory containing the widget class file.
  179. * @return string the directory containing the view files for this widget.
  180. */
  181. public function getViewPath()
  182. {
  183. $class = new ReflectionClass($this);
  184. return dirname($class->getFileName()) . DIRECTORY_SEPARATOR . 'views';
  185. }
  186. }