system system.base system.caching system.caching.dependencies system.collections system.console system.db system.db.ar system.db.schema system.db.schema.cubrid system.db.schema.mssql system.db.schema.mysql system.db.schema.oci system.db.schema.pgsql system.db.schema.sqlite system.gii system.i18n system.i18n.gettext system.logging system.test system.utils system.validators system.web system.web.actions system.web.auth system.web.filters system.web.form system.web.helpers system.web.renderers system.web.services system.web.widgets system.web.widgets.captcha system.web.widgets.pagers zii.behaviors zii.widgets zii.widgets.grid zii.widgets.jui

CWidgetFactory

system.web
继承 class CWidgetFactory » CApplicationComponent » CComponent
实现 IApplicationComponent, IWidgetFactory
可用自 1.1
源码 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 the behaviors that should be attached to this component. CApplicationComponent
enableSkin boolean whether to enable widget skinning. CWidgetFactory
isInitialized boolean Checks if this application component has been initialized. 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() Calls the named method which is not a class method. CComponent
__get() Returns a property value, an event handler list or a behavior based on its name. CComponent
__isset() Checks if a property value is null. CComponent
__set() Sets value of a component property. CComponent
__unset() Sets a component property to be null. CComponent
asa() Returns the named behavior object. CComponent
attachBehavior() Attaches a behavior to this component. CComponent
attachBehaviors() Attaches a list of behaviors to the component. CComponent
attachEventHandler() Attaches an event handler to an event. CComponent
canGetProperty() Determines whether a property can be read. CComponent
canSetProperty() Determines whether a property can be set. CComponent
createWidget() Creates a new widget based on the given class name and initial properties. CWidgetFactory
detachBehavior() Detaches a behavior from the component. CComponent
detachBehaviors() Detaches all behaviors from the component. CComponent
detachEventHandler() Detaches an existing event handler. CComponent
disableBehavior() Disables an attached behavior. CComponent
disableBehaviors() Disables all behaviors attached to this component. CComponent
enableBehavior() Enables an attached behavior. CComponent
enableBehaviors() Enables all behaviors attached to this component. CComponent
evaluateExpression() Evaluates a PHP expression or callback under the context of this component. CComponent
getEventHandlers() Returns the list of attached event handlers for an event. CComponent
getIsInitialized() Checks if this application component has been initialized. CApplicationComponent
hasEvent() Determines whether an event is defined. CComponent
hasEventHandler() Checks whether the named event has attached handlers. CComponent
hasProperty() Determines whether a property is defined. CComponent
init() Initializes the application component. CWidgetFactory
raiseEvent() Raises an event. 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.

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#144 (显示)
public function createWidget($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(
$properties as $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#171 (显示)
protected function getSkin($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(
$skins as $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#129 (显示)
public function init()
{
    
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.