CGridView

$dataProvider=new CActiveDataProvider('Post');

$this->widget('zii.widgets.grid.CGridView', array(
    'dataProvider'=>$dataProvider,
));

$this->widget('zii.widgets.grid.CGridView', array(
    'dataProvider'=>$dataProvider,
    'columns'=>array(
        'title',          // display the 'title' attribute
        'category.name',  // display the 'name' attribute of the 'category' relation
        'content:html',   // display the 'content' attribute as purified HTML
        array(            // display 'create_time' using an expression
            'name'=>'create_time',
            'value'=>'date("M j, Y", $data->create_time)',
        ),
        array(            // display 'author.username' using an expression
            'name'=>'authorName',
            'value'=>'$data->author->username',
        ),
        array(            // display a column with "view", "update" and "delete" buttons
            'class'=>'CButtonColumn',
        ),
    ),
));

Property Details

afterAjaxUpdate property

public string $afterAjaxUpdate;

a javascript function that will be invoked after a successful AJAX response is received. The function signature is function(id, data) where 'id' refers to the ID of the grid view, 'data' the received ajax response data.

ajaxType property (available since v1.1.14)

public string $ajaxType;

the type ('GET' or 'POST') of the AJAX requests. If not set, 'GET' will be used. You can set this to 'POST' if you are filtering by many fields at once and have a problem with GET query string length. Note that in POST mode direct links and enableHistory feature may not work correctly!

ajaxUpdate property

public mixed $ajaxUpdate;

the ID of the container whose content may be updated with an AJAX response. Defaults to null, meaning the container for this grid view instance. If it is set false, it means sorting and pagination will be performed in normal page requests instead of AJAX requests. If the sorting and pagination should trigger the update of multiple containers' content in AJAX fashion, these container IDs may be listed here (separated with comma).

ajaxUpdateError property

public string $ajaxUpdateError;

a javascript function that will be invoked if an AJAX update error occurs.

The function signature is function(xhr, textStatus, errorThrown, errorMessage)

• xhr is the XMLHttpRequest object.
• textStatus is a string describing the type of error that occurred. Possible values (besides null) are "timeout", "error", "notmodified" and "parsererror"
• errorThrown is an optional exception object, if one occurred.
• errorMessage is the CGridView default error message derived from xhr and errorThrown. Useful if you just want to display this error differently. CGridView by default displays this error with an javascript.alert()

 ...
 'ajaxUpdateError'=>'function(xhr,ts,et,err,id){ $("#"+id).text(err); }',
 ...

ajaxUrl property (available since v1.1.8)

public mixed $ajaxUrl;

the URL for the AJAX requests should be sent to. CHtml::normalizeUrl() will be called on this property. If not set, the current page URL will be used for AJAX requests.

ajaxVar property

public string $ajaxVar;

the name of the GET variable that indicates the request is an AJAX request triggered by this widget. Defaults to 'ajax'. This is effective only when ajaxUpdate is not false.

baseScriptUrl property

public string $baseScriptUrl;

the base script URL for all grid view resources (eg javascript, CSS file, images). Defaults to null, meaning using the integrated grid view resources (which are published as assets).

beforeAjaxUpdate property

public string $beforeAjaxUpdate;

a javascript function that will be invoked before an AJAX update occurs. The function signature is function(id,options) where 'id' refers to the ID of the grid view, 'options' the AJAX request options (see jQuery.ajax api manual).

blankDisplay property (available since v1.1.7)

public string $blankDisplay;

the text to be displayed in an empty grid cell. This property will NOT be HTML-encoded when rendering. Defaults to an HTML blank. This differs from nullDisplay in that nullDisplay is only used by CDataColumn to render null data values.

columns property

public array $columns;

grid column configuration. Each array element represents the configuration for one particular grid column which can be either a string or an array.

When a column is specified as a string, it should be in the format of "name:type:header", where "type" and "header" are optional. A CDataColumn instance will be created in this case, whose CDataColumn::name, CDataColumn::type and CDataColumn::header properties will be initialized accordingly.

When a column is specified as an array, it will be used to create a grid column instance, where the 'class' element specifies the column class name (defaults to CDataColumn if absent). Currently, these official column classes are provided: CDataColumn, CLinkColumn, CButtonColumn and CCheckBoxColumn.

cssFile property

public string $cssFile;

the URL of the CSS file used by this grid view. Defaults to null, meaning using the integrated CSS file. If this is set false, you are responsible to explicitly include the necessary CSS file in your page.

enableHistory property (available since v1.1.11)

public boolean $enableHistory;

whether to leverage the DOM history object. Set this property to true to persist state of grid across page revisits. Note, there are two limitations for this feature:

• this feature is only compatible with browsers that support HTML5.
• expect unexpected functionality (e.g. multiple ajax calls) if there is more than one grid/list on a single page with enableHistory turned on.

filter property (available since v1.1.1)

public CModel $filter;

the model instance that keeps the user-entered filter data. When this property is set, the grid view will enable column-based filtering. Each data column by default will display a text field at the top that users can fill in to filter the data. Note that in order to show an input field for filtering, a column must have its CDataColumn::name property set or have CDataColumn::filter as the HTML code for the input field. When this property is not set (null) the filtering is disabled.

filterCssClass property (available since v1.1.1)

public string $filterCssClass;

the CSS class name for the table row element containing all filter input fields. Defaults to 'filters'.

filterPosition property (available since v1.1.1)

public string $filterPosition;

whether the filters should be displayed in the grid view. Valid values include:

• header: the filters will be displayed on top of each column's header cell.
• body: the filters will be displayed right below each column's header cell.
• footer: the filters will be displayed below each column's footer cell.

filterSelector property (available since v1.1.13)

public string $filterSelector;

the jQuery selector of filter input fields. The token '{filter}' is recognized and it will be replaced with the grid filters selector. Defaults to '{filter}'.

Note: if this value is empty an exception will be thrown.

Example (adding a custom selector to the default one):

 ...
 'filterSelector'=>'{filter}, #myfilter',
 ...

formatter property

public CFormatter getFormatter()
public void setFormatter(CFormatter $value)

the formatter instance. Defaults to the 'format' application component.

hasFooter property read-only

public boolean getHasFooter()

whether the table should render a footer. This is true if any of the columns has a true CGridColumn::hasFooter value.

hideHeader property (available since v1.1.1)

public boolean $hideHeader;

whether to hide the header cells of the grid. When this is true, header cells will not be rendered, which means the grid cannot be sorted anymore since the sort links are located in the header. Defaults to false.

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 'grid-view-loading'.

nullDisplay property

public string $nullDisplay;

the text to be displayed in a data cell when a data value is null. This property will NOT be HTML-encoded when rendering. Defaults to an HTML blank.

rowCssClass property

public array $rowCssClass;

the CSS class names for the table body rows. If multiple CSS class names are given, they will be assigned to the rows sequentially and repeatedly. This property is ignored if rowCssClassExpression is set. Defaults to array('odd', 'even').

rowCssClassExpression property

public string $rowCssClassExpression;

a PHP expression that is evaluated for every table body row and whose result is used as the CSS class name for the row. In this expression, you can use the following variables:

• $row the row number (zero-based)
• $data the data model for the row
• $this the grid view object

rowHtmlOptionsExpression property (available since v1.1.13)

public string $rowHtmlOptionsExpression;

a PHP expression that is evaluated for every table body row and whose result is used as additional HTML attributes for the row. The expression should return an array whose key value pairs correspond to html attribute and value. In this expression, you can use the following variables:

• $row the row number (zero-based)
• $data the data model for the row
• $this the grid view object

selectableRows property

public integer $selectableRows;

the number of table body rows that can be selected. If 0, it means rows cannot be selected. If 1, only one row can be selected. If 2 or any other number, it means multiple rows can be selected. A selected row will have a CSS class named 'selected'. You may also call the JavaScript function $(gridID).yiiGridView('getSelection') to retrieve the key values of the currently selected rows (gridID is the DOM selector of the grid).

selectionChanged property

public string $selectionChanged;

a javascript function that will be invoked after the row selection is changed. The function signature is function(id) where 'id' refers to the ID of the grid view. In this function, you may use $(gridID).yiiGridView('getSelection') to get the key values of the currently selected rows (gridID is the DOM selector of the grid).

showTableOnEmpty property

public boolean $showTableOnEmpty;

whether to display the table even when there is no data. Defaults to true. The emptyText will be displayed to indicate there is no data.

updateSelector property (available since v1.1.7)

public string $updateSelector;

the jQuery selector of the HTML elements that may trigger AJAX updates when they are clicked. These tokens are recognized: {page} and {sort}. They will be replaced with the pagination and sorting links selectors. Defaults to '{page}, {sort}', that means that the pagination links and the sorting links will trigger AJAX updates. Tokens are available from 1.1.11

Note: if this value is empty an exception will be thrown.

Example (adding a custom selector to the default ones):

 ...
 'updateSelector'=>'{page}, {sort}, #mybutton',
 ...

Method Details

createDataColumn() method

protected CDataColumn createDataColumn(string $text)

protected function createDataColumn($text)
{
    if(!preg_match('/^([\w\.]+)(:(\w*))?(:(.*))?$/',$text,$matches))
        throw new CException(Yii::t('zii','The column must be specified in the format of "Name:Type:Label", where "Type" and "Label" are optional.'));
    $column=new CDataColumn($this);
    $column->name=$matches[1];
    if(isset($matches[3]) && $matches[3]!=='')
        $column->type=$matches[3];
    if(isset($matches[5]))
        $column->header=$matches[5];
    return $column;
}

Creates a CDataColumn based on a shortcut column specification string.

getFormatter() method

public CFormatter getFormatter()

public function getFormatter()
{
    if($this->_formatter===null)
        $this->_formatter=Yii::app()->format;
    return $this->_formatter;
}

getHasFooter() method

public boolean getHasFooter()

public function getHasFooter()
{
    foreach($this->columns as $column)
        if($column->getHasFooter())
            return true;
    return false;
}

init() method

public void init()

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

    if(empty($this->updateSelector))
        throw new CException(Yii::t('zii','The property updateSelector should be defined.'));
    if(empty($this->filterSelector))
        throw new CException(Yii::t('zii','The property filterSelector should be defined.'));

    if(!isset($this->htmlOptions['class']))
        $this->htmlOptions['class']='grid-view';

    if($this->baseScriptUrl===null)
        $this->baseScriptUrl=Yii::app()->getAssetManager()->publish(Yii::getPathOfAlias('zii.widgets.assets')).'/gridview';

    if($this->cssFile!==false)
    {
        if($this->cssFile===null)
            $this->cssFile=$this->baseScriptUrl.'/styles.css';
        Yii::app()->getClientScript()->registerCssFile($this->cssFile);
    }

    $this->initColumns();
}

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

initColumns() method

protected void initColumns()

protected function initColumns()
{
    if($this->columns===array())
    {
        if($this->dataProvider instanceof CActiveDataProvider)
            $this->columns=$this->dataProvider->model->attributeNames();
        elseif($this->dataProvider instanceof IDataProvider)
        {
            // use the keys of the first row of data as the default columns
            $data=$this->dataProvider->getData();
            if(isset($data[0]) && is_array($data[0]))
                $this->columns=array_keys($data[0]);
        }
    }
    $id=$this->getId();
    foreach($this->columns as $i=>$column)
    {
        if(is_string($column))
            $column=$this->createDataColumn($column);
        else
        {
            if(!isset($column['class']))
                $column['class']='CDataColumn';
            $column=Yii::createComponent($column, $this);
        }
        if(!$column->visible)
        {
            unset($this->columns[$i]);
            continue;
        }
        if($column->id===null)
            $column->id=$id.'_c'.$i;
        $this->columns[$i]=$column;
    }

    foreach($this->columns as $column)
        $column->init();
}

Creates column objects and initializes them.

registerClientScript() method

public void registerClientScript()

public function registerClientScript()
{
    $id=$this->getId();

    if($this->ajaxUpdate===false)
        $ajaxUpdate=false;
    else
        $ajaxUpdate=array_unique(preg_split('/\s*,\s*/',$this->ajaxUpdate.','.$id,-1,PREG_SPLIT_NO_EMPTY));
    $options=array(
        'ajaxUpdate'=>$ajaxUpdate,
        'ajaxVar'=>$this->ajaxVar,
        'pagerClass'=>$this->pagerCssClass,
        'loadingClass'=>$this->loadingCssClass,
        'filterClass'=>$this->filterCssClass,
        'tableClass'=>$this->itemsCssClass,
        'selectableRows'=>$this->selectableRows,
        'enableHistory'=>$this->enableHistory,
        'updateSelector'=>$this->updateSelector,
        'filterSelector'=>$this->filterSelector
    );
    if($this->ajaxUrl!==null)
        $options['url']=CHtml::normalizeUrl($this->ajaxUrl);
    if($this->ajaxType!==null) {
        $options['ajaxType']=strtoupper($this->ajaxType);
        $request=Yii::app()->getRequest();
        if ($options['ajaxType']=='POST' && $request->enableCsrfValidation) {
            $options['csrfTokenName']=$request->csrfTokenName;
            $options['csrfToken']=$request->getCsrfToken();
        }
    }
    if($this->enablePagination)
        $options['pageVar']=$this->dataProvider->getPagination()->pageVar;
    foreach(array('beforeAjaxUpdate', 'afterAjaxUpdate', 'ajaxUpdateError', 'selectionChanged') as $event)
    {
        if($this->$event!==null)
        {
            if($this->$event instanceof CJavaScriptExpression)
                $options[$event]=$this->$event;
            else
                $options[$event]=new CJavaScriptExpression($this->$event);
        }
    }

    $options=CJavaScript::encode($options);
    $cs=Yii::app()->getClientScript();
    $cs->registerCoreScript('jquery');
    $cs->registerCoreScript('bbq');
    if($this->enableHistory)
        $cs->registerCoreScript('history');
    $cs->registerScriptFile($this->baseScriptUrl.'/jquery.yiigridview.js',CClientScript::POS_END);
    $cs->registerScript(__CLASS__.'#'.$id,"jQuery('#$id').yiiGridView($options);");
}

Registers necessary client scripts.

renderDataCell() method (available since v1.1.16)

protected void renderDataCell(CGridColumn $column, integer $row)

protected function renderDataCell($column, $row)
{
    $column->renderDataCell($row);
}

A seam for people extending CGridView to be able to hook onto the data cell rendering process.

By overriding only this method we will not need to copypaste and modify the whole entirety of `renderTableRow`. Or override `renderDataCell()` method of all possible CGridColumn descendants.

renderFilter() method (available since v1.1.1)

public void renderFilter()

public function renderFilter()
{
    if($this->filter!==null)
    {
        echo "<tr class=\"{$this->filterCssClass}\">\n";
        foreach($this->columns as $column)
            $column->renderFilterCell();
        echo "</tr>\n";
    }
}

Renders the filter.

renderItems() method

public void renderItems()

public function renderItems()
{
    if($this->dataProvider->getItemCount()>0 || $this->showTableOnEmpty)
    {
        echo "<table class=\"{$this->itemsCssClass}\">\n";
        $this->renderTableHeader();
        ob_start();
        $this->renderTableBody();
        $body=ob_get_clean();
        $this->renderTableFooter();
        echo $body; // TFOOT must appear before TBODY according to the standard.
        echo "</table>";
    }
    else
        $this->renderEmptyText();
}

Renders the data items for the grid view.

renderTableBody() method

public void renderTableBody()

public function renderTableBody()
{
    $data=$this->dataProvider->getData();
    $n=count($data);
    echo "<tbody>\n";

    if($n>0)
    {
        for($row=0;$row<$n;++$row)
            $this->renderTableRow($row);
    }
    else
    {
        echo '<tr><td colspan="'.count($this->columns).'" class="empty">';
        $this->renderEmptyText();
        echo "</td></tr>\n";
    }
    echo "</tbody>\n";
}

Renders the table body.

renderTableFooter() method

public void renderTableFooter()

public function renderTableFooter()
{
    $hasFilter=$this->filter!==null && $this->filterPosition===self::FILTER_POS_FOOTER;
    $hasFooter=$this->getHasFooter();
    if($hasFilter || $hasFooter)
    {
        echo "<tfoot>\n";
        if($hasFooter)
        {
            echo "<tr>\n";
            foreach($this->columns as $column)
                $column->renderFooterCell();
            echo "</tr>\n";
        }
        if($hasFilter)
            $this->renderFilter();
        echo "</tfoot>\n";
    }
}

Renders the table footer.

renderTableHeader() method

public void renderTableHeader()

public function renderTableHeader()
{
    if(!$this->hideHeader)
    {
        echo "<thead>\n";

        if($this->filterPosition===self::FILTER_POS_HEADER)
            $this->renderFilter();

        echo "<tr>\n";
        foreach($this->columns as $column)
            $column->renderHeaderCell();
        echo "</tr>\n";

        if($this->filterPosition===self::FILTER_POS_BODY)
            $this->renderFilter();

        echo "</thead>\n";
    }
    elseif($this->filter!==null && ($this->filterPosition===self::FILTER_POS_HEADER || $this->filterPosition===self::FILTER_POS_BODY))
    {
        echo "<thead>\n";
        $this->renderFilter();
        echo "</thead>\n";
    }
}

Renders the table header.

renderTableRow() method

public void renderTableRow(integer $row)

public function renderTableRow($row)
{
    $htmlOptions=array();
    if($this->rowHtmlOptionsExpression!==null)
    {
        $data=$this->dataProvider->data[$row];
        $options=$this->evaluateExpression($this->rowHtmlOptionsExpression,array('row'=>$row,'data'=>$data));
        if(is_array($options))
            $htmlOptions = $options;
    }

    if($this->rowCssClassExpression!==null)
    {
        $data=$this->dataProvider->data[$row];
        $class=$this->evaluateExpression($this->rowCssClassExpression,array('row'=>$row,'data'=>$data));
    }
    elseif(is_array($this->rowCssClass) && ($n=count($this->rowCssClass))>0)
        $class=$this->rowCssClass[$row%$n];

    if(!empty($class))
    {
        if(isset($htmlOptions['class']))
            $htmlOptions['class'].=' '.$class;
        else
            $htmlOptions['class']=$class;
    }

    echo CHtml::openTag('tr', $htmlOptions)."\n";
    foreach($this->columns as $column)
        $this->renderDataCell($column, $row);
    echo "</tr>\n";
}

Renders a table body row.

setFormatter() method

public void setFormatter(CFormatter $value)

public function setFormatter($value)
{
    $this->_formatter=$value;
}