0 follower

CWidget

Package system.web.widgets
Inheritance class CWidget » CBaseController » CComponent
Subclasses CActiveForm, CBaseListView, CBasePager, CBreadcrumbs, CCaptcha, CClipWidget, CDetailView, CFilterWidget, CFlexWidget, CInputWidget, CJuiWidget, CMenu, CPortlet, CTabView, CTreeView
Since 1.0
Source Code framework/web/widgets/CWidget.php
CWidget is the base class for widgets.

A widget is a self-contained component that may generate presentation based on model data. It can be viewed as a micro-controller that embeds into the controller-managed views.

Compared with controller, a widget has neither actions nor filters.

Usage is described at CBaseController and CBaseController::widget.

Public Properties

Hide inherited properties

PropertyTypeDescriptionDefined By
actionPrefix string the prefix to the IDs of the actions. CWidget
controller CController Returns the controller that this widget belongs to. CWidget
id string Returns the ID of the widget or generates a new one if requested. CWidget
owner CBaseController Returns the owner/creator of this widget. CWidget
skin mixed the name of the skin to be used by this widget. CWidget
viewPath string Returns the directory containing the view files for this widget. CWidget

Public Methods

Hide inherited methods

MethodDescriptionDefined By
__call() Calls the named method which is not a class method. CComponent
__construct() Constructor. CWidget
__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
actions() Returns a list of actions that are used by this widget. CWidget
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
beginCache() Begins fragment caching. CBaseController
beginClip() Begins recording a clip. CBaseController
beginContent() Begins the rendering of content that is to be decorated by the specified view. CBaseController
beginWidget() Creates a widget and executes it. CBaseController
canGetProperty() Determines whether a property can be read. CComponent
canSetProperty() Determines whether a property can be set. CComponent
createWidget() Creates a widget and initializes it. CBaseController
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
endCache() Ends fragment caching. CBaseController
endClip() Ends recording a clip. CBaseController
endContent() Ends the rendering of content. CBaseController
endWidget() Ends the execution of the named widget. CBaseController
evaluateExpression() Evaluates a PHP expression or callback under the context of this component. CComponent
getController() Returns the controller that this widget belongs to. CWidget
getEventHandlers() Returns the list of attached event handlers for an event. CComponent
getId() Returns the ID of the widget or generates a new one if requested. CWidget
getOwner() Returns the owner/creator of this widget. CWidget
getViewFile() Looks for the view script file according to the view name. CWidget
getViewPath() Returns the directory containing the view files for this widget. CWidget
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 widget. CWidget
raiseEvent() Raises an event. CComponent
render() Renders a view. CWidget
renderFile() Renders a view file. CBaseController
renderInternal() Renders a view file. CBaseController
run() Executes the widget. CWidget
setId() Sets the ID of the widget. CWidget
widget() Creates a widget and executes it. CBaseController

Property Details

actionPrefix property
public string $actionPrefix;

the prefix to the IDs of the actions. When a widget is declared an action provider in CController::actions, a prefix can be specified to differentiate its action IDs from others. The same prefix should then also be used to configure this property when the widget is used in a view of the controller.

controller property read-only
public CController getController()

Returns the controller that this widget belongs to.

id property
public string getId(boolean $autoGenerate=true)
public void setId(string $value)

Returns the ID of the widget or generates a new one if requested.

owner property read-only
public CBaseController getOwner()

Returns the owner/creator of this widget.

skin property (available since v1.1)
public mixed $skin;

the name of the skin to be used by this widget. Defaults to 'default'. If this is set as false, no skin will be applied to this widget.

See Also

viewPath property read-only
public string getViewPath(boolean $checkTheme=false)

Returns the directory containing the view files for this widget. The default implementation returns the 'views' subdirectory of the directory containing the widget class file. If $checkTheme is set true, the directory "ThemeID/views/ClassName" will be returned when it exists.

Method Details

__construct() method
public void __construct(CBaseController $owner=NULL)
$owner CBaseController owner/creator of this widget. It could be either a widget or a controller.
Source Code: framework/web/widgets/CWidget.php#92 (show)
public function __construct($owner=null)
{
    $this->_owner=$owner===null?Yii::app()->getController():$owner;
}

Constructor.

actions() method
public static array actions()
{return} array
Source Code: framework/web/widgets/CWidget.php#83 (show)
public static function actions()
{
    return array();
}

Returns a list of actions that are used by this widget. The structure of this method's return value is similar to that returned by CController::actions.

When a widget uses several actions, you can declare these actions using this method. The widget will then become an action provider, and the actions can be easily imported into a controller.

Note, when creating URLs referring to the actions listed in this method, make sure the action IDs are prefixed with actionPrefix.

See Also

getController() method
public CController getController()
{return} CController the controller that this widget belongs to.
Source Code: framework/web/widgets/CWidget.php#132 (show)
public function getController()
{
    if($this->_owner instanceof CController)
        return $this->_owner;
    else
        return Yii::app()->getController();
}

Returns the controller that this widget belongs to.

getId() method
public string getId(boolean $autoGenerate=true)
$autoGenerate boolean whether to generate an ID if it is not set previously
{return} string id of the widget.
Source Code: framework/web/widgets/CWidget.php#111 (show)
public function getId($autoGenerate=true)
{
    if($this->_id!==null)
        return $this->_id;
    elseif($autoGenerate)
        return $this->_id='yw'.self::$_counter++;
}

Returns the ID of the widget or generates a new one if requested.

getOwner() method
public CBaseController getOwner()
{return} CBaseController owner/creator of this widget. It could be either a widget or a controller.
Source Code: framework/web/widgets/CWidget.php#101 (show)
public function getOwner()
{
    return $this->_owner;
}

Returns the owner/creator of this widget.

getViewFile() method
public string getViewFile(string $viewName)
$viewName string name of the view (without file extension)
{return} string the view file path. False if the view file does not exist
Source Code: framework/web/widgets/CWidget.php#200 (show)
public function getViewFile($viewName)
{
    if(($renderer=Yii::app()->getViewRenderer())!==null)
        $extension=$renderer->fileExtension;
    else
        $extension='.php';
    if(strpos($viewName,'.')) // a path alias
        $viewFile=Yii::getPathOfAlias($viewName);
    else
    {
        $viewFile=$this->getViewPath(true).DIRECTORY_SEPARATOR.$viewName;
        if(is_file($viewFile.$extension))
            return Yii::app()->findLocalizedFile($viewFile.$extension);
        elseif($extension!=='.php' && is_file($viewFile.'.php'))
            return Yii::app()->findLocalizedFile($viewFile.'.php');
        $viewFile=$this->getViewPath(false).DIRECTORY_SEPARATOR.$viewName;
    }

    if(is_file($viewFile.$extension))
        return Yii::app()->findLocalizedFile($viewFile.$extension);
    elseif($extension!=='.php' && is_file($viewFile.'.php'))
        return Yii::app()->findLocalizedFile($viewFile.'.php');
    else
        return false;
}

Looks for the view script file according to the view name. This method will look for the view under the widget's viewPath. The view script file is named as "ViewName.php". A localized view file may be returned if internationalization is needed. See CApplication::findLocalizedFile for more details. The view name can also refer to a path alias if it contains dot characters.

See Also

getViewPath() method
public string getViewPath(boolean $checkTheme=false)
$checkTheme boolean whether to check if the theme contains a view path for the widget.
{return} string the directory containing the view files for this widget.
Source Code: framework/web/widgets/CWidget.php#165 (show)
public function getViewPath($checkTheme=false)
{
    $className=get_class($this);
    $scope=$checkTheme?'theme':'local';
    if(isset(self::$_viewPaths[$className][$scope]))
        return self::$_viewPaths[$className][$scope];
    else
    {
        if($checkTheme && ($theme=Yii::app()->getTheme())!==null)
        {
            $path=$theme->getViewPath().DIRECTORY_SEPARATOR;
            if(strpos($className,'\\')!==false) // namespaced class
                $path.=str_replace('\\','_',ltrim($className,'\\'));
            else
                $path.=$className;
            if(is_dir($path))
                return self::$_viewPaths[$className]['theme']=$path;
        }

        $class=new ReflectionClass($className);
        return self::$_viewPaths[$className]['local']=dirname($class->getFileName()).DIRECTORY_SEPARATOR.'views';
    }
}

Returns the directory containing the view files for this widget. The default implementation returns the 'views' subdirectory of the directory containing the widget class file. If $checkTheme is set true, the directory "ThemeID/views/ClassName" will be returned when it exists.

init() method
public void init()
Source Code: framework/web/widgets/CWidget.php#146 (show)
public function init()
{
}

Initializes the widget. This method is called by CBaseController::createWidget and CBaseController::beginWidget after the widget's properties have been initialized.

render() method
public string render(string $view, array $data=NULL, boolean $return=false)
$view string name of the view to be rendered. See getViewFile for details about how the view script is resolved.
$data array data to be extracted into PHP variables and made available to the view script
$return boolean whether the rendering result should be returned instead of being displayed to end users
{return} string the rendering result. Null if the rendering result is not required.
Source Code: framework/web/widgets/CWidget.php#241 (show)
public function render($view,$data=null,$return=false)
{
    if(($viewFile=$this->getViewFile($view))!==false)
        return $this->renderFile($viewFile,$data,$return);
    else
        throw new CException(Yii::t('yii','{widget} cannot find the view "{view}".',
            array('{widget}'=>get_class($this), '{view}'=>$view)));
}

Renders a view.

The named view refers to a PHP script (resolved via getViewFile) that is included by this method. If $data is an associative array, it will be extracted as PHP variables and made available to the script.

See Also

run() method
public void run()
Source Code: framework/web/widgets/CWidget.php#154 (show)
public function run()
{
}

Executes the widget. This method is called by CBaseController::endWidget.

setId() method
public void setId(string $value)
$value string id of the widget.
Source Code: framework/web/widgets/CWidget.php#123 (show)
public function setId($value)
{
    $this->_id=$value;
}

Sets the ID of the widget.