Yii 1.1:using cbuttoncolumn to customize buttons in Cgridview follow @yiiframework

http://www.yiiframework.com/wiki/106/using-cbuttoncolumn-to-customize-buttons-in-cgridview/

Introduction

Cgridview is a one of the most flexible widgets in Yii and example its flexibility are cbuttoncolumn used to build buttons for Steering model in each grid row. Here on this how-to we'll explain ways user can customize Cbuttoncolumn to flexibly fit it to its needs.

Basic Customization

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

The easiest-customize look and behaviour of them are to use series of cbuttoncolumn properties, like: upd Atebuttonimageurl (path to image for Update button), Updatebuttonlabel (label for the update bu Tton; Not html-encoded), updatebuttonoptions (HTML options for this button, used in the as many htmloption s property for many widgets) and Updatebuttonurl (a PHP expresion, which is the evaluated for button and whose Result is used as the URL). respective properties you'll find for other default buttons.

A Few remarks:for Delete button only, there are deleteconfirmation Property (String), which can are use D for customizing message being displayed as confirmation of delete operation. In PHP expression used for Xxxbuttonurl property, you can use variable $row for the row number (zero-base D); $data for the data model for the row and $this for the Column object. If you provide a empty string for Xxxbuttonimageurl or set it to false, a textual link would be used Inst ead.

Info: Delete confirmation message (and other textual elements of cbuttoncolumn or Cgridview) can is also customized by creating zii.php file in Protected/messages/languageid/(or even better-copying one from for example Yii/messages/de/and Transla Ting 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-force YII-Look in your own Messages folder instead of Build-in one inside Framew Ork directory. 

More Flexible customizing

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

You can use the template property to the Change Order of build-in buttons or remove some of them as this:

Array
(
    ' class ' = ' Cbuttoncolumn ',
    ' template ' = ' {delete}{update} ',
)

In Cgridview ' s buttons column build upon above example there would be no view button and delete and update buttons would be In other than default order (delete first).

You can use the same property to introduce new buttons:

Array
(
    ' class ' = ' Cbuttoncolumn ',
    ' template ' = ' {up}{down}{delete} ',
)

For new buttons (and the course-for existing, build-in ones too!) you have to specify look and behaviour. Buttons property of Cbuttoncolumn was used for it. This is a array of buttons ID (which names must correspond to the one provided in template property) and each BU Tton is another an array holding its specific properties.

Here's can use:

' 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 ' = ' and ' ... ',     //a JS function to being invoked when the button is clicked.
    ' Visible ' = ' ... ',   //a PHP expression for determining whether the button is visible.
)

Please, Note:text in the Label property was displayed only, if you had a textual link! If you is using images (build-in or own) instead of text links, text hold in the This property would be rendered as image ' s AL T parameter. If you want to the change text of the ToolTip, which is displayed when the user hovers your image button, you have the to edit Options Pro Perty instead and give the text to their title parameter, like this:

' 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 is similar remarks for above mentioned properties like the one described in first part of this text:in PHP Express Ion used for URLs or visible properties, you can use variable $row for the row number (zero-based) and $d ATA for the data model for the row. If you provide a empty string for imageUrl or set it to false, a textual link would be used instead.

Finally Here is a example of introducing new buttons to Cbuttoncolumn:

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's since jquery is used here, the any function passed to the click should be surrounded by proper jQuery function C All. That's why, we're using the ' 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 and data from model for the current row). It also explains how to use BASEURL function from CHttpRequest class to set an image for button to be a file stored Outsid e protected folder.

  Specific Delete Confirmation

Notice that a standard set of views generated for CRUD operations by the GII includes (in view and update views) delet E menu item with confirmation. This confirmation text can is easily changed/extended to include some the record (model) specific data, like record ID.

This is a not-so-simple in Cgridview (Cbuttoncolumn), and as deleteconfirmation is not parsed. However, there is a tricky by-achieve this (thanks-to- Mdomba for providing it!) using JQuery. Here are an example:

Array
(
        ' class ' = ' Cbuttoncolumn ',
        ' deleteconfirmation ' = ' = ' js: ' Record with ID ' +$ (this). Parent (). Parent (). Children (': First-child '). Text () + ' 'll be deleted! Continue? ' ",
),

We can also use JQuery's Ntn-child function for retrieve contents of the other column:

Array
(
        ' class ' = ' Cbuttoncolumn ',
        ' deleteconfirmation ' = ' + ' JS: ' Do you really want to delete record With the 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 is it have to is in that form, please read the This forum post. 

Final Words

I hope this short how-to would help in better understanding the How flexible buttons in Cgridview can be customized. This is especially important as there was many forum posts asking questions about this. Please, feel free to make any updates or corrections to this article, if you find something be missing or that there be M Istakes in it.

Has a nice day and happy yii-ing! :)