0 follower

CBaseListView

Package zii.widgets
Inheritance abstract class CBaseListView » CWidget » CBaseController » CComponent
Subclasses CGridView, CListView
Since 1.1
Source Code framework/zii/widgets/CBaseListView.php
CBaseListView is the base class for CListView and CGridView.

CBaseListView implements the common features needed by a view wiget for rendering multiple models.

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
dataProvider IDataProvider the data provider for the view. CBaseListView
emptyCssClass string the CSS class name for the container of the emptyText property. CBaseListView
emptyTagName string the HTML tag name for the container of the emptyText property. CBaseListView
emptyText string the message to be displayed when dataProvider does not have any data. CBaseListView
enablePagination boolean whether to enable pagination. CBaseListView
enableSorting boolean whether to enable sorting. CBaseListView
htmlOptions array the HTML options for the view container tag. CBaseListView
id string Returns the ID of the widget or generates a new one if requested. CWidget
itemsCssClass string the CSS class name for the container of all data item display. CBaseListView
loadingCssClass string the CSS class name that will be assigned to the widget container element when the widget is updating its content via AJAX. CBaseListView
owner CBaseController Returns the owner/creator of this widget. CWidget
pager array|string the configuration for the pager. CBaseListView
pagerCssClass string the CSS class name for the pager container. CBaseListView
skin mixed the name of the skin to be used by this widget. CWidget
summaryCssClass string the CSS class name for the summary text container. CBaseListView
summaryTagName string the HTML tag name for the container of the summaryText property. CBaseListView
summaryText string the summary text template for the view. CBaseListView
tagName string the tag name for the view container. CBaseListView
template string the template to be used to control the layout of various sections in the view. CBaseListView
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 view. CBaseListView
raiseEvent() Raises an event. CComponent
registerClientScript() Registers necessary client scripts. CBaseListView
render() Renders a view. CWidget
renderContent() Renders the main content of the view. CBaseListView
renderEmptyText() Renders the empty message when there is no data. CBaseListView
renderFile() Renders a view file. CBaseController
renderInternal() Renders a view file. CBaseController
renderItems() Renders the data items for the view. CBaseListView
renderKeys() Renders the key values of the data in a hidden tag. CBaseListView
renderPager() Renders the pager. CBaseListView
renderSummary() Renders the summary text. CBaseListView
run() Renders the view. CBaseListView
setId() Sets the ID of the widget. CWidget
widget() Creates a widget and executes it. CBaseController

Protected Methods

Hide inherited methods

MethodDescriptionDefined By
renderSection() Renders a section. CBaseListView

Property Details

dataProvider property
public IDataProvider $dataProvider;

the data provider for the view.

emptyCssClass property (available since v1.1.16)
public string $emptyCssClass;

the CSS class name for the container of the emptyText property. Defaults to 'empty'.

emptyTagName property
public string $emptyTagName;

the HTML tag name for the container of the emptyText property.

emptyText property
public string $emptyText;

the message to be displayed when dataProvider does not have any data.

enablePagination property
public boolean $enablePagination;

whether to enable pagination. Note that if the IDataProvider::pagination property of dataProvider is false, this will be treated as false as well. When pagination is enabled, a pager will be displayed in the view so that it can trigger pagination of the data display. Defaults to true.

enableSorting property
public boolean $enableSorting;

whether to enable sorting. Note that if the IDataProvider::sort property of dataProvider is false, this will be treated as false as well. When sorting is enabled, sortable columns will have their headers clickable to trigger sorting along that column. Defaults to true.

See Also

  • sortableAttributes
htmlOptions property
public array $htmlOptions;

the HTML options for the view container tag.

itemsCssClass property
public string $itemsCssClass;

the CSS class name for the container of all data item display. Defaults to 'items'. Note, this property must not contain false, null or empty string values. Otherwise such values may cause undefined behavior.

loadingCssClass property (available since v1.1.1)
public string $loadingCssClass;

the CSS class name that will be assigned to the widget container element when the widget is updating its content via AJAX. Defaults to 'loading'.

pager property
public array|string $pager;

the configuration for the pager. Defaults to array('class'=>'CLinkPager'). String value will be treated as the class name of the pager ('ClassName' value is similar to the array('class'=>'ClassName') value). See CBasePager and CLinkPager for more details about pager configuration array values.

See Also

pagerCssClass property
public string $pagerCssClass;

the CSS class name for the pager container. Defaults to 'pager'. Note, this property must not contain false, null or empty string values. Otherwise such values may cause undefined behavior.

summaryCssClass property
public string $summaryCssClass;

the CSS class name for the summary text container. Defaults to 'summary'.

summaryTagName property (available since v1.1.16)
public string $summaryTagName;

the HTML tag name for the container of the summaryText property.

summaryText property
public string $summaryText;

the summary text template for the view. These tokens are recognized and will be replaced with the corresponding values:

  • {start}: the starting row number (1-based) currently being displayed
  • {end}: the ending row number (1-based) currently being displayed
  • {count}: the total number of rows
  • {page}: the page number (1-based) current being displayed, available since version 1.1.3
  • {pages}: the total number of pages, available since version 1.1.3
tagName property
public string $tagName;

the tag name for the view container. Defaults to 'div'.

template property
public string $template;

the template to be used to control the layout of various sections in the view. These tokens are recognized: {summary}, {items} and {pager}. They will be replaced with the summary text, the items, and the pager.

Method Details

init() method
public void init()
Source Code: framework/zii/widgets/CBaseListView.php#120 (show)
public function init()
{
    if($this->dataProvider===null)
        throw new CException(Yii::t('zii','The "dataProvider" property cannot be empty.'));

    $this->dataProvider->getData();

    if(isset($this->htmlOptions['id']))
        $this->id=$this->htmlOptions['id'];
    else
        $this->htmlOptions['id']=$this->id;

    if($this->enableSorting && $this->dataProvider->getSort()===false)
        $this->enableSorting=false;
    if($this->enablePagination && $this->dataProvider->getPagination()===false)
        $this->enablePagination=false;
}

Initializes the view. This method will initialize required property values and instantiate columns objects.

registerClientScript() method
public void registerClientScript()
Source Code: framework/zii/widgets/CBaseListView.php#297 (show)
public function registerClientScript()
{
}

Registers necessary client scripts. This method is invoked by run. Child classes may override this method to register customized client scripts.

renderContent() method
public void renderContent()
Source Code: framework/zii/widgets/CBaseListView.php#161 (show)
public function renderContent()
{
    ob_start();
    echo preg_replace_callback("/{(\w+)}/",array($this,'renderSection'),$this->template);
    ob_end_flush();
}

Renders the main content of the view. The content is divided into sections, such as summary, items, pager. Each section is rendered by a method named as "renderXyz", where "Xyz" is the section name. The rendering results will replace the corresponding placeholders in template.

renderEmptyText() method
public void renderEmptyText()
Source Code: framework/zii/widgets/CBaseListView.php#193 (show)
public function renderEmptyText()
{
    $emptyText=$this->emptyText===null ? Yii::t('zii','No results found.') : $this->emptyText;
    echo CHtml::tag($this->emptyTagName, array('class'=>$this->emptyCssClass), $emptyText);
}

Renders the empty message when there is no data.

renderItems() method
abstract public void renderItems()
Source Code: framework/zii/widgets/CBaseListView.php#306 (show)
abstract public function renderItems();

Renders the data items for the view. Each item is corresponding to a single data model instance. Child classes should override this method to provide the actual item rendering logic.

renderKeys() method
public void renderKeys()
Source Code: framework/zii/widgets/CBaseListView.php#202 (show)
public function renderKeys()
{
    echo CHtml::openTag('div',array(
        'class'=>'keys',
        'style'=>'display:none',
        'title'=>Yii::app()->getRequest()->getUrl(),
    ));
    foreach($this->dataProvider->getKeys() as $key)
        echo "<span>".CHtml::encode($key)."</span>";
    echo "</div>\n";
}

Renders the key values of the data in a hidden tag.

renderPager() method
public void renderPager()
Source Code: framework/zii/widgets/CBaseListView.php#262 (show)
public function renderPager()
{
    if(!$this->enablePagination)
        return;

    $pager=array();
    $class='CLinkPager';
    if(is_string($this->pager))
        $class=$this->pager;
    elseif(is_array($this->pager))
    {
        $pager=$this->pager;
        if(isset($pager['class']))
        {
            $class=$pager['class'];
            unset($pager['class']);
        }
    }
    $pager['pages']=$this->dataProvider->getPagination();

    if($pager['pages']->getPageCount()>1)
    {
        echo '<div class="'.$this->pagerCssClass.'">';
        $this->widget($class,$pager);
        echo '</div>';
    }
    else
        $this->widget($class,$pager);
}

Renders the pager.

renderSection() method
protected string renderSection(array $matches)
$matches array the matches, where $matches[0] represents the whole placeholder, while $matches[1] contains the name of the matched placeholder.
{return} string the rendering result of the section
Source Code: framework/zii/widgets/CBaseListView.php#176 (show)
protected function renderSection($matches)
{
    $method='render'.$matches[1];
    if(method_exists($this,$method))
    {
        $this->$method();
        $html=ob_get_contents();
        ob_clean();
        return $html;
    }
    else
        return $matches[0];
}

Renders a section. This method is invoked by renderContent for every placeholder found in template. It should return the rendering result that would replace the placeholder.

renderSummary() method
public void renderSummary()
Source Code: framework/zii/widgets/CBaseListView.php#217 (show)
public function renderSummary()
{
    if(($count=$this->dataProvider->getItemCount())<=0)
        return;

    echo CHtml::openTag($this->summaryTagName, array('class'=>$this->summaryCssClass));
    if($this->enablePagination)
    {
        $pagination=$this->dataProvider->getPagination();
        $total=$this->dataProvider->getTotalItemCount();
        $start=$pagination->currentPage*$pagination->pageSize+1;
        $end=$start+$count-1;
        if($end>$total)
        {
            $end=$total;
            $start=$end-$count+1;
        }
        if(($summaryText=$this->summaryText)===null)
            $summaryText=Yii::t('zii','Displaying {start}-{end} of 1 result.|Displaying {start}-{end} of {count} results.',$total);
        echo strtr($summaryText,array(
            '{start}'=>$start,
            '{end}'=>$end,
            '{count}'=>$total,
            '{page}'=>$pagination->currentPage+1,
            '{pages}'=>$pagination->pageCount,
        ));
    }
    else
    {
        if(($summaryText=$this->summaryText)===null)
            $summaryText=Yii::t('zii','Total 1 result.|Total {count} results.',$count);
        echo strtr($summaryText,array(
            '{count}'=>$count,
            '{start}'=>1,
            '{end}'=>$count,
            '{page}'=>1,
            '{pages}'=>1,
        ));
    }
    echo CHtml::closeTag($this->summaryTagName);
}

Renders the summary text.

run() method
public void run()
Source Code: framework/zii/widgets/CBaseListView.php#143 (show)
public function run()
{
    $this->registerClientScript();

    echo CHtml::openTag($this->tagName,$this->htmlOptions)."\n";

    $this->renderContent();
    $this->renderKeys();

    echo CHtml::closeTag($this->tagName);
}

Renders the view. This is the main entry of the whole view rendering. Child classes should mainly override renderContent method.