1. Requirements
2. Usage
3. Notes
4. References

This extension is a drop-in replacement for the CButtonColumn used by the CGridView widget.

Its purpose is:

• to allow general buttons (buttons not specific to a row in a grid) to be placed in the filter cell of the column (for example, included as a default is a create button, to allow you to launch the create page of a model directly from the GridView);

• to allow the use of form submits as buttons, in order to ensure a graceful degradation of the buttons which require POST form submit when Javascript is not present or fails.

The extension changes default behaviour of the delete button, by making it a submit button (self contained form ~~~ [html]

<div style="display:none"><input type="hidden" value="4b09197af08aa26718201dda761c60dbae1dacab" name="YII_CSRF_TOKEN"/>
</div>
<fieldset class="button-column-field">
	<input type="image" class="button-column-submit" src="/assets/2f966bb8/gridview/delete.png" name="yt1" value="submit"/>
</fieldset>

~~~ which is fully xHtml compliant and contains the Yii CSRF token if enabled), which means that even when Javascript is disabled, the delete button will function as intended (instead of throwing an error as it does presently). The extension also adds by default a create button into the filter cell of the grid column, providing a link to creating a new model.

Requirements ¶

The extension was built on Yii 1.1.10 and functions on Yii 1.1.9, but I can't see any changes in things that it relies on that would mean that it shouldn't function in previous versions.

Usage ¶

You will need to copy the class file into your extensions folder, then all you need to do is use it in place of CButtonColumn in your GridViews, like follows:

Yii::import('ext.RButtonColumn');
$this->widget('zii.widgets.grid.CGridView', array(
	'dataProvider' => $model->search(),
	'blankDisplay' => ' ',
	'filter' => $model,
	'columns' => array(
		'id',
		'name',
		array(
			'class' => 'ext.RButtonColumn',
			'template' => '{view} {update} {reset} {delete}',
			'buttons' => array(
				'reset' => array(
					'label' => Yii::t('Admin', 'Reset password'),
					'url' => '$this->grid->controller->createUrl(\'reset\', array(\'id\' => $data->id))',
					'type' => RButtonColumn::SUBMIT_BUTTON,
					'imageUrl' => Yii::app()->request->baseUrl.'/images/password.png',
				),
			),
		),
	),
));

As you can see, in order to make a submit button, there is a new property added to the buttons, which is 'type' - this should be either RButtonColumn::SUBMIT_BUTTON or RButtonColumn::LINK_BUTTON (by default buttons are anchors, and submit forms will only be used if 'type' is set to RButtonColumn::SUBMIT_BUTTON). CHtml is used to generate the form, so any submit buttons will include the CSRF token if enabled. As with the anchor button, if an image Url is included in the button configuration, a submit button will use an image submit instead of the normal button.

New configuration options include:

• $filterHtmlOptions, which allows Html attributes to be set for the filter td (in order to give it a CSS class for example);

• $headerTemplate, which functions in exactly the same way as the original $template, to determine the layout of buttons in the filter cell;

• $createButtonLabel

• $createButtonImageUrl

• $createButtonUrl

• $createButtonOptions - all of the above $createButton options are for the default create button inserted into the filter cell, and function in exactly the same way as their counterparts for the default view, update and delete buttons;

• $headerButtons, allows us to add buttons to the filter cell and works in exactly the same way as the $buttons configuration;

• each button and headerButton entry supports an additional 'type' property allowing us to specify whether it is a submit button.

Notes ¶

When using a submit button, it should be noted that all the Html options given in the button configuration are actually applied to the outer form element, and not to the input button itself, so if you want to style the button or field set, then you should give a CSS class to the button (form) and make your CSS from that (e.g. form.your-class fieldset input { height: 40px; } ).

NB forms are not inline by default, so if you want your buttons to retain the inline style of the anchor buttons, you will need to add CSS with the appropriate classes to make them inline.

Currently only the filter cell is used for general header buttons. I am aware that I could use the header cell instead, but have preferred to leave it for a title (knowing also that if the GridView does not have filters then the buttons will not appear). I am open to changing this or adding different options if required.

The RButtonColumn class overrides most of the important methods from CButtonColumn, so if any changes are made to the way that CButtonColumn functions they will probably not be reflected in this class (and therefore require an update).

References ¶

The reason for this extension and possible solutions were discussed in this original bug report.

All this code is very lightly adapted from the original CButtonColumn class, so all credit is, as usual, due to Qiang.