1: <?php
2: /**
3: * CButtonColumn class file.
4: *
5: * @author Qiang Xue <qiang.xue@gmail.com>
6: * @link http://www.yiiframework.com/
7: * @copyright 2008-2013 Yii Software LLC
8: * @license http://www.yiiframework.com/license/
9: */
10:
11: Yii::import('zii.widgets.grid.CGridColumn');
12:
13: /**
14: * CButtonColumn represents a grid view column that renders one or several buttons.
15: *
16: * By default, it will display three buttons, "view", "update" and "delete", which triggers the corresponding
17: * actions on the model of the row.
18: *
19: * By configuring {@link buttons} and {@link template} properties, the column can display other buttons
20: * and customize the display order of the buttons.
21: *
22: * @author Qiang Xue <qiang.xue@gmail.com>
23: * @package zii.widgets.grid
24: * @since 1.1
25: */
26: class CButtonColumn extends CGridColumn
27: {
28: /**
29: * @var array the HTML options for the data cell tags.
30: */
31: public $htmlOptions=array('class'=>'button-column');
32: /**
33: * @var array the HTML options for the header cell tag.
34: */
35: public $headerHtmlOptions=array('class'=>'button-column');
36: /**
37: * @var array the HTML options for the footer cell tag.
38: */
39: public $footerHtmlOptions=array('class'=>'button-column');
40: /**
41: * @var string the template that is used to render the content in each data cell.
42: * These default tokens are recognized: {view}, {update} and {delete}. If the {@link buttons} property
43: * defines additional buttons, their IDs are also recognized here. For example, if a button named 'preview'
44: * is declared in {@link buttons}, we can use the token '{preview}' here to specify where to display the button.
45: */
46: public $template='{view} {update} {delete}';
47: /**
48: * @var string the label for the view button. Defaults to "View".
49: * Note that the label will not be HTML-encoded when rendering.
50: */
51: public $viewButtonLabel;
52: /**
53: * @var string the image URL for the view button. If not set, an integrated image will be used.
54: * You may set this property to be false to render a text link instead.
55: */
56: public $viewButtonImageUrl;
57: /**
58: * @var string a PHP expression that is evaluated for every view button and whose result is used
59: * as the URL for the view button. In this expression, you can use the following variables:
60: * <ul>
61: * <li><code>$row</code> the row number (zero-based)</li>
62: * <li><code>$data</code> the data model for the row</li>
63: * <li><code>$this</code> the column object</li>
64: * </ul>
65: * The PHP expression will be evaluated using {@link evaluateExpression}.
66: *
67: * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
68: * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
69: */
70: public $viewButtonUrl='Yii::app()->controller->createUrl("view",array("id"=>$data->primaryKey))';
71: /**
72: * @var array the HTML options for the view button tag.
73: */
74: public $viewButtonOptions=array('class'=>'view');
75:
76: /**
77: * @var string the label for the update button. Defaults to "Update".
78: * Note that the label will not be HTML-encoded when rendering.
79: */
80: public $updateButtonLabel;
81: /**
82: * @var string the image URL for the update button. If not set, an integrated image will be used.
83: * You may set this property to be false to render a text link instead.
84: */
85: public $updateButtonImageUrl;
86: /**
87: * @var string a PHP expression that is evaluated for every update button and whose result is used
88: * as the URL for the update button. In this expression, you can use the following variables:
89: * <ul>
90: * <li><code>$row</code> the row number (zero-based)</li>
91: * <li><code>$data</code> the data model for the row</li>
92: * <li><code>$this</code> the column object</li>
93: * </ul>
94: * The PHP expression will be evaluated using {@link evaluateExpression}.
95: *
96: * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
97: * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
98: */
99: public $updateButtonUrl='Yii::app()->controller->createUrl("update",array("id"=>$data->primaryKey))';
100: /**
101: * @var array the HTML options for the update button tag.
102: */
103: public $updateButtonOptions=array('class'=>'update');
104:
105: /**
106: * @var string the label for the delete button. Defaults to "Delete".
107: * Note that the label will not be HTML-encoded when rendering.
108: */
109: public $deleteButtonLabel;
110: /**
111: * @var string the image URL for the delete button. If not set, an integrated image will be used.
112: * You may set this property to be false to render a text link instead.
113: */
114: public $deleteButtonImageUrl;
115: /**
116: * @var string a PHP expression that is evaluated for every delete button and whose result is used
117: * as the URL for the delete button. In this expression, you can use the following variables:
118: * <ul>
119: * <li><code>$row</code> the row number (zero-based)</li>
120: * <li><code>$data</code> the data model for the row</li>
121: * <li><code>$this</code> the column object</li>
122: * </ul>
123: * The PHP expression will be evaluated using {@link evaluateExpression}.
124: *
125: * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
126: * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
127: */
128: public $deleteButtonUrl='Yii::app()->controller->createUrl("delete",array("id"=>$data->primaryKey))';
129: /**
130: * @var array the HTML options for the delete button tag.
131: */
132: public $deleteButtonOptions=array('class'=>'delete');
133: /**
134: * @var string the confirmation message to be displayed when delete button is clicked.
135: * By setting this property to be false, no confirmation message will be displayed.
136: * This property is used only if <code>$this->buttons['delete']['click']</code> is not set.
137: */
138: public $deleteConfirmation;
139: /**
140: * @var string a javascript function that will be invoked after the delete ajax call.
141: * This property is used only if <code>$this->buttons['delete']['click']</code> is not set.
142: *
143: * The function signature is <code>function(link, success, data)</code>
144: * <ul>
145: * <li><code>link</code> references the delete link.</li>
146: * <li><code>success</code> status of the ajax call, true if the ajax call was successful, false if the ajax call failed.
147: * <li><code>data</code> the data returned by the server in case of a successful call or XHR object in case of error.
148: * </ul>
149: * Note that if success is true it does not mean that the delete was successful, it only means that the ajax call was successful.
150: *
151: * Example:
152: * <pre>
153: * array(
154: * class'=>'CButtonColumn',
155: * 'afterDelete'=>'function(link,success,data){ if(success) alert("Delete completed successfully"); }',
156: * ),
157: * </pre>
158: */
159: public $afterDelete;
160: /**
161: * @var array the configuration for buttons. Each array element specifies a single button
162: * which has the following format:
163: * <pre>
164: * 'buttonID' => array(
165: * 'label'=>'...', // text label of the button
166: * 'url'=>'...', // a PHP expression for generating the URL of the button
167: * 'imageUrl'=>'...', // image URL of the button. If not set or false, a text link is used
168: * 'options'=>array(...), // HTML options for the button tag
169: * 'click'=>'...', // a JS function to be invoked when the button is clicked
170: * 'visible'=>'...', // a PHP expression for determining whether the button is visible
171: * )
172: * </pre>
173: *
174: * In the PHP expression for the 'url' option and/or 'visible' option, the variable <code>$row</code>
175: * refers to the current row number (zero-based), and <code>$data</code> refers to the data model for
176: * the row.
177: * The PHP expression will be evaluated using {@link evaluateExpression}.
178: * A PHP expression can be any PHP code that has a value. To learn more about what an expression is,
179: * please refer to the {@link http://www.php.net/manual/en/language.expressions.php php manual}.
180: *
181: * If the 'buttonID' is 'view', 'update' or 'delete' the options will be applied to the default buttons.
182: *
183: * Note that in order to display non-default buttons, the {@link template} property needs to
184: * be configured so that the corresponding button IDs appear as tokens in the template.
185: */
186: public $buttons=array();
187:
188: /**
189: * Initializes the column.
190: * This method registers necessary client script for the button column.
191: */
192: public function init()
193: {
194: $this->initDefaultButtons();
195:
196: foreach($this->buttons as $id=>$button)
197: {
198: if(strpos($this->template,'{'.$id.'}')===false)
199: unset($this->buttons[$id]);
200: elseif(isset($button['click']))
201: {
202: if(!isset($button['options']['class']))
203: $this->buttons[$id]['options']['class']=$id;
204: if(!($button['click'] instanceof CJavaScriptExpression))
205: $this->buttons[$id]['click']=new CJavaScriptExpression($button['click']);
206: }
207: }
208:
209: $this->registerClientScript();
210: }
211:
212: /**
213: * Initializes the default buttons (view, update and delete).
214: */
215: protected function initDefaultButtons()
216: {
217: if($this->viewButtonLabel===null)
218: $this->viewButtonLabel=Yii::t('zii','View');
219: if($this->updateButtonLabel===null)
220: $this->updateButtonLabel=Yii::t('zii','Update');
221: if($this->deleteButtonLabel===null)
222: $this->deleteButtonLabel=Yii::t('zii','Delete');
223: if($this->viewButtonImageUrl===null)
224: $this->viewButtonImageUrl=$this->grid->baseScriptUrl.'/view.png';
225: if($this->updateButtonImageUrl===null)
226: $this->updateButtonImageUrl=$this->grid->baseScriptUrl.'/update.png';
227: if($this->deleteButtonImageUrl===null)
228: $this->deleteButtonImageUrl=$this->grid->baseScriptUrl.'/delete.png';
229: if($this->deleteConfirmation===null)
230: $this->deleteConfirmation=Yii::t('zii','Are you sure you want to delete this item?');
231:
232: foreach(array('view','update','delete') as $id)
233: {
234: $button=array(
235: 'label'=>$this->{$id.'ButtonLabel'},
236: 'url'=>$this->{$id.'ButtonUrl'},
237: 'imageUrl'=>$this->{$id.'ButtonImageUrl'},
238: 'options'=>$this->{$id.'ButtonOptions'},
239: );
240: if(isset($this->buttons[$id]))
241: $this->buttons[$id]=array_merge($button,$this->buttons[$id]);
242: else
243: $this->buttons[$id]=$button;
244: }
245:
246: if(!isset($this->buttons['delete']['click']))
247: {
248: if(is_string($this->deleteConfirmation))
249: $confirmation="if(!confirm(".CJavaScript::encode($this->deleteConfirmation).")) return false;";
250: else
251: $confirmation='';
252:
253: if(Yii::app()->request->enableCsrfValidation)
254: {
255: $csrfTokenName = Yii::app()->request->csrfTokenName;
256: $csrfToken = Yii::app()->request->csrfToken;
257: $csrf = "\n\t\tdata:{ '$csrfTokenName':'$csrfToken' },";
258: }
259: else
260: $csrf = '';
261:
262: if($this->afterDelete===null)
263: $this->afterDelete='function(){}';
264:
265: $this->buttons['delete']['click']=<<<EOD
266: function() {
267: $confirmation
268: var th = this,
269: afterDelete = $this->afterDelete;
270: jQuery('#{$this->grid->id}').yiiGridView('update', {
271: type: 'POST',
272: url: jQuery(this).attr('href'),$csrf
273: success: function(data) {
274: jQuery('#{$this->grid->id}').yiiGridView('update');
275: afterDelete(th, true, data);
276: },
277: error: function(XHR) {
278: return afterDelete(th, false, XHR);
279: }
280: });
281: return false;
282: }
283: EOD;
284: }
285: }
286:
287: /**
288: * Registers the client scripts for the button column.
289: */
290: protected function registerClientScript()
291: {
292: $js=array();
293: foreach($this->buttons as $id=>$button)
294: {
295: if(isset($button['click']))
296: {
297: $function=CJavaScript::encode($button['click']);
298: $class=preg_replace('/\s+/','.',$button['options']['class']);
299: $js[]="jQuery(document).on('click','#{$this->grid->id} a.{$class}',$function);";
300: }
301: }
302:
303: if($js!==array())
304: Yii::app()->getClientScript()->registerScript(__CLASS__.'#'.$this->id, implode("\n",$js));
305: }
306:
307: /**
308: * Returns the data cell content.
309: * This method renders the view, update and delete buttons in the data cell.
310: * @param integer $row the row number (zero-based)
311: * @return string the data cell content.
312: * @since 1.1.16
313: */
314: public function getDataCellContent($row)
315: {
316: $data=$this->grid->dataProvider->data[$row];
317: $tr=array();
318: ob_start();
319: foreach($this->buttons as $id=>$button)
320: {
321: $this->renderButton($id,$button,$row,$data);
322: $tr['{'.$id.'}']=ob_get_contents();
323: ob_clean();
324: }
325: ob_end_clean();
326: return strtr($this->template,$tr);
327: }
328:
329: /**
330: * Renders a link button.
331: * @param string $id the ID of the button
332: * @param array $button the button configuration which may contain 'label', 'url', 'imageUrl' and 'options' elements.
333: * See {@link buttons} for more details.
334: * @param integer $row the row number (zero-based)
335: * @param mixed $data the data object associated with the row
336: */
337: protected function renderButton($id,$button,$row,$data)
338: {
339: if (isset($button['visible']) && !$this->evaluateExpression($button['visible'],array('row'=>$row,'data'=>$data)))
340: return;
341: $label=isset($button['label']) ? $button['label'] : $id;
342: $url=isset($button['url']) ? $this->evaluateExpression($button['url'],array('data'=>$data,'row'=>$row)) : '#';
343: $options=isset($button['options']) ? $button['options'] : array();
344: if(!isset($options['title']))
345: $options['title']=$label;
346: if(isset($button['imageUrl']) && is_string($button['imageUrl']))
347: echo CHtml::link(CHtml::image($button['imageUrl'],$label),$url,$options);
348: else
349: echo CHtml::link($label,$url,$options);
350: }
351: }
352: