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

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.

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!

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

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); }',
 ...

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.

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.

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

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

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.

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.

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.

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.

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.

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

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.

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',
 ...

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

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

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.

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'.

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.

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').

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 value provided by grid view object for the row.
• $this the grid view object.

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 value provided by grid view object for the row.
• $this the grid view object.

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

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

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.

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

Creates a CDataColumn based on a shortcut column specification string.

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

Creates column objects and initializes them.

Registers necessary client scripts.

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.

Renders the filter.

Renders the data items for the grid view.

Renders the table body.

Renders the table footer.

Renders the table header.

Renders a table body row.