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

namespace yii\grid;

use Yii;
use Closure;
use yii\helpers\Html;
13
use yii\helpers\Url;
Qiang Xue committed
14 15

/**
16 17
 * ActionColumn is a column for the [[GridView]] widget that displays buttons for viewing and manipulating the items.
 *
18 19 20 21 22 23
 * To add an ActionColumn to the gridview, add it to the [[GridView::columns|columns]] configuration as follows:
 *
 * ```php
 * 'columns' => [
 *     // ...
 *     [
24
 *         'class' => ActionColumn::className(),
25 26 27 28 29
 *         // you may configure additional properties here
 *     ],
 * ]
 * ```
 *
Qiang Xue committed
30 31 32 33 34
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @since 2.0
 */
class ActionColumn extends Column
{
35 36 37 38 39 40 41 42 43 44 45 46 47
    /**
     * @var string the ID of the controller that should handle the actions specified here.
     * If not set, it will use the currently active controller. This property is mainly used by
     * [[urlCreator]] to create URLs for different actions. The value of this property will be prefixed
     * to each action name to form the route of the action.
     */
    public $controller;
    /**
     * @var string the template used for composing each cell in the action column.
     * Tokens enclosed within curly brackets are treated as controller action IDs (also called *button names*
     * in the context of action column). They will be replaced by the corresponding button rendering callbacks
     * specified in [[buttons]]. For example, the token `{view}` will be replaced by the result of
     * the callback `buttons['view']`. If a callback cannot be found, the token will be replaced with an empty string.
caboosesw committed
48 49 50 51 52 53 54
     *
     * As an example, to only have the view, and update button you can add the ActionColumn to your GridView columns as follows:
     *
     * ```
     * ['class' => 'yii\grid\ActionColumn', 'template' => '{view} {update}'],
     * ```
     *
55 56 57 58 59 60 61 62 63
     * @see buttons
     */
    public $template = '{view} {update} {delete}';
    /**
     * @var array button rendering callbacks. The array keys are the button names (without curly brackets),
     * and the values are the corresponding button rendering callbacks. The callbacks should use the following
     * signature:
     *
     * ```php
64
     * function ($url, $model, $key) {
65 66 67 68
     *     // return the button HTML code
     * }
     * ```
     *
69 70
     * where `$url` is the URL that the column creates for the button, `$model` is the model object
     * being rendered for the current row, and `$key` is the key of the model in the data provider array.
71 72 73 74 75 76
     *
     * You can add further conditions to the button, for example only display it, when the model is
     * editable (here assuming you have a status field that indicates that):
     *
     * ```php
     * [
77
     *     'update' => function ($url, $model, $key) {
78
     *         return $model->status === 'editable' ? Html::a('Update', $url) : '';
79 80 81
     *     };
     * ],
     * ```
82 83 84 85 86 87 88 89
     */
    public $buttons = [];
    /**
     * @var callable a callback that creates a button URL using the specified model information.
     * The signature of the callback should be the same as that of [[createUrl()]].
     * If this property is not set, button URLs will be created using [[createUrl()]].
     */
    public $urlCreator;
Qiang Xue committed
90

91

92 93 94 95 96 97 98 99
    /**
     * @inheritdoc
     */
    public function init()
    {
        parent::init();
        $this->initDefaultButtons();
    }
100

101
    /**
102
     * Initializes the default button rendering callbacks.
103 104 105 106
     */
    protected function initDefaultButtons()
    {
        if (!isset($this->buttons['view'])) {
107
            $this->buttons['view'] = function ($url, $model, $key) {
108 109 110 111 112 113 114
                return Html::a('<span class="glyphicon glyphicon-eye-open"></span>', $url, [
                    'title' => Yii::t('yii', 'View'),
                    'data-pjax' => '0',
                ]);
            };
        }
        if (!isset($this->buttons['update'])) {
115
            $this->buttons['update'] = function ($url, $model, $key) {
116 117 118 119 120 121 122
                return Html::a('<span class="glyphicon glyphicon-pencil"></span>', $url, [
                    'title' => Yii::t('yii', 'Update'),
                    'data-pjax' => '0',
                ]);
            };
        }
        if (!isset($this->buttons['delete'])) {
123
            $this->buttons['delete'] = function ($url, $model, $key) {
124 125 126 127 128 129 130 131 132
                return Html::a('<span class="glyphicon glyphicon-trash"></span>', $url, [
                    'title' => Yii::t('yii', 'Delete'),
                    'data-confirm' => Yii::t('yii', 'Are you sure you want to delete this item?'),
                    'data-method' => 'post',
                    'data-pjax' => '0',
                ]);
            };
        }
    }
Qiang Xue committed
133

134 135 136
    /**
     * Creates a URL for the given action and model.
     * This method is called for each button and each row.
137 138 139 140 141
     * @param string $action the button name (or action ID)
     * @param \yii\db\ActiveRecord $model the data model
     * @param mixed $key the key associated with the data model
     * @param integer $index the current row index
     * @return string the created URL
142 143 144 145 146 147 148 149
     */
    public function createUrl($action, $model, $key, $index)
    {
        if ($this->urlCreator instanceof Closure) {
            return call_user_func($this->urlCreator, $action, $model, $key, $index);
        } else {
            $params = is_array($key) ? $key : ['id' => (string) $key];
            $params[0] = $this->controller ? $this->controller . '/' . $action : $action;
Qiang Xue committed
150

151 152 153
            return Url::toRoute($params);
        }
    }
Qiang Xue committed
154

155 156 157 158 159 160 161 162 163 164
    /**
     * @inheritdoc
     */
    protected function renderDataCellContent($model, $key, $index)
    {
        return preg_replace_callback('/\\{([\w\-\/]+)\\}/', function ($matches) use ($model, $key, $index) {
            $name = $matches[1];
            if (isset($this->buttons[$name])) {
                $url = $this->createUrl($name, $model, $key, $index);

165
                return call_user_func($this->buttons[$name], $url, $model, $key);
166 167 168 169 170
            } else {
                return '';
            }
        }, $this->template);
    }
Qiang Xue committed
171
}