GridView.php 12.2 KB
Newer Older
Qiang Xue committed
1 2 3 4 5 6 7
<?php
/**
 * @link http://www.yiiframework.com/
 * @copyright Copyright (c) 2008 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */

8
namespace yii\grid;
Qiang Xue committed
9 10 11 12 13 14 15 16

use Yii;
use Closure;
use yii\base\Formatter;
use yii\base\InvalidConfigException;
use yii\base\Widget;
use yii\db\ActiveRecord;
use yii\helpers\Html;
17
use yii\widgets\ListViewBase;
Qiang Xue committed
18 19 20 21 22 23 24 25 26 27 28

/**
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @since 2.0
 */
class GridView extends ListViewBase
{
	const FILTER_POS_HEADER = 'header';
	const FILTER_POS_FOOTER = 'footer';
	const FILTER_POS_BODY = 'body';

29 30 31 32
	/**
	 * @var string the default data column class if the class name is not explicitly specified when configuring a data column.
	 * Defaults to 'yii\grid\DataColumn'.
	 */
Qiang Xue committed
33
	public $dataColumnClass;
34 35 36 37
	/**
	 * @var string the caption of the grid table
	 * @see captionOptions
	 */
Qiang Xue committed
38
	public $caption;
39 40 41 42
	/**
	 * @var array the HTML attributes for the caption element
	 * @see caption
	 */
Qiang Xue committed
43
	public $captionOptions = array();
44 45 46
	/**
	 * @var array the HTML attributes for the grid table element
	 */
Qiang Xue committed
47
	public $tableOptions = array('class' => 'table table-striped table-bordered');
48 49 50
	/**
	 * @var array the HTML attributes for the table header row
	 */
Qiang Xue committed
51
	public $headerRowOptions = array();
52 53 54
	/**
	 * @var array the HTML attributes for the table footer row
	 */
Qiang Xue committed
55
	public $footerRowOptions = array();
56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76
	/**
	 * @var array|Closure the HTML attributes for the table body rows. This can be either an array
	 * specifying the common HTML attributes for all body rows, or an anonymous function that
	 * returns an array of the HTML attributes. The anonymous function will be called once for every
	 * data model returned by [[dataProvider]]. It should have the following signature:
	 *
	 * ~~~php
	 * function ($model, $key, $index, $grid)
	 * ~~~
	 *
	 * - `$model`: the current data model being rendered
	 * - `$key`: the key value associated with the current data model
	 * - `$index`: the zero-based index of the data model in the model array returned by [[dataProvider]]
	 * - `$grid`: the GridView object
	 */
	public $rowOptions = array();
	/**
	 * @var Closure an anonymous function that is called once BEFORE rendering each data model.
	 * It should have the similar signature as [[rowOptions]]. The return result of the function
	 * will be rendered directly.
	 */
Qiang Xue committed
77
	public $beforeRow;
78 79 80 81 82
	/**
	 * @var Closure an anonymous function that is called once AFTER rendering each data model.
	 * It should have the similar signature as [[rowOptions]]. The return result of the function
	 * will be rendered directly.
	 */
Qiang Xue committed
83
	public $afterRow;
84 85 86
	/**
	 * @var boolean whether to show the header section of the grid table.
	 */
Qiang Xue committed
87 88
	public $showHeader = true;
	/**
89
	 * @var boolean whether to show the footer section of the grid table.
Qiang Xue committed
90
	 */
91
	public $showFooter = false;
Qiang Xue committed
92 93 94 95 96 97 98 99
	/**
	 * @var array|Formatter the formatter used to format model attribute values into displayable texts.
	 * This can be either an instance of [[Formatter]] or an configuration array for creating the [[Formatter]]
	 * instance. If this property is not set, the "formatter" application component will be used.
	 */
	public $formatter;
	/**
	 * @var array grid column configuration. Each array element represents the configuration
100
	 * for one particular grid column. For example,
Qiang Xue committed
101
	 *
102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117
	 * ~~~php
	 * array(
	 *     array(
	 *         'class' => SerialColumn::className(),
	 *     ),
	 *     array(
	 *         'class' => DataColumn::className(),
	 *         'attribute' => 'name',
	 *         'format' => 'text',
	 *         'header' => 'Name',
	 *     ),
	 *     array(
	 *         'class' => CheckboxColumn::className(),
	 *     ),
	 * )
	 * ~~~
Qiang Xue committed
118
	 *
119 120 121 122 123 124
	 * If a column is of class [[DataColumn]], the "class" element can be omitted.
	 *
	 * As a shortcut format, a string may be used to specify the configuration of a data column
	 * which only contains "attribute", "format", and/or "header" options: `"attribute:format:header"`.
	 * For example, the above "name" column can also be specified as: `"name:text:Name"`.
	 * Both "format" and "header" are optional. They will take default values if absent.
Qiang Xue committed
125 126 127 128 129 130 131 132 133 134 135
	 */
	public $columns = array();
	/**
	 * @var string the layout that determines how different sections of the list view should be organized.
	 * The following tokens will be replaced with the corresponding section contents:
	 *
	 * - `{summary}`: the summary section. See [[renderSummary()]].
	 * - `{items}`: the list items. See [[renderItems()]].
	 * - `{sorter}`: the sorter. See [[renderSorter()]].
	 * - `{pager}`: the pager. See [[renderPager()]].
	 */
Qiang Xue committed
136
	public $layout = "{items}\n{summary}\n{pager}";
Qiang Xue committed
137 138
	public $emptyCell = '&nbsp;';
	/**
139
	 * @var \yii\base\Model the model that keeps the user-entered filter data. When this property is set,
Qiang Xue committed
140 141
	 * 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.
142 143 144 145 146
	 *
	 * Note that in order to show an input field for filtering, a column must have its [[DataColumn::attribute]]
	 * property set or have [[DataColumn::filter]] set as the HTML code for the input field.
	 *
	 * When this property is not set (null) the filtering feature is disabled.
Qiang Xue committed
147 148 149 150
	 */
	public $filterModel;
	/**
	 * @var string whether the filters should be displayed in the grid view. Valid values include:
151 152 153 154 155 156 157 158
	 *
	 * - [[FILTER_POS_HEADER]]: the filters will be displayed on top of each column's header cell.
	 * - [[FILTER_POS_BODY]]: the filters will be displayed right below each column's header cell.
	 * - [[FILTER_POS_FOOTER]]: the filters will be displayed below each column's footer cell.
	 */
	public $filterPosition = self::FILTER_POS_BODY;
	/**
	 * @var array the HTML attributes for the filter row element
Qiang Xue committed
159
	 */
160
	public $filterRowOptions = array('class' => 'filters');
Qiang Xue committed
161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176

	/**
	 * Initializes the grid view.
	 * This method will initialize required property values and instantiate {@link columns} objects.
	 */
	public function init()
	{
		parent::init();
		if ($this->formatter == null) {
			$this->formatter = Yii::$app->getFormatter();
		} elseif (is_array($this->formatter)) {
			$this->formatter = Yii::createObject($this->formatter);
		}
		if (!$this->formatter instanceof Formatter) {
			throw new InvalidConfigException('The "formatter" property must be either a Format object or a configuration array.');
		}
Qiang Xue committed
177 178 179
		if (!isset($this->options['id'])) {
			$this->options['id'] = $this->getId();
		}
Qiang Xue committed
180 181 182 183

		$this->initColumns();
	}

Qiang Xue committed
184 185 186 187 188 189 190 191 192 193 194 195
	/**
	 * Runs the widget.
	 */
	public function run()
	{
		$id = $this->options['id'];
		$view = $this->getView();
		GridViewAsset::register($view);
		$view->registerJs("jQuery('#$id').yiiGridView();");
		parent::run();
	}

Qiang Xue committed
196
	/**
197
	 * Renders the data models for the grid view.
Qiang Xue committed
198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223
	 */
	public function renderItems()
	{
		$content = array_filter(array(
			$this->renderCaption(),
			$this->renderColumnGroup(),
			$this->showHeader ? $this->renderTableHeader() : false,
			$this->showFooter ? $this->renderTableFooter() : false,
			$this->renderTableBody(),
		));
		return Html::tag('table', implode("\n", $content), $this->tableOptions);
	}

	public function renderCaption()
	{
		if (!empty($this->caption)) {
			return Html::tag('caption', $this->caption, $this->captionOptions);
		} else {
			return false;
		}
	}

	public function renderColumnGroup()
	{
		$requireColumnGroup = false;
		foreach ($this->columns as $column) {
224
			/** @var Column $column */
Qiang Xue committed
225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248
			if (!empty($column->options)) {
				$requireColumnGroup = true;
				break;
			}
		}
		if ($requireColumnGroup) {
			$cols = array();
			foreach ($this->columns as $column) {
				$cols[] = Html::tag('col', '', $column->options);
			}
			return Html::tag('colgroup', implode("\n", $cols));
		} else {
			return false;
		}
	}

	/**
	 * Renders the table header.
	 * @return string the rendering result
	 */
	public function renderTableHeader()
	{
		$cells = array();
		foreach ($this->columns as $column) {
249
			/** @var Column $column */
Qiang Xue committed
250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268
			$cells[] = $column->renderHeaderCell();
		}
		$content = implode('', $cells);
		if ($this->filterPosition == self::FILTER_POS_HEADER) {
			$content = $this->renderFilters() . $content;
		} elseif ($this->filterPosition == self::FILTER_POS_BODY) {
			$content .= $this->renderFilters();
		}
		return "<thead>\n" . Html::tag('tr', $content, $this->headerRowOptions) . "\n</thead>";
	}

	/**
	 * Renders the table footer.
	 * @return string the rendering result
	 */
	public function renderTableFooter()
	{
		$cells = array();
		foreach ($this->columns as $column) {
269
			/** @var Column $column */
Qiang Xue committed
270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286
			$cells[] = $column->renderFooterCell();
		}
		$content = implode('', $cells);
		if ($this->filterPosition == self::FILTER_POS_FOOTER) {
			$content .= $this->renderFilters();
		}
		return "<tfoot>\n" . Html::tag('tr', $content, $this->footerRowOptions) . "\n</tfoot>";
	}

	/**
	 * Renders the filter.
	 */
	public function renderFilters()
	{
		if ($this->filterModel !== null) {
			$cells = array();
			foreach ($this->columns as $column) {
287
				/** @var Column $column */
Qiang Xue committed
288 289
				$cells[] = $column->renderFilterCell();
			}
290
			return Html::tag('tr', implode('', $cells), $this->filterRowOptions);
Qiang Xue committed
291 292 293 294 295 296 297 298 299 300 301
		} else {
			return '';
		}
	}

	/**
	 * Renders the table body.
	 * @return string the rendering result
	 */
	public function renderTableBody()
	{
302
		$models = array_values($this->dataProvider->getModels());
Qiang Xue committed
303 304
		$keys = $this->dataProvider->getKeys();
		$rows = array();
305
		foreach ($models as $index => $model) {
Qiang Xue committed
306 307
			$key = $keys[$index];
			if ($this->beforeRow !== null) {
308
				$row = call_user_func($this->beforeRow, $model, $key, $index, $this);
Qiang Xue committed
309 310 311 312 313
				if (!empty($row)) {
					$rows[] = $row;
				}
			}

314
			$rows[] = $this->renderTableRow($model, $key, $index);
Qiang Xue committed
315 316

			if ($this->afterRow !== null) {
317
				$row = call_user_func($this->afterRow, $model, $key, $index, $this);
Qiang Xue committed
318 319 320 321 322 323 324 325 326
				if (!empty($row)) {
					$rows[] = $row;
				}
			}
		}
		return "<tbody>\n" . implode("\n", $rows) . "\n</tbody>";
	}

	/**
327 328 329 330
	 * Renders a table row with the given data model and key.
	 * @param mixed $model the data model to be rendered
	 * @param mixed $key the key associated with the data model
	 * @param integer $index the zero-based index of the data model among the model array returned by [[dataProvider]].
Qiang Xue committed
331 332
	 * @return string the rendering result
	 */
333
	public function renderTableRow($model, $key, $index)
Qiang Xue committed
334 335
	{
		$cells = array();
336
		/** @var Column $column */
Qiang Xue committed
337
		foreach ($this->columns as $column) {
338
			$cells[] = $column->renderDataCell($model, $index);
Qiang Xue committed
339 340
		}
		if ($this->rowOptions instanceof Closure) {
341
			$options = call_user_func($this->rowOptions, $model, $key, $index, $this);
Qiang Xue committed
342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361
		} else {
			$options = $this->rowOptions;
		}
		$options['data-key'] = $key;
		return Html::tag('tr', implode('', $cells), $options);
	}

	/**
	 * Creates column objects and initializes them.
	 */
	protected function initColumns()
	{
		if (empty($this->columns)) {
			$this->guessColumns();
		}
		foreach ($this->columns as $i => $column) {
			if (is_string($column)) {
				$column = $this->createDataColumn($column);
			} else {
				$column = Yii::createObject(array_merge(array(
Qiang Xue committed
362
					'class' => $this->dataColumnClass ?: DataColumn::className(),
Qiang Xue committed
363 364 365 366 367 368 369 370 371 372 373 374
					'grid' => $this,
				), $column));
			}
			if (!$column->visible) {
				unset($this->columns[$i]);
				continue;
			}
			$this->columns[$i] = $column;
		}
	}

	/**
375
	 * Creates a [[DataColumn]] object based on a string in the format of "attribute:format:header".
Qiang Xue committed
376 377 378 379 380 381
	 * @param string $text the column specification string
	 * @return DataColumn the column instance
	 * @throws InvalidConfigException if the column specification is invalid
	 */
	protected function createDataColumn($text)
	{
382
		if (!preg_match('/^([\w\.]+)(:(\w*))?(:(.*))?$/', $text, $matches)) {
383
			throw new InvalidConfigException('The column must be specified in the format of "attribute", "attribute:format" or "attribute:format:header');
Qiang Xue committed
384 385
		}
		return Yii::createObject(array(
Qiang Xue committed
386
			'class' => $this->dataColumnClass ?: DataColumn::className(),
Qiang Xue committed
387 388
			'grid' => $this,
			'attribute' => $matches[1],
389 390
			'format' => isset($matches[3]) ? $matches[3] : 'text',
			'header' => isset($matches[5]) ? $matches[5] : null,
Qiang Xue committed
391 392 393 394 395
		));
	}

	protected function guessColumns()
	{
396 397 398 399
		$models = $this->dataProvider->getModels();
		$model = reset($models);
		if (is_array($model) || is_object($model)) {
			foreach ($model as $name => $value) {
Qiang Xue committed
400 401 402 403 404 405 406
				$this->columns[] = $name;
			}
		} else {
			throw new InvalidConfigException('Unable to generate columns from data.');
		}
	}
}