CheckboxColumn.php 2.98 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

Qiang Xue committed
10 11 12 13
use Closure;
use yii\base\InvalidConfigException;
use yii\helpers\Html;

Qiang Xue committed
14
/**
15
 * CheckboxColumn displays a column of checkboxes in a grid view.
16
 *
17
 * To add a CheckboxColumn to the [[GridView]], add it to the [[GridView::columns|columns]] configuration as follows:
18 19 20 21 22 23 24 25 26 27 28
 *
 * ```php
 * 'columns' => [
 *     // ...
 *     [
 *         'class' => 'yii\grid\CheckboxColumn',
 *         // you may configure additional properties here
 *     ],
 * ]
 * ```
 *
29 30 31 32 33 34 35 36
 * Users may click on the checkboxes to select rows of the grid. The selected rows may be
 * obtained by calling the following JavaScript code:
 *
 * ~~~
 * var keys = $('#grid').yiiGridView('getSelectedRows');
 * // keys is an array consisting of the keys associated with the selected rows
 * ~~~
 *
Qiang Xue committed
37 38 39 40 41
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @since 2.0
 */
class CheckboxColumn extends Column
{
42 43 44
	/**
	 * @var string the name of the input checkbox input fields. This will be appended with `[]` to ensure it is an array.
	 */
45
	public $name = 'selection';
46 47
	/**
	 * @var array HTML attributes for the checkboxes.
48
	 * @see \yii\helpers\Html::renderTagAttributes() for details on how attributes are being rendered.
49
	 */
Alexander Makarov committed
50
	public $checkboxOptions = [];
51 52 53
	/**
	 * @var bool whether it is possible to select multiple rows. Defaults to `true`.
	 */
Qiang Xue committed
54 55
	public $multiple = true;

Qiang Xue committed
56

57 58 59 60
	/**
	 * @inheritdoc
	 * @throws \yii\base\InvalidConfigException if [[name]] is not set.
	 */
Qiang Xue committed
61 62
	public function init()
	{
Qiang Xue committed
63 64 65
		parent::init();
		if (empty($this->name)) {
			throw new InvalidConfigException('The "name" property must be set.');
Qiang Xue committed
66
		}
Qiang Xue committed
67 68
		if (substr($this->name, -2) !== '[]') {
			$this->name .= '[]';
Qiang Xue committed
69 70 71 72 73
		}
	}

	/**
	 * Renders the header cell content.
Qiang Xue committed
74
	 * The default implementation simply renders [[header]].
Qiang Xue committed
75 76
	 * This method may be overridden to customize the rendering of the header cell.
	 * @return string the rendering result
Qiang Xue committed
77 78 79
	 */
	protected function renderHeaderCellContent()
	{
Qiang Xue committed
80 81
		$name = rtrim($this->name, '[]') . '_all';
		$id = $this->grid->options['id'];
Alexander Makarov committed
82
		$options = json_encode([
Qiang Xue committed
83 84 85
			'name' => $this->name,
			'multiple' => $this->multiple,
			'checkAll' => $name,
Alexander Makarov committed
86
		]);
Qiang Xue committed
87
		$this->grid->getView()->registerJs("jQuery('#$id').yiiGridView('setSelectionColumn', $options);");
Qiang Xue committed
88

Qiang Xue committed
89 90
		if ($this->header !== null || !$this->multiple) {
			return parent::renderHeaderCellContent();
Qiang Xue committed
91
		} else {
Alexander Makarov committed
92
			return Html::checkBox($name, false, ['class' => 'select-on-check-all']);
Qiang Xue committed
93 94 95 96
		}
	}

	/**
97
	 * @inheritdoc
Qiang Xue committed
98
	 */
99
	protected function renderDataCellContent($model, $key, $index)
Qiang Xue committed
100
	{
Qiang Xue committed
101
		if ($this->checkboxOptions instanceof Closure) {
102
			$options = call_user_func($this->checkboxOptions, $model, $key, $index, $this);
Qiang Xue committed
103
		} else {
Qiang Xue committed
104
			$options = $this->checkboxOptions;
105 106 107
			if (!isset($options['value'])) {
				$options['value'] = is_array($key) ? json_encode($key) : $key;
			}
Qiang Xue committed
108
		}
Qiang Xue committed
109
		return Html::checkbox($this->name, !empty($options['checked']), $options);
Qiang Xue committed
110 111
	}
}