GridView.php 13.3 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

use Yii;
use Closure;
use yii\base\Formatter;
use yii\base\InvalidConfigException;
use yii\helpers\Html;
15
use yii\helpers\Json;
16
use yii\widgets\BaseListView;
Qiang Xue committed
17 18

/**
19 20 21 22
 * The GridView widget is used to display data in a grid.
 *
 * It provides features like sorting, paging and also filtering the data.
 *
Qiang Xue committed
23 24 25
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @since 2.0
 */
26
class GridView extends BaseListView
Qiang Xue committed
27 28 29 30 31
{
	const FILTER_POS_HEADER = 'header';
	const FILTER_POS_FOOTER = 'footer';
	const FILTER_POS_BODY = 'body';

32 33 34 35
	/**
	 * @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
36
	public $dataColumnClass;
37 38 39 40
	/**
	 * @var string the caption of the grid table
	 * @see captionOptions
	 */
Qiang Xue committed
41
	public $caption;
42 43 44 45
	/**
	 * @var array the HTML attributes for the caption element
	 * @see caption
	 */
Alexander Makarov committed
46
	public $captionOptions = [];
47 48 49
	/**
	 * @var array the HTML attributes for the grid table element
	 */
Alexander Makarov committed
50
	public $tableOptions = ['class' => 'table table-striped table-bordered'];
51 52 53 54 55
	/**
	 * @var array the HTML attributes for the container tag of the grid view.
	 * The "tag" element specifies the tag name of the container element and defaults to "div".
	 */
	public $options = ['class' => 'grid-view'];
56 57 58
	/**
	 * @var array the HTML attributes for the table header row
	 */
Alexander Makarov committed
59
	public $headerRowOptions = [];
60 61 62
	/**
	 * @var array the HTML attributes for the table footer row
	 */
Alexander Makarov committed
63
	public $footerRowOptions = [];
64 65 66 67 68 69
	/**
	 * @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:
	 *
70
	 * ```php
71
	 * function ($model, $key, $index, $grid)
72
	 * ```
73 74 75 76 77 78
	 *
	 * - `$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
	 */
Alexander Makarov committed
79
	public $rowOptions = [];
80 81 82 83 84
	/**
	 * @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
85
	public $beforeRow;
86 87 88 89 90
	/**
	 * @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
91
	public $afterRow;
92 93 94
	/**
	 * @var boolean whether to show the header section of the grid table.
	 */
Qiang Xue committed
95 96
	public $showHeader = true;
	/**
97
	 * @var boolean whether to show the footer section of the grid table.
Qiang Xue committed
98
	 */
99
	public $showFooter = false;
100
	/**
101
	 * @var boolean whether to show the grid view if [[dataProvider]] returns no data.
102
	 */
103
	public $showOnEmpty = true;
Qiang Xue committed
104 105 106 107 108 109 110 111
	/**
	 * @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
112
	 * for one particular grid column. For example,
Qiang Xue committed
113
	 *
114
	 * ```php
Alexander Makarov committed
115 116 117
	 * [
	 *     ['class' => SerialColumn::className()],
	 *     [
118 119 120
	 *         'class' => DataColumn::className(),
	 *         'attribute' => 'name',
	 *         'format' => 'text',
121
	 *         'label' => 'Name',
Alexander Makarov committed
122 123 124
	 *     ],
	 *     ['class' => CheckboxColumn::className()],
	 * ]
125
	 * ```
Qiang Xue committed
126
	 *
127 128 129
	 * 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
130
	 * which only contains "attribute", "format", and/or "label" options: `"attribute:format:label"`.
131
	 * For example, the above "name" column can also be specified as: `"name:text:Name"`.
132
	 * Both "format" and "label" are optional. They will take default values if absent.
Qiang Xue committed
133
	 */
Alexander Makarov committed
134
	public $columns = [];
Qiang Xue committed
135 136
	public $emptyCell = '&nbsp;';
	/**
137
	 * @var \yii\base\Model the model that keeps the user-entered filter data. When this property is set,
Qiang Xue committed
138 139
	 * 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.
140 141 142 143 144
	 *
	 * 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
145 146
	 */
	public $filterModel;
147 148 149 150 151 152 153 154
	/**
	 * @var string|array the URL for returning the filtering result. [[Html::url()]] will be called to
	 * normalize the URL. If not set, the current controller action will be used.
	 * When the user makes change to any filter input, the current filtering inputs will be appended
	 * as GET parameters to this URL.
	 */
	public $filterUrl;
	public $filterSelector;
Qiang Xue committed
155 156
	/**
	 * @var string whether the filters should be displayed in the grid view. Valid values include:
157 158 159 160 161 162 163 164
	 *
	 * - [[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
165
	 */
Alexander Makarov committed
166
	public $filterRowOptions = ['class' => 'filters'];
Qiang Xue committed
167 168 169

	/**
	 * Initializes the grid view.
Qiang Xue committed
170
	 * This method will initialize required property values and instantiate [[columns]] objects.
Qiang Xue committed
171 172 173 174 175 176 177 178 179 180 181 182
	 */
	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
183 184 185
		if (!isset($this->options['id'])) {
			$this->options['id'] = $this->getId();
		}
186 187 188
		if (!isset($this->filterRowOptions['id'])) {
			$this->filterRowOptions['id'] = $this->options['id'] . '-filters';
		}
Qiang Xue committed
189 190 191 192

		$this->initColumns();
	}

Qiang Xue committed
193 194 195 196 197 198
	/**
	 * Runs the widget.
	 */
	public function run()
	{
		$id = $this->options['id'];
199
		$options = Json::encode($this->getClientOptions());
Qiang Xue committed
200 201
		$view = $this->getView();
		GridViewAsset::register($view);
202
		$view->registerJs("jQuery('#$id').yiiGridView($options);");
Qiang Xue committed
203 204 205
		parent::run();
	}

206 207 208 209 210 211 212

	/**
	 * Returns the options for the grid view JS widget.
	 * @return array the options
	 */
	protected function getClientOptions()
	{
Alexander Makarov committed
213
		$filterUrl = isset($this->filterUrl) ? $this->filterUrl : [Yii::$app->controller->action->id];
214 215 216 217 218 219
		$id = $this->filterRowOptions['id'];
		$filterSelector = "#$id input, #$id select";
		if (isset($this->filterSelector)) {
			$filterSelector .= ', ' . $this->filterSelector;
		}

Alexander Makarov committed
220
		return [
221 222
			'filterUrl' => Html::url($filterUrl),
			'filterSelector' => $filterSelector,
Alexander Makarov committed
223
		];
224 225
	}

Qiang Xue committed
226
	/**
227
	 * Renders the data models for the grid view.
Qiang Xue committed
228 229 230
	 */
	public function renderItems()
	{
Alexander Makarov committed
231
		$content = array_filter([
Qiang Xue committed
232 233 234 235 236
			$this->renderCaption(),
			$this->renderColumnGroup(),
			$this->showHeader ? $this->renderTableHeader() : false,
			$this->showFooter ? $this->renderTableFooter() : false,
			$this->renderTableBody(),
Alexander Makarov committed
237
		]);
Qiang Xue committed
238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253
		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) {
254
			/** @var Column $column */
Qiang Xue committed
255 256 257 258 259 260
			if (!empty($column->options)) {
				$requireColumnGroup = true;
				break;
			}
		}
		if ($requireColumnGroup) {
Alexander Makarov committed
261
			$cols = [];
Qiang Xue committed
262 263 264 265 266 267 268 269 270 271 272 273 274 275 276
			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()
	{
Alexander Makarov committed
277
		$cells = [];
Qiang Xue committed
278
		foreach ($this->columns as $column) {
279
			/** @var Column $column */
Qiang Xue committed
280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296
			$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()
	{
Alexander Makarov committed
297
		$cells = [];
Qiang Xue committed
298
		foreach ($this->columns as $column) {
299
			/** @var Column $column */
Qiang Xue committed
300 301 302 303 304 305 306 307 308 309 310 311 312 313 314
			$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) {
Alexander Makarov committed
315
			$cells = [];
Qiang Xue committed
316
			foreach ($this->columns as $column) {
317
				/** @var Column $column */
Qiang Xue committed
318 319
				$cells[] = $column->renderFilterCell();
			}
320
			return Html::tag('tr', implode('', $cells), $this->filterRowOptions);
Qiang Xue committed
321 322 323 324 325 326 327 328 329 330 331
		} else {
			return '';
		}
	}

	/**
	 * Renders the table body.
	 * @return string the rendering result
	 */
	public function renderTableBody()
	{
332
		$models = array_values($this->dataProvider->getModels());
Qiang Xue committed
333
		$keys = $this->dataProvider->getKeys();
Alexander Makarov committed
334
		$rows = [];
335
		foreach ($models as $index => $model) {
Qiang Xue committed
336 337
			$key = $keys[$index];
			if ($this->beforeRow !== null) {
338
				$row = call_user_func($this->beforeRow, $model, $key, $index, $this);
Qiang Xue committed
339 340 341 342 343
				if (!empty($row)) {
					$rows[] = $row;
				}
			}

344
			$rows[] = $this->renderTableRow($model, $key, $index);
Qiang Xue committed
345 346

			if ($this->afterRow !== null) {
347
				$row = call_user_func($this->afterRow, $model, $key, $index, $this);
Qiang Xue committed
348 349 350 351 352
				if (!empty($row)) {
					$rows[] = $row;
				}
			}
		}
353 354 355 356

		if (empty($rows)) {
			$colspan = count($this->columns);
			return "<tbody>\n<tr><td colspan=\"$colspan\">" . $this->renderEmpty() . "</td></tr>\n</tbody>";
Qiang Xue committed
357 358
		} else {
			return "<tbody>\n" . implode("\n", $rows) . "\n</tbody>";
359
		}
Qiang Xue committed
360 361 362
	}

	/**
363 364 365 366
	 * 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
367 368
	 * @return string the rendering result
	 */
369
	public function renderTableRow($model, $key, $index)
Qiang Xue committed
370
	{
Alexander Makarov committed
371
		$cells = [];
372
		/** @var Column $column */
Qiang Xue committed
373
		foreach ($this->columns as $column) {
374
			$cells[] = $column->renderDataCell($model, $key, $index);
Qiang Xue committed
375 376
		}
		if ($this->rowOptions instanceof Closure) {
377
			$options = call_user_func($this->rowOptions, $model, $key, $index, $this);
Qiang Xue committed
378 379 380
		} else {
			$options = $this->rowOptions;
		}
381
		$options['data-key'] = is_array($key) ? json_encode($key) : $key;
Qiang Xue committed
382 383 384 385 386 387 388 389 390 391 392 393 394 395 396
		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 {
Alexander Makarov committed
397
				$column = Yii::createObject(array_merge([
Qiang Xue committed
398
					'class' => $this->dataColumnClass ?: DataColumn::className(),
Qiang Xue committed
399
					'grid' => $this,
Alexander Makarov committed
400
				], $column));
Qiang Xue committed
401 402 403 404 405 406 407 408 409 410
			}
			if (!$column->visible) {
				unset($this->columns[$i]);
				continue;
			}
			$this->columns[$i] = $column;
		}
	}

	/**
411
	 * Creates a [[DataColumn]] object based on a string in the format of "attribute:format:label".
Qiang Xue committed
412 413 414 415 416 417
	 * @param string $text the column specification string
	 * @return DataColumn the column instance
	 * @throws InvalidConfigException if the column specification is invalid
	 */
	protected function createDataColumn($text)
	{
418
		if (!preg_match('/^([\w\.]+)(:(\w*))?(:(.*))?$/', $text, $matches)) {
Alexander Kochetov committed
419
			throw new InvalidConfigException('The column must be specified in the format of "attribute", "attribute:format" or "attribute:format:label"');
Qiang Xue committed
420
		}
Alexander Makarov committed
421
		return Yii::createObject([
Qiang Xue committed
422
			'class' => $this->dataColumnClass ?: DataColumn::className(),
Qiang Xue committed
423 424
			'grid' => $this,
			'attribute' => $matches[1],
425
			'format' => isset($matches[3]) ? $matches[3] : 'text',
426
			'label' => isset($matches[5]) ? $matches[5] : null,
Alexander Makarov committed
427
		]);
Qiang Xue committed
428 429 430 431
	}

	protected function guessColumns()
	{
432 433 434 435
		$models = $this->dataProvider->getModels();
		$model = reset($models);
		if (is_array($model) || is_object($model)) {
			foreach ($model as $name => $value) {
Qiang Xue committed
436 437 438 439 440 441 442
				$this->columns[] = $name;
			}
		} else {
			throw new InvalidConfigException('Unable to generate columns from data.');
		}
	}
}