CWidgetFactory

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.

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

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;
}

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];
}

public function init()
{
    parent::init();

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