CWidgetFactory

所有包 | 属性 | 方法

包	system.web
继承	class CWidgetFactory » CApplicationComponent » CComponent
实现	IApplicationComponent, IWidgetFactory
源自	1.1
版本	$Id: CWidgetFactory.php 3421 2011-10-20 21:23:38Z alexander.makarow $
源码	framework/web/CWidgetFactory.php

CWidgetFactory creates new widgets to be used in views.

CWidgetFactory is used as the default "widgetFactory" application component.

When calling CBaseController::createWidget, CBaseController::widget or CBaseController::beginWidget, if the "widgetFactory" component is installed, it will be used to create the requested widget. To install the "widgetFactory" component, we should have the following application configuration:

return array(  'components'=>array(      'widgetFactory'=>array(          'class'=>'CWidgetFactory',      ),  ),
)

CWidgetFactory implements the "skin" feature, which allows a new widget to be created and initialized with a set of predefined property values (called skin).

When CWidgetFactory is used to create a new widget, it will first instantiate the widget instance. It then checks if there is a skin available for this widget according to the widget class name and the widget CWidget::skin property. If a skin is found, it will be merged with the initial properties passed via createWidget. Then the merged initial properties will be used to initialize the newly created widget instance.

As aforementioned, a skin is a set of initial property values for a widget. It is thus represented as an associative array of name-value pairs. Skins are stored in PHP scripts like other configurations. Each script file stores the skins for a particular widget type and is named as the widget class name (e.g. CLinkPager.php). Each widget type may have one or several skins, identified by the skin name set via CWidget::skin property. If the CWidget::skin property is not set for a given widget, it means the default skin would be used. The following shows the possible skins for the CLinkPager widget:

return array(  'default'=>array(      'nextPageLabel'=>'>>',      'prevPageLabel'=>'<<',  ),  'short'=>array(      'header'=>'',      'maxButtonCount'=>5,  ),
);

In the above, there are two skins. The first one is the default skin which is indexed by the string "default". Note that CWidget::skin defaults to "default". Therefore, this is the skin that will be applied if we do not explicitly specify the CWidget::skin property. The second one is named as the "short" skin which will be used only when we set CWidget::skin to be "short".

By default, CWidgetFactory looks for the skin of a widget under the "skins" directory of the current application's CWebApplication::viewPath (e.g. protected/views/skins). If a theme is being used, it will look for the skin under the "skins" directory of the theme's CTheme::viewPath (as well as the aforementioned skin directory). In case the specified skin is not found, a widget will still be created normally without causing any error.

公共属性

隐藏继承属性

属性	类型	描述	定义在
behaviors	array	这个应用组件附加的行为。 这此行为将在应用组件调用init时附加在应用组件上。 请参照CModel::behaviors如何指定此属性值。	CApplicationComponent
enableSkin	boolean	whether to enable widget skinning.	CWidgetFactory
isInitialized	boolean	检查应用组件是否已经初始化。	CApplicationComponent
skinPath	string	the directory containing all the skin files.	CWidgetFactory
skinnableWidgets	array	list of widget class names that can be skinned.	CWidgetFactory
widgets	array	widget initial property values.	CWidgetFactory

公共方法

隐藏继承方法

方法	描述	定义在
__call()	如果类中没有调的方法名，则调用这个方法。	CComponent
__get()	返回一个属性值、一个事件处理程序列表或一个行为名称。	CComponent
__isset()	检查一个属性是否为null。	CComponent
__set()	设置一个组件的属性值。	CComponent
__unset()	设置一个组件的属性为null。	CComponent
asa()	返回这个名字的行为对象。	CComponent
attachBehavior()	附加一个行为到组件。	CComponent
attachBehaviors()	附加一个行为列表到组件。	CComponent
attachEventHandler()	为事件附加一个事件处理程序。	CComponent
canGetProperty()	确定属性是否可读。	CComponent
canSetProperty()	确定属性是否可写。	CComponent
createWidget()	Creates a new widget based on the given class name and initial properties.	CWidgetFactory
detachBehavior()	从组件中分离一个行为。	CComponent
detachBehaviors()	从组件中分离所有行为。	CComponent
detachEventHandler()	分离一个存在的事件处理程序。	CComponent
disableBehavior()	禁用一个附加行为。	CComponent
disableBehaviors()	禁用组件附加的所有行为。	CComponent
enableBehavior()	启用一个附加行为。	CComponent
enableBehaviors()	启用组件附加的所有行为。	CComponent
evaluateExpression()	计算一个PHP表达式，或根据组件上下文执行回调。	CComponent
getEventHandlers()	返回一个事件的附加处理程序列表。	CComponent
getIsInitialized()	检查应用组件是否已经初始化。	CApplicationComponent
hasEvent()	确定一个事件是否定义。	CComponent
hasEventHandler()	检查事件是否有附加的处理程序。	CComponent
hasProperty()	确定属性是否被定义。	CComponent
init()	Initializes the application component.	CWidgetFactory
raiseEvent()	发起一个事件。	CComponent

受保护方法

隐藏继承方法

方法	描述	定义在
getSkin()	Returns the skin for the specified widget class and skin name.	CWidgetFactory

属性详细

enableSkin 属性 （可用自 v1.1.3） public boolean $enableSkin;

whether to enable widget skinning. Defaults to false.

参见

• skinnableWidgets

skinPath 属性 public string $skinPath;

the directory containing all the skin files. Defaults to null, meaning using the "skins" directory under the current application's CWebApplication::viewPath.

skinnableWidgets 属性 （可用自 v1.1.3） public array $skinnableWidgets;

list of widget class names that can be skinned. Because skinning widgets has performance impact, you may want to specify this property to limit skinning only to specific widgets. Any widgets that are not in this list will not be skinned. Defaults to null, meaning all widgets can be skinned.

widgets 属性 （可用自 v1.1.3） public array $widgets;

widget initial property values. Each array key-value pair represents the initial property values for a single widget class, with the array key being the widget class name, and array value being the initial property value array. For example,

array(  'CLinkPager'=>array(      'maxButtonCount'=>5,      'cssFile'=>false,  ),  'CJuiDatePicker'=>array(      'language'=>'ru',  ),
)

Note that the initial values specified here may be overridden by the values given in CBaseController::createWidget calls. They may also be overridden by widget skins, if enableSkin is true.

方法详细

createWidget() 方法

public CWidget createWidget(CBaseController $owner, string $className, array $properties=array ( ))
$owner	CBaseController	the owner of the new widget
$className	string	the class name of the widget. This can also be a path alias (e.g. system.web.widgets.COutputCache)
$properties	array	the initial property values (name=>value) of the widget.
{return}	CWidget	the newly created widget whose properties have been initialized with the given values.

源码： framework/web/CWidgetFactory.php#145 (显示) publicfunctioncreateWidget($owner,$className,$properties=array())
{
$className=Yii::import($className,true);
$widget=new$className($owner);

if(isset($this->widgets[$className]))
$properties=$properties===array()?$this->widgets[$className]:CMap::mergeArray($this->widgets[$className],$properties);
if($this->enableSkin)
{
if($this->skinnableWidgets===null||in_array($className,$this->skinnableWidgets))
{
$skinName=isset($properties['skin'])?$properties['skin']:'default';
if($skinName!==false&&($skin=$this->getSkin($className,$skinName))!==array())
$properties=$properties===array()?$skin:CMap::mergeArray($skin,$properties);
}
}
foreach($propertiesas$name=>$value)
$widget->$name=$value;
return$widget;
}

Creates a new widget based on the given class name and initial properties.

getSkin() 方法

protected array getSkin(string $className, string $skinName)
$className	string	the widget class name
$skinName	string	the widget skin name
{return}	array	the skin (name=>value) for the widget

源码： framework/web/CWidgetFactory.php#172 (显示) protectedfunctiongetSkin($className,$skinName)
{
if(!isset($this->_skins[$className][$skinName]))
{
$skinFile=$this->skinPath.DIRECTORY_SEPARATOR.$className.'.php';
if(is_file($skinFile))
$this->_skins[$className]=require($skinFile);
else
$this->_skins[$className]=array();

if(($theme=Yii::app()->getTheme())!==null)
{
$skinFile=$theme->getSkinPath().DIRECTORY_SEPARATOR.$className.'.php';
if(is_file($skinFile))
{
$skins=require($skinFile);
foreach($skinsas$name=>$skin)
$this->_skins[$className][$name]=$skin;
}
}

if(!isset($this->_skins[$className][$skinName]))
$this->_skins[$className][$skinName]=array();
}
return$this->_skins[$className][$skinName];
}

Returns the skin for the specified widget class and skin name.

init() 方法

public void init()

源码： framework/web/CWidgetFactory.php#130 (显示) publicfunctioninit()
{
parent::init();

if($this->enableSkin&&$this->skinPath===null)
$this->skinPath=Yii::app()->getViewPath().DIRECTORY_SEPARATOR.'skins';
}

Initializes the application component. This method overrides the parent implementation by resolving the skin path.