CheckboxColumn.php 4.26 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
 * Users may click on the checkboxes to select rows of the grid. The selected rows may be
 * obtained by calling the following JavaScript code:
 *
Carsten Brandt committed
32
 * ```javascript
33 34
 * var keys = $('#grid').yiiGridView('getSelectedRows');
 * // keys is an array consisting of the keys associated with the selected rows
Carsten Brandt committed
35
 * ```
36
 *
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 45 46
    /**
     * @var string the name of the input checkbox input fields. This will be appended with `[]` to ensure it is an array.
     */
    public $name = 'selection';
    /**
47 48
     * @var array|\Closure the HTML attributes for checkboxes. This can either be an array of
     * attributes or an anonymous function ([[Closure]]) that returns such an array.
Carsten Brandt committed
49 50 51 52 53 54 55 56 57 58 59 60 61
     * The signature of the function should be the following: `function ($model, $key, $index, $column)`.
     * Where `$model`, `$key`, and `$index` refer to the model, key and index of the row currently being rendered
     * and `$column` is a reference to the [[CheckboxColumn]] object.
     * A function may be used to assign different attributes to different rows based on the data in that row.
     * Specifically if you want to set a different value for the checkbox
     * you can use this option in the following way (in this example using the `name` attribute of the model):
     *
     * ```php
     * 'checkboxOptions' => function($model, $key, $index, $column) {
     *     return ['value' => $model->name];
     * }
     * ```
     *
62 63 64 65
     * @see \yii\helpers\Html::renderTagAttributes() for details on how attributes are being rendered.
     */
    public $checkboxOptions = [];
    /**
66
     * @var boolean whether it is possible to select multiple rows. Defaults to `true`.
67 68
     */
    public $multiple = true;
Qiang Xue committed
69

70

71 72 73 74 75 76 77 78 79 80
    /**
     * @inheritdoc
     * @throws \yii\base\InvalidConfigException if [[name]] is not set.
     */
    public function init()
    {
        parent::init();
        if (empty($this->name)) {
            throw new InvalidConfigException('The "name" property must be set.');
        }
81
        if (substr_compare($this->name, '[]', -2, 2)) {
82 83 84
            $this->name .= '[]';
        }
    }
Qiang Xue committed
85

86 87 88 89 90 91 92 93 94 95 96 97 98 99
    /**
     * Renders the header cell content.
     * The default implementation simply renders [[header]].
     * This method may be overridden to customize the rendering of the header cell.
     * @return string the rendering result
     */
    protected function renderHeaderCellContent()
    {
        $name = rtrim($this->name, '[]') . '_all';
        $id = $this->grid->options['id'];
        $options = json_encode([
            'name' => $this->name,
            'multiple' => $this->multiple,
            'checkAll' => $name,
100
        ], JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
101
        $this->grid->getView()->registerJs("jQuery('#$id').yiiGridView('setSelectionColumn', $options);");
Qiang Xue committed
102

103 104 105 106 107 108
        if ($this->header !== null || !$this->multiple) {
            return parent::renderHeaderCellContent();
        } else {
            return Html::checkBox($name, false, ['class' => 'select-on-check-all']);
        }
    }
Qiang Xue committed
109

110 111 112 113 114 115 116 117 118 119
    /**
     * @inheritdoc
     */
    protected function renderDataCellContent($model, $key, $index)
    {
        if ($this->checkboxOptions instanceof Closure) {
            $options = call_user_func($this->checkboxOptions, $model, $key, $index, $this);
        } else {
            $options = $this->checkboxOptions;
            if (!isset($options['value'])) {
120
                $options['value'] = is_array($key) ? json_encode($key, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE) : $key;
121 122
            }
        }
Qiang Xue committed
123

124 125
        return Html::checkbox($this->name, !empty($options['checked']), $options);
    }
Qiang Xue committed
126
}