3
* CListView class file.
5
* @author Qiang Xue <qiang.xue@gmail.com>
6
* @link http://www.yiiframework.com/
7
* @copyright Copyright © 2008-2010 Yii Software LLC
8
* @license http://www.yiiframework.com/license/
11
Yii::import('zii.widgets.CBaseListView');
14
* CListView displays a list of data items in terms of a list.
16
* Unlike {@link CGridView} which displays the data items in a table, CListView allows one to use
17
* a view template to render each data item. As a result, CListView could generate more flexible
20
* CListView supports both sorting and pagination of the data items. The sorting
21
* and pagination can be done in AJAX mode or normal page request. A benefit of using CListView is that
22
* when the user browser disables JavaScript, the sorting and pagination automatically degenerate
23
* to normal page requests and are still functioning as expected.
25
* CListView should be used together with a {@link IDataProvider data provider}, preferrably a
26
* {@link CActiveDataProvider}.
28
* The minimal code needed to use CListView is as follows:
31
* $dataProvider=new CActiveDataProvider('Post');
33
* $this->widget('zii.widgets.CListView', array(
34
* 'dataProvider'=>$dataProvider,
35
* 'itemView'=>'_post', // refers to the partial view named '_post'
36
* 'sortableAttributes'=>array(
38
* 'create_time'=>'Post Time',
43
* The above code first creates a data provider for the <code>Post</code> ActiveRecord class.
44
* It then uses CListView to display every data item as returned by the data provider.
45
* The display is done via the partial view named '_post'. This partial view will be rendered
46
* once for every data item. In the view, one can access the current data item via variable <code>$data</code>.
47
* For more details, see {@link itemView}.
49
* In order to support sorting, one has to specify the {@link sortableAttributes} property.
50
* By doing so, a list of hyperlinks that can sort the data will be displayed.
52
* @author Qiang Xue <qiang.xue@gmail.com>
53
* @version $Id: CListView.php 99 2010-01-07 20:55:13Z qiang.xue $
54
* @package zii.widgets
57
class CListView extends CBaseListView
60
* @var string the view used for rendering each data item.
61
* This property value will be passed as the first parameter to either {@link CController::renderPartial}
62
* or {@link CWidget::render} to render each data item.
63
* In the corresponding view template, the following variables can be used in addition to those declared in {@link viewData}:
65
* <li><code>$this</code>: refers to the owner of this list view widget. For example, if the widget is in the view of a controller,
66
* then <code>$this</code> refers to the controller.</li>
67
* <li><code>$data</code>: refers to the data item currently being rendered.</li>
68
* <li><code>$index</code>: refers to the zero-based index of the data item currently being rendered.</li>
69
* <li><code>$widget</code>: refers to this list view widget instance.</li>
74
* @var array additional data to be passed to {@link itemView} when rendering each data item.
75
* This array will be extracted into local PHP variables that can be accessed in the {@link itemView}.
77
public $viewData=array();
79
* @var array list of sortable attribute names. In order for an attribute to be sortable, it must also
80
* appear as as a sortable attribute the {@link IDataProvider::sort} property of {@link dataProvider}.
83
public $sortableAttributes;
85
* @var string the template to be used to control the layout of various components in the list view.
86
* These tokens are recognized: {summary}, {sorter}, {items} and {pager}. They will be replaced with the
87
* summary text, the sort links, the data item list, and the pager.
89
public $template="{summary}\n{sorter}\n{items}\n{pager}";
91
* @var string the CSS class name for the sorter container. Defaults to 'sorter'.
93
public $sorterCssClass='sorter';
95
* @var string the text shown before sort links. Defaults to 'Sort by: '.
99
* @var string the text shown after sort links. Defaults to empty.
101
public $sorterFooter='';
103
* @var mixed the ID of the container whose content may be updated with an AJAX response.
104
* Defaults to null, meaning the container for this list view instance.
105
* If it is set false, it means sorting and pagination will be performed in normal page requests
106
* instead of AJAX requests. If the sorting and pagination should trigger the update of multiple
107
* containers' content in AJAX fashion, these container IDs may be listed here (separated with comma).
111
* @var string the name of the GET variable that indicates the request is an AJAX request triggered
112
* by this widget. Defaults to 'ajax'. This is effective only when {@link ajaxUpdate} is not false.
114
public $ajaxVar='ajax';
116
* @var string a javascript function that will be invoked before an AJAX update occurs.
117
* The function signature is <code>function(id)</code> where 'id' refers to the ID of the list view.
119
public $beforeAjaxUpdate;
121
* @var string a javascript function that will be invoked after a successful AJAX response is received.
122
* The function signature is <code>function(id, data)</code> where 'id' refers to the ID of the list view
123
* 'data' the received ajax response data.
125
public $afterAjaxUpdate;
127
* @var string the base script URL for all list view resources (e.g. javascript, CSS file, images).
128
* Defaults to null, meaning using the integrated list view resources (which are published as assets).
130
public $baseScriptUrl;
132
* @var string the URL of the CSS file used by this list view. Defaults to null, meaning using the integrated
133
* CSS file. If this is set false, you are responsible to explicitly include the necessary CSS file in your page.
138
* Initializes the list view.
139
* This method will initialize required property values and instantiate {@link columns} objects.
141
public function init()
143
if($this->itemView===null)
144
throw new CException(Yii::t('zii','The property "itemView" cannot be empty.'));
147
if(!isset($this->htmlOptions['class']))
148
$this->htmlOptions['class']='list-view';
150
if($this->baseScriptUrl===null)
151
$this->baseScriptUrl=Yii::app()->getAssetManager()->publish(Yii::getPathOfAlias('zii.widgets.assets')).'/listview';
153
if($this->cssFile!==false)
155
if($this->cssFile===null)
156
$this->cssFile=$this->baseScriptUrl.'/styles.css';
157
Yii::app()->getClientScript()->registerCssFile($this->cssFile);
162
* Registers necessary client scripts.
164
public function registerClientScript()
168
if($this->ajaxUpdate===false)
171
$ajaxUpdate=array_unique(preg_split('/\s*,\s*/',$this->ajaxUpdate.','.$id,-1,PREG_SPLIT_NO_EMPTY));
173
'ajaxUpdate'=>$ajaxUpdate,
174
'ajaxVar'=>$this->ajaxVar,
175
'pagerClass'=>$this->pagerCssClass,
176
'sorterClass'=>$this->sorterCssClass,
178
if($this->beforeAjaxUpdate!==null)
179
$options['beforeAjaxUpdate']=(strpos($this->beforeAjaxUpdate,'js:')!==0 ? 'js:' : '').$this->beforeAjaxUpdate;
180
if($this->afterAjaxUpdate!==null)
181
$options['afterAjaxUpdate']=(strpos($this->afterAjaxUpdate,'js:')!==0 ? 'js:' : '').$this->afterAjaxUpdate;
183
$options=CJavaScript::encode($options);
184
$cs=Yii::app()->getClientScript();
185
$cs->registerCoreScript('jquery');
186
$cs->registerScriptFile($this->baseScriptUrl.'/jquery.yiilistview.js');
187
$cs->registerScript(__CLASS__.'#'.$id,"jQuery('#$id').yiiListView($options);");
191
* Renders the data item list.
193
public function renderItems()
195
echo CHtml::openTag('div',array('class'=>$this->itemsCssClass))."\n";
196
$data=$this->dataProvider->getData();
199
$owner=$this->getOwner();
200
$render=$owner instanceof CController ? 'renderPartial' : 'render';
201
foreach($data as $i=>$item)
203
$data=$this->viewData;
206
$data['widget']=$this;
207
$owner->$render($this->itemView,$data);
211
$this->renderEmptyText();
212
echo CHtml::closeTag('div');
216
* Renders the sorter.
218
public function renderSorter()
220
if($this->dataProvider->getItemCount()<=0 || !$this->enableSorting || empty($this->sortableAttributes))
222
echo CHtml::openTag('div',array('class'=>$this->sorterCssClass))."\n";
223
echo $this->sorterHeader===null ? Yii::t('zii','Sort by: ') : $this->sorterHeader;
225
$sort=$this->dataProvider->getSort();
226
foreach($this->sortableAttributes as $name=>$label)
229
if(is_integer($name))
230
echo $sort->link($label);
232
echo $sort->link($name,$label);
236
echo $this->sorterFooter;
237
echo CHtml::closeTag('div');
added
removed
yii/zii/widgets/CListView.php
