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.

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.

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()

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()

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()

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()

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()

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()

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()

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)

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()

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()

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.