Yii2 source code learning notes (20), yii2 source code learning notes
Widget class is the base class of all components. Yii2 \ base \ Widget. php
1 <? Php 2/*** @ link http://www.yiiframework.com/4 * @ copyright Copyright (c) 2008 Yii Software LLC 5 * @ license http://www.yiiframework.com/license/ 6 */7 8 namespace yii \ base; 9 10 use Yii; 11 use ReflectionClass; 12 13/** 14 * Widget is the base class for widgets. 15 * widgets are the base class of all widgets 16 * @ property string $ id of the Widget. widget ID 17 * @ property \ yii \ web \ View $ view The view object that can Be used to render views or view files. note that the 18 * type of this property differs in getter and setter. see [[getView ()] and [[setView ()] for details. 19 * view objects used to render views or view files are different in getter and setter 20 * @ property string $ viewPath The directory containing the view files for this widget. this property is 21 * read-only. view File directory containing this control 22*23 * @ author Qiang Xue <qiang.xue@gmail.com> 24 * @ since 2.0 25 */26 class Widget extends Component implements ViewContextInterface 27 {28/** 29 * @ var integer a counter used to generate [[id] for widgets. 30 * @ internal: counter 31 */32 public static $ counter = 0; 33/** 34 * @ var string the prefix to the automatically generated widget IDs. 35 * @ see getId () automatically generated prefix 36 */37 public static $ autoIdPrefix = 'W'; 38/** 39 * @ var Widget [] Widgets that are currently being rendered (not ended ). this property 40 * is maintained by [[begin ()] and [[end ()] methods. currently the rendered widget is 41 * @ internal 42 */43 public static $ stack = []; 44 45 46/** 47 * Begins a widget. start a part 48 * This method creates an instance of the calling class. it will apply the configuration 49 * to the created instance. A matching [[end ()] call shoshould be called later. 50 * Create an instance of the call class from the application configuration file, and [end ()] the method corresponds to 51 * @ param array $ config name-value pairs that will be used to initialize the object properties 52 * parameter 53 * @ return static the newly created widget instance static newly created part instance 54 */55 public static function begin ($ config = []) 56 {57 $ config ['class'] = get_called_class (); // The Name Of The static binding class in the later stage. 58/* @ var $ widget Widget */59 $ widget = Yii :: createObject ($ config); // pass the class Name and input configuration, instantiate call class 60 static: $ stack [] = $ widget; // put the object into the rendered part stack 61 62 return $ widget; 63} 64 65/** 66 * Ends a widget. end widget 67 * Note that the rendering result of the widget is directly echoed out. the rendering result is directly echoed 68 * @ return static the widget instance that is ended. static end part instance. 69 * @ throws InvalidCallException if [[begin ()] and [[end ()] CILS are not properly nested 70 */71 public static function end () 72 {73 if (! Empty (static: $ stack) {// The Calling class instance 74 $ widget = array_pop (static ::$ stack) exists in the rendered widget stack ); // Delete the last instance from the stack 75 if (get_class ($ widget) === get_called_class () {76 echo $ widget-> run (); // If the deleted instance class name and the current call class name are the same, the output widget's content 77 return $ widget; 78} else {79 throw new InvalidCallException ("Expecting end () of ". get_class ($ widget ). ", found ". get_called_class (); 80} 81} else {82 throw new InvalidCallException (" Unexpected ". get_called_class (). ': end () call. A matching begin () is not found. '); 83} 84} 85 86/** 87 * Creates a widget instance and runs it. create a part instance and run 88 * The widget rendering result is returned by this method. returns the part rendering result. 89 * @ param array $ config name-value pairs that will be used to initialize the object properties 90 * parameter 91 * @ return string the rendering result of the widget used to initialize the object properties. control rendering result. 92 */93 public static function widget ($ config = []) 94 {95 ob_start (); // open the output buffer 96 ob_implicit_flush (false ); // close the absolute refresh 97/* @ var $ widget Widget */98 $ config ['class'] = get_called_class (); // obtain the call class name 99 $ widget = Yii: createObject ($ config); // instantiate class 100 $ out = $ widget-> run (); // run part 101 102 return ob_get_clean (). $ out; // return the content of the internal buffer, disable buffer 103} 104 105 private $ _ id; 106 107/** 108 * Returns the ID of th E widget. returns the plug-in ID 109 * @ param boolean $ autoGenerate whether to generate an ID if it is not set previusly110 * whether to generate a unique ID, if 111 * @ return string ID of the widget is not set. unique part id 112 */113 public function getId ($ autoGenerate = true) 114 {115 if ($ autoGenerate & $ this-> _ id = null) {116 // If the id is empty and is set to allow automatic generation of the id, 117 $ this-> _ id = static: $ autoIdPrefix is automatically generated. static: $ counter ++; 118} 119 120 return $ this-> _ id; 121} 122 123/** 124 * Sets the ID of the widget. Set the widget id 125 * @ param string $ value ID of the widget. the widget id. 126 */127 public function setId ($ value) 128 {129 $ this-> _ id = $ value; 130} 131 132 private $ _ view; 133 134/** 135 * Returns the view object that can be used to render views or view files. returns The view object 136 * the [[render ()] and [[renderFile ()] methods will use137 * this view object to implement The actual view rendering.138 * [render ()] and the [renderFile ()] method use the view object to display the actual view. 139 * If not set, it will default to the "view" application component.140 * @ return \ yii \ web \ View the view object that can be used to render views or view files.141 */142 public function getView () 143 {144 if ($ this-> _ view = null) {145 $ this-> _ view = Yii: $ app-> getView (); // if the view object is empty, call getView () to obtain the view object instance 146} 147 148 return $ this-> _ view; 149} 150 151/** 152 * Sets the view object to be used by this wid Get. set the View object instance called by the current part 153 * @ param view $ view the view object that can be used to render views or view files.154 */155 public function setView ($ View) 156 {157 $ this-> _ view = $ view; // view object to use 158} 159 160/** 161 * Executes the widget. execute part 162 * @ return string the result of widget execution to be outputted.163. 164 */165 public function run () 166 {167} 168 169/** 170 * Renders a view.171 * The view to be rendered can be specified in one of the following formats: 172 * rendering a View that actually calls the method of rendering with the same name in the View class. You can specify the path 173 *-path alias (e.g. "@ app/views/site/index"); 174 *-absolute path within application (e.g. "// site/index"): the view name starts with double slashes.175 * The actual view file will be looked for under the [Application :: viewPath | view path] of the application.176 *-absolute path within module (e.g. "/site/index"): the view name starts with a single slash.177 * The actual view file will be looked for under the [Module :: viewPath | view path] of the currently178 * active module.179 *-relative path (e.g. "index"): the actual view file will be looked for under [[viewPath]. 180*181 * If the view name does not contain a file extension, it will use the default one '. php '. 182*183 * @ param string $ view the view name. view name 184 * @ param array $ params the parameters (name-value pairs) that shoshould be made available in the view.185 * parameter available in the view 186 * @ return string the rendering result. rendering result 187 * @ throws InvalidParamException if the view file does not exist.188 */189 public function render ($ view, $ params = []) 190 {191 // call render in the view class to render the specified view 192 return $ this-> getView ()-> render ($ view, $ params, $ this ); 193} 194 195/** 196 * Renders a view file. rendering a view file is the same as 197 * @ param string $ file the view file to be rendered. this can be either a file path or a path alias.198 * @ param array $ params the parameters (name-value pairs) that shoshould be made available in the view.199 * @ return string the rendering result.200 * @ throws InvalidParamException if the view file does not exist.201 */202 public function renderFile ($ file, $ params = []) 203 {204 return $ this-> getView ()-> renderFile ($ file, $ params, $ this ); 205} 206 207/** 208 * Returns the directory containing the view files for this widget. return to The view File Path 209 * the default implementation returns the 'view' subdirectory under the directory containing the widget class file.210 * @ return string the directory containing The view files for this widget.211 */212 public function getViewPath () 213 {214 $ class = new ReflectionClass ($ this); 215 // obtain the directory of the part class file and splice it into the view directory 216 return dirname ($ class-> getFileName ()). DIRECTORY_SEPARATOR. 'Views '; 217} 218}