CWidgetFactory

CWidgetFactory creates new widgets to be used in views.

CWidgetFactory is used as the default "widgetFactory" application component. When calling {@link CBaseController::createWidget}, {@link CBaseController::widget} or {@link 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 {@link CWidget::skin} property. If a skin is found, it will be merged with the initial properties passed via {@link 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 {@link CWidget::skin} property. If the {@link 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 {@link 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 {@link CWidget::skin} defaults to "default". Therefore, this is the skin that will be applied if we do not explicitly specify the {@link CWidget::skin} property. The second one is named as the "short" skin which will be used only when we set {@link CWidget::skin} to be "short". By default, CWidgetFactory looks for the skin of a widget under the "skins" directory of the current application's {@link 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 {@link 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.