Difference between #8 and #7 of Using CButtonColumn to customize buttons in CGridView

unchanged
Title
Using CButtonColumn to customize buttons in CGridView
unchanged
Category
How-tos
unchanged
Tags
CButtonColumn, CGridView, customize, buttons
changed
Content
### Introduction
CGridView is a one of most flexible widgets in Yii and example its flexibility
is CButtonColumn used to build buttons for steering model in each grid row. Here
in this how-to we will explain ways user can customize CButtonColumn to flexibly
fit it to its needs.

### Basic customization
In default look CButtonColumn contains three buttons in this order: {view},
{update} and {delete}. Their meaning and behaviour should be obvious.

The easiest way to customize look and behaviour of them is to use series of
CButtonColumn properties, like: **updateButtonImageUrl** (path to image for
update button), **updateButtonLabel** (label for the update button; not
HTML-encoded), **updateButtonOptions** (HTML options for this button, used in
the way as many htmlOptions property for many widgets) and **updateButtonUrl**
(a PHP expresion that is evaluated for button and whose result is used as the
URL). Respective properties you'll find for other default buttons.

A few remarks:

1. For delete button only, there is **deleteConfirmation** property (string),
which can be used for customizing message being displayed as confirmation of
delete operation.
2. In PHP expression used for **xxxButtonUrl** property, you can use variable
_$row_ for the row number (zero-based); _$data_ for the data model for the row
and _$this_ for the column object.
3. If you provide an empty string for **xxxButtonImageUrl** or set it to false,
a textual link will be used instead.

>Info: Delete confirmation message (and other textual elements of
CButtonColumn or CGridView) can be also customized by creating zii.php file in
_protected/messages/languageID/_ (or even better - copying one from for example
_yii/messages/de/_ and translating or customizing it to own needs). Don't forget
to set **'coreMessages'=>array('basePath'=>'protected/messages')** in
components part of your config.php file for the application to force Yii to look
in your own messages folder instead of build-in one inside framework directory.

### More flexible customizing

If using above properties for customizing many aspects of many buttons is a bit
messy in code or if there is need for more complex customization or introduction
of new buttons there is a better, more flexible way - by using **template** and
**buttons** properties.

You can use template property to change order of build-in buttons or remove some
of them like this:

~~~
[php]
array
(
    'class'=>'CButtonColumn',
    'template'=>'{delete}{update}',
)
~~~
In CGridView's buttons column build upon above example there will be no view
button and delete and update buttons will be in other than default order (delete
first).

You can use the same property to introduce new buttons:
~~~
[php]
array
(
    'class'=>'CButtonColumn',
    'template'=>'{up}{down}{delete}',
)
~~~
For new buttons (and of course - for existing, build-in ones too!) you have to
specify look and behaviour. **buttons** property of CButtonColumn is used for
it. This property is an array of buttons id (which names must correspond to the
one provided in _template_ property) and each button is another array holding
its specific properties.

Here you can use:

~~~
[php]
'buttonID' => array
(
    'label'=>'...',     //Text label of the button.
    'url'=>'...',       //A PHP expression for generating the URL of the
button.
    'imageUrl'=>'...',  //Image URL of the button.
    'options'=>array(), //HTML options for the button tag.
    'click'=>'...',     //A JS function to be invoked when the button is
clicked.
    'visible'=>'...',   //A PHP expression for determining whether the button
is visible.
)
~~~
Please, note: Text in _label_ property is displayed **only**, if you have a
**textual** link! If you are using images (build-in or own) instead of text
links, text hold in this property will be rendered as image's _alt_ parameter.
If you want to change text of _tooltip_, which is displayed when user hovers
your image button, you have to edit _options_ property instead and give the text
to its _title_ parameter, like this:

~~~
[php]
'buttonID' => array
(
    'label'=>'Text shown as alt text to image or as label to text link...',
    'options'=>array('title'=>'Text shown as tooltip when user hovers
image...'),
)
~~~

There are similar remarks for above mentioned properties like the one described
in first part of this text:

1. In PHP expression used for **url** or **visible** properties, you can use
variable _$row_ for the row number (zero-based) and _$data_ for the data model
for the row.
2. If you provide an empty string for **imageUrl** or set it to false, a textual
link will be used instead.

Finally here is an example of introducing new buttons to CButtonColumn:

~~~
[php]
array
(
    'class'=>'CButtonColumn',
    'template'=>'{email}{down}{delete}',
    'buttons'=>array
    (
        'email' => array
        (
            'label'=>'Send an e-mail to this user',
           
'imageUrl'=>Yii::app()->request->baseUrl.'/images/email.png',
            'url'=>'Yii::app()->createUrl("users/email",
array("id"=>$data->id))',
        ),
        'down' => array
        (
            'label'=>'[-]',
            'url'=>'"#"',
            'visible'=>'$data->score > 0',
            'click'=>'function(){alert("Going down!");}',
        ),
    ),
),
~~~
Please note, that since jQuery is used here, any function passed to _click_
should be surrounded by proper jQuery function call. That is why, we are using
_'click'=>'function(){alert("Going down!");}'_ instead of simple
_'click'=>'alert("Going down!");'_.

Above example also shows (_email_ button) how to create a valid URL containing
controller and view plus current user ID (or any other data from model for
current row). It also explains how to use _baseUrl_ function from _CHttpRequest_
class to set an image for button to be a file stored outside _protected_ folder.

### Specific delete confirmation

You may notice that a standard set of views generated for CRUD operations by Gii
includes (in view and update views) delete menu item with confirmation. This
confirmation text can be easily changed/extended to include some record (model)
specific data, like record ID.

This is not so simple in CGridView (CButtonColumn), as _deleteConfirmation_
property is not parsed. However, there is a tricky way to achieve this (thanks
to **[mdomba](http://www.yiiframework.com/user/2650/ "mdomba")** for
providing it!) using jQuery. Here is an example:

~~~
[php]
array
(
        'class'=>'CButtonColumn',
        'deleteConfirmation'=>"js:'Record with ID
'+$(this).parent().parent().children(':first-child').text()+' will be deleted!
Continue?'",
),
~~~

We can also use jQuery's [ntn-child](http://api.jquery.com/nth-child-selector/
"ntn-child") function for retrieve contents of other column:

~~~
[php]
array
(
        'class'=>'CButtonColumn',
        'deleteConfirmation'=>"js:'Do you really want to delete record
with ID '+$(this).parent().parent().children(':nth-child(2)').text()+'?'",
),
~~~

The jQuery function looks really tricky freeky at first sight. If you wish to
know, why it has to be in that form, please read [this forum
post](http://www.yiiframework.com/forum/index.php?/topic/13804-dynamic-deleteconfirmation-in-the-cbuttoncolumn/page__view__findpost__p__68427
"").

### Final words

I hope this short how-to will help in better understanding of how flexible
buttons in CGridView can be customized. This is especially important as there
are many forum posts asking questions about this. Please, feel free to make any
updates or corrections to this article, if you find something is missing or that
there are mistakes in it.

Have a nice day and happy Yii-ing! :)

Russian Version:[The PHP
Times](http://phptime.ru/blog/yii/22.html)Version:
[Использование класса CButtonColumn для изменения
кнопок в виджете
CGridView](http://phptime.ru/blog/yii/22.html)

Chinese
Version:[中文翻译](http://www.yiiwiki.com/wiki/view/id/12/title/%E4%BD%BF%E7%94%A8CButtonColumn%E8%87%AA%E5%AE%9A%E4%B9%89CGridiew%E9%87%8C%E9%9D%A2%E7%9A%84%E6%8C%89%E9%92%AE)