Class CListView

CListView displays a list of data items in terms of a list.

Unlike CGridView which displays the data items in a table, CListView allows one to use a view template to render each data item. As a result, CListView could generate more flexible rendering result.

CListView supports both sorting and pagination of the data items. The sorting and pagination can be done in AJAX mode or normal page request. A benefit of using CListView is that when the user browser disables JavaScript, the sorting and pagination automatically degenerate to normal page requests and are still functioning as expected.

CListView should be used together with a IDataProvider data provider, preferably a CActiveDataProvider.

The minimal code needed to use CListView is as follows:

$dataProvider=new CActiveDataProvider('Post');

$this->widget('zii.widgets.CListView', array(
    'dataProvider'=>$dataProvider,
    'itemView'=>'_post',   // refers to the partial view named '_post'
    'sortableAttributes'=>array(
        'title',
        'create_time'=>'Post Time',
    ),
));

The above code first creates a data provider for the Post ActiveRecord class. It then uses CListView to display every data item as returned by the data provider. The display is done via the partial view named '_post'. This partial view will be rendered once for every data item. In the view, one can access the current data item via variable <span class="php-var">$data</span>. For more details, see CListView::$itemView.

In order to support sorting, one has to specify the CListView::$sortableAttributes property. By doing so, a list of hyperlinks that can sort the data will be displayed.

CComponent

CBaseController

CWidget

CBaseListView

CListView

Direct known subclasses

RecordIndexListView, TopicsListView, X2ListView

Indirect known subclasses

MobileActivityFeedListView

Package: zii\widgets
Copyright: 2008-2013 Yii Software LLC
License: http://www.yiiframework.com/license/
Author: Qiang Xue <qiang.xue@gmail.com>
Since: 1.1
Located at x2engine/framework/zii/widgets/CListView.php

Methods summary
`public`	# `init( )` Initializes the list view. This method will initialize required property values and instantiate columns objects. Initializes the list view. This method will initialize required property values and instantiate columns objects. Overrides `CBaseListView::init()`
`public`	# `registerClientScript( )` Registers necessary client scripts. Registers necessary client scripts. Overrides `CBaseListView::registerClientScript()`
`public`	# `renderItems( )` Renders the data item list. Renders the data item list.
`public`	# `renderSorter( )` Renders the sorter. Renders the sorter.

Methods inherited from CBaseListView
`renderContent(), renderEmptyText(), renderKeys(), renderPager(), renderSection(), renderSummary(), run()`

Methods inherited from CWidget
`__construct(), actions(), getController(), getId(), getOwner(), getViewFile(), getViewPath(), render(), setId()`

Methods inherited from CBaseController
`beginCache(), beginClip(), beginContent(), beginWidget(), createWidget(), endCache(), endClip(), endContent(), endWidget(), renderFile(), renderInternal(), widget()`

Methods inherited from CComponent
`__call(), __get(), __isset(), __set(), __unset(), asa(), attachBehavior(), attachBehaviors(), attachEventHandler(), canGetProperty(), canSetProperty(), detachBehavior(), detachBehaviors(), detachEventHandler(), disableBehavior(), disableBehaviors(), enableBehavior(), enableBehaviors(), evaluateExpression(), getEventHandlers(), hasEvent(), hasEventHandler(), hasProperty(), raiseEvent()`

Properties summary
`public string`	`$itemView`		# the view used for rendering each data item. This property value will be passed as the first parameter to either `CController::renderPartial()` or `CWidget::render()` to render each data item. In the corresponding view template, the following variables can be used in addition to those declared in `CListView::$viewData`: `<span class="php-var">$this</span>`: refers to the owner of this list view widget. For example, if the widget is in the view of a controller, then `<span class="php-var">$this</span>` refers to the controller. `<span class="php-var">$data</span>`: refers to the data item currently being rendered. `<span class="php-var">$index</span>`: refers to the zero-based index of the data item currently being rendered. `<span class="php-var">$widget</span>`: refers to this list view widget instance. the view used for rendering each data item. This property value will be passed as the first parameter to either `CController::renderPartial()` or `CWidget::render()` to render each data item. In the corresponding view template, the following variables can be used in addition to those declared in `CListView::$viewData`: `<span class="php-var">$this</span>`: refers to the owner of this list view widget. For example, if the widget is in the view of a controller, then `<span class="php-var">$this</span>` refers to the controller. `<span class="php-var">$data</span>`: refers to the data item currently being rendered. `<span class="php-var">$index</span>`: refers to the zero-based index of the data item currently being rendered. `<span class="php-var">$widget</span>`: refers to this list view widget instance.
`public string`	`$separator`		# the HTML code to be displayed between any two consecutive items. the HTML code to be displayed between any two consecutive items. Since 1.1.7
`public array`	`$viewData`	`array()`	# additional data to be passed to `CListView::$itemView` when rendering each data item. This array will be extracted into local PHP variables that can be accessed in the `CListView::$itemView`. additional data to be passed to `CListView::$itemView` when rendering each data item. This array will be extracted into local PHP variables that can be accessed in the `CListView::$itemView`.
`public array`	`$sortableAttributes`		# list of sortable attribute names. In order for an attribute to be sortable, it must also appear as a sortable attribute in the IDataProvider::sort property of `CBaseListView::$dataProvider`. list of sortable attribute names. In order for an attribute to be sortable, it must also appear as a sortable attribute in the IDataProvider::sort property of `CBaseListView::$dataProvider`. See `CBaseListView::$enableSorting`
`public string`	`$template`	`"{summary}\n{sorter}\n{items}\n{pager}"`	# the template to be used to control the layout of various components in the list view. These tokens are recognized: {summary}, {sorter}, {items} and {pager}. They will be replaced with the summary text, the sort links, the data item list, and the pager. the template to be used to control the layout of various components in the list view. These tokens are recognized: {summary}, {sorter}, {items} and {pager}. They will be replaced with the summary text, the sort links, the data item list, and the pager.
`public string`	`$loadingCssClass`	`'list-view-loading'`	# the CSS class name that will be assigned to the widget container element when the widget is updating its content via AJAX. Defaults to 'list-view-loading'. the CSS class name that will be assigned to the widget container element when the widget is updating its content via AJAX. Defaults to 'list-view-loading'. Since 1.1.1
`public string`	`$sorterCssClass`	`'sorter'`	# the CSS class name for the sorter container. Defaults to 'sorter'. the CSS class name for the sorter container. Defaults to 'sorter'.
`public string`	`$sorterHeader`		# the text shown before sort links. Defaults to 'Sort by: '. the text shown before sort links. Defaults to 'Sort by: '.
`public string`	`$sorterFooter`	`''`	# the text shown after sort links. Defaults to empty. the text shown after sort links. Defaults to empty.
`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 list 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). the ID of the container whose content may be updated with an AJAX response. Defaults to null, meaning the container for this list 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).
`public string`	`$updateSelector`		# the jQuery selector of the HTML elements that may trigger AJAX updates when they are clicked. If not set, the pagination links and the sorting links will trigger AJAX updates. the jQuery selector of the HTML elements that may trigger AJAX updates when they are clicked. If not set, the pagination links and the sorting links will trigger AJAX updates. Since 1.1.7
`public string`	`$ajaxUpdateError`		# a javascript function that will be invoked if an AJAX update error occurs. The function signature is `<span class="php-keyword1">function</span>(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. Usefull if you just want to display this error differently. CGridView by default displays this error with an javascript.alert() Note: This handler is not called for JSONP requests, because they do not use an XMLHttpRequest. Example (add in a call to CGridView): ... 'ajaxUpdateError'=>'function(xhr,ts,et,err,id){ $("#"+id).text(err); }', ... a javascript function that will be invoked if an AJAX update error occurs. The function signature is `<span class="php-keyword1">function</span>(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. Usefull if you just want to display this error differently. CGridView by default displays this error with an javascript.alert() Note: This handler is not called for JSONP requests, because they do not use an XMLHttpRequest. Example (add in a call to CGridView): ... 'ajaxUpdateError'=>'function(xhr,ts,et,err,id){ $("#"+id).text(err); }', ... Since 1.1.13
`public string`	`$ajaxVar`	`'ajax'`	# 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 `CListView::$ajaxUpdate` is not false. 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 `CListView::$ajaxUpdate` is not false.
`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. 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. Since 1.1.8
`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 `CListView::$enableHistory` feature may not work correctly! 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 `CListView::$enableHistory` feature may not work correctly! Since 1.1.14
`public string`	`$beforeAjaxUpdate`		# a javascript function that will be invoked before an AJAX update occurs. The function signature is `<span class="php-keyword1">function</span>(id)` where 'id' refers to the ID of the list view. a javascript function that will be invoked before an AJAX update occurs. The function signature is `<span class="php-keyword1">function</span>(id)` where 'id' refers to the ID of the list view.
`public string`	`$afterAjaxUpdate`		# a javascript function that will be invoked after a successful AJAX response is received. The function signature is `<span class="php-keyword1">function</span>(id, data)` where 'id' refers to the ID of the list view 'data' the received ajax response data. a javascript function that will be invoked after a successful AJAX response is received. The function signature is `<span class="php-keyword1">function</span>(id, data)` where 'id' refers to the ID of the list view 'data' the received ajax response data.
`public string`	`$baseScriptUrl`		# the base script URL for all list view resources (e.g. javascript, CSS file, images). Defaults to null, meaning using the integrated list view resources (which are published as assets). the base script URL for all list view resources (e.g. javascript, CSS file, images). Defaults to null, meaning using the integrated list view resources (which are published as assets).
`public string`	`$cssFile`		# the URL of the CSS file used by this list 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. the URL of the CSS file used by this list 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.
`public string`	`$itemsTagName`	`'div'`	# the HTML tag name for the container of all data item display. Defaults to 'div'. the HTML tag name for the container of all data item display. Defaults to 'div'. Since 1.1.4
`public boolean`	`$enableHistory`	`false`	# whether to leverage the DOM history object. Set this property to true to persist state of list 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. whether to leverage the DOM history object. Set this property to true to persist state of list 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. Since 1.1.11

Properties inherited from CBaseListView
`$dataProvider, $emptyCssClass, $emptyTagName, $emptyText, $enablePagination, $enableSorting, $htmlOptions, $itemsCssClass, $pager, $pagerCssClass, $summaryCssClass, $summaryTagName, $summaryText, $tagName`

Properties inherited from CWidget
`$actionPrefix, $skin`

Magic properties inherited from CWidget
`$controller, $id, $owner, $viewPath`

Packages

Classes

Class CListView

Direct known subclasses

Indirect known subclasses

Overrides

Overrides

Since

See

Since

Since

Since

Since

Since

Since

Since