git.sur5r.net Git - bacula/bacula/blob - gui/baculum/framework/Web/UI/WebControls/TButton.php

   1 <?php
   2 /**
   3  * TButton class file.
   4  *
   5  * @author Qiang Xue <qiang.xue@gmail.com>
   6  * @link http://www.pradosoft.com/
   7  * @copyright Copyright &copy; 2005-2014 PradoSoft
   8  * @license http://www.pradosoft.com/license/
   9  * @package System.Web.UI.WebControls
  10  */
  11
  12 /**
  13  * TButton class
  14  *
  15  * TButton creates a click button on the page. It is mainly used to submit data to a page.
  16  *
  17  * TButton raises two server-side events, {@link onClick OnClick} and {@link onCommand OnCommand},
  18  * when it is clicked on the client-side. The difference between these two events
  19  * is that the event {@link onCommand OnCommand} is bubbled up to the button's ancestor controls.
  20  * And within the event parameter for {@link onCommand OnCommand} contains the reference
  21  * to the {@link setCommandName CommandName} and {@link setCommandParameter CommandParameter}
  22  * property values that are set for the button object. This allows you to create multiple TButton
  23  * components on a Web page and programmatically determine which one is clicked
  24  * with what parameter.
  25  *
  26  * Clicking on button can also trigger form validation, if
  27  * {@link setCausesValidation CausesValidation} is true.
  28  * The validation may be restricted within a certain group of validator
  29  * controls by setting {@link setValidationGroup ValidationGroup} property.
  30  * If validation is successful, the data will be post back to the same page.
  31  *
  32  * TButton displays the {@link setText Text} property as the button caption.
  33  *
  34  * TButton can be one of three {@link setButtonType ButtonType}: Submit, Button and Reset.
  35  * By default, it is a Submit button and the form submission uses the browser's
  36  * default submission capability. If it is Button or Reset, postback may occur
  37  * if one of the following conditions is met:
  38  * - an event handler is attached to {@link onClick OnClick} event;
  39  * - an event handler is attached to {@link onCommand OnCommand} event;
  40  * - the button is in a non-empty validation group.
  41  * In addition, clicking on a Reset button will clear up all input fields
  42  * if the button does not cause a postback.
  43  *
  44  * @author Qiang Xue <qiang.xue@gmail.com>
  45  * @package System.Web.UI.WebControls
  46  * @since 3.0
  47  */
  48 class TButton extends TWebControl implements IPostBackEventHandler, IButtonControl, IDataRenderer
  49 {
  50         /**
  51          * @return string tag name of the button
  52          */
  53         protected function getTagName()
  54         {
  55                 return 'input';
  56         }
  57
  58         /**
  59          * @return boolean whether to render javascript.
  60          */
  61         public function getEnableClientScript()
  62         {
  63                 return $this->getViewState('EnableClientScript',true);
  64         }
  65
  66         /**
  67          * @param boolean whether to render javascript.
  68          */
  69         public function setEnableClientScript($value)
  70         {
  71                 $this->setViewState('EnableClientScript',TPropertyValue::ensureBoolean($value),true);
  72         }
  73
  74         /**
  75          * Adds attribute name-value pairs to renderer.
  76          * This overrides the parent implementation with additional button specific attributes.
  77          * @param THtmlWriter the writer used for the rendering purpose
  78          */
  79         protected function addAttributesToRender($writer)
  80         {
  81                 $page=$this->getPage();
  82                 $page->ensureRenderInForm($this);
  83                 $writer->addAttribute('type',strtolower($this->getButtonType()));
  84                 if(($uniqueID=$this->getUniqueID())!=='')
  85                         $writer->addAttribute('name',$uniqueID);
  86                 $writer->addAttribute('value',$this->getText());
  87                 if($this->getEnabled(true))
  88                 {
  89                         if($this->getEnableClientScript() && $this->needPostBackScript())
  90                                 $this->renderClientControlScript($writer);
  91                 }
  92                 else if($this->getEnabled()) // in this case, parent will not render 'disabled'
  93                         $writer->addAttribute('disabled','disabled');
  94
  95                 parent::addAttributesToRender($writer);
  96         }
  97
  98         /**
  99          * Renders the client-script code.
 100          */
 101         protected function renderClientControlScript($writer)
 102         {
 103                 $writer->addAttribute('id',$this->getClientID());
 104                 $this->getPage()->getClientScript()->registerPostBackControl($this->getClientClassName(),$this->getPostBackOptions());
 105         }
 106
 107         /**
 108          * Gets the name of the javascript class responsible for performing postback for this control.
 109          * This method overrides the parent implementation.
 110          * @return string the javascript class name
 111          */
 112         protected function getClientClassName()
 113         {
 114                 return 'Prado.WebUI.TButton';
 115         }
 116
 117         /**
 118          * @return boolean whether to perform validation if the button is clicked
 119          */
 120         protected function canCauseValidation()
 121         {
 122                 if($this->getCausesValidation())
 123                 {
 124                         $group=$this->getValidationGroup();
 125                         return $this->getPage()->getValidators($group)->getCount()>0;
 126                 }
 127                 else
 128                         return false;
 129         }
 130
 131         /**
 132          * @param boolean set by a panel to register this button as the default button for the panel.
 133          */
 134         public function setIsDefaultButton($value)
 135         {
 136                 $this->setViewState('IsDefaultButton', TPropertyValue::ensureBoolean($value),false);
 137         }
 138
 139         /**
 140          * @return boolean true if this button is registered as a default button for a panel.
 141          */
 142         public function getIsDefaultButton()
 143         {
 144                 return $this->getViewState('IsDefaultButton', false);
 145         }
 146
 147         /**
 148          * @return boolean whether the button needs javascript to do postback
 149          */
 150         protected function needPostBackScript()
 151         {
 152                 return $this->canCauseValidation() || ($this->getButtonType()!==TButtonType::Submit &&
 153                         ($this->hasEventHandler('OnClick') || $this->hasEventHandler('OnCommand')))
 154                         || $this->getIsDefaultButton();
 155         }
 156
 157         /**
 158          * Returns postback specifications for the button.
 159          * This method is used by framework and control developers.
 160          * @return array parameters about how the button defines its postback behavior.
 161          */
 162         protected function getPostBackOptions()
 163         {
 164                 $options['ID']=$this->getClientID();
 165                 $options['CausesValidation']=$this->getCausesValidation();
 166                 $options['EventTarget'] = $this->getUniqueID();
 167                 $options['ValidationGroup']=$this->getValidationGroup();
 168
 169                 return $options;
 170         }
 171
 172         /**
 173          * Renders the body content enclosed between the control tag.
 174          * This overrides the parent implementation with nothing to be rendered.
 175          * @param THtmlWriter the writer used for the rendering purpose
 176          */
 177         public function renderContents($writer)
 178         {
 179         }
 180
 181         /**
 182          * This method is invoked when the button is clicked.
 183          * The method raises 'OnClick' event to fire up the event handlers.
 184          * If you override this method, be sure to call the parent implementation
 185          * so that the event handler can be invoked.
 186          * @param TEventParameter event parameter to be passed to the event handlers
 187          */
 188         public function onClick($param)
 189         {
 190                 $this->raiseEvent('OnClick',$this,$param);
 191         }
 192
 193         /**
 194          * This method is invoked when the button is clicked.
 195          * The method raises 'OnCommand' event to fire up the event handlers.
 196          * If you override this method, be sure to call the parent implementation
 197          * so that the event handlers can be invoked.
 198          * @param TCommandEventParameter event parameter to be passed to the event handlers
 199          */
 200         public function onCommand($param)
 201         {
 202                 $this->raiseEvent('OnCommand',$this,$param);
 203                 $this->raiseBubbleEvent($this,$param);
 204         }
 205
 206         /**
 207          * Raises the postback event.
 208          * This method is required by {@link IPostBackEventHandler} interface.
 209          * If {@link getCausesValidation CausesValidation} is true, it will
 210          * invoke the page's {@link TPage::validate validate} method first.
 211          * It will raise {@link onClick OnClick} and {@link onCommand OnCommand} events.
 212          * This method is mainly used by framework and control developers.
 213          * @param TEventParameter the event parameter
 214          */
 215         public function raisePostBackEvent($param)
 216         {
 217                 if($this->getCausesValidation())
 218                         $this->getPage()->validate($this->getValidationGroup());
 219                 $this->onClick(null);
 220                 $this->onCommand(new TCommandEventParameter($this->getCommandName(),$this->getCommandParameter()));
 221         }
 222
 223         /**
 224          * @return string caption of the button
 225          */
 226         public function getText()
 227         {
 228                 return $this->getViewState('Text','');
 229         }
 230
 231         /**
 232          * @param string caption of the button
 233          */
 234         public function setText($value)
 235         {
 236                 $this->setViewState('Text',$value,'');
 237         }
 238
 239         /**
 240          * Returns the caption of the button.
 241          * This method is required by {@link IDataRenderer}.
 242          * It is the same as {@link getText()}.
 243          * @return string caption of the button.
 244          * @see getText
 245          * @since 3.1.0
 246          */
 247         public function getData()
 248         {
 249                 return $this->getText();
 250         }
 251
 252         /**
 253          * Sets the caption of the button.
 254          * This method is required by {@link IDataRenderer}.
 255          * It is the same as {@link setText()}.
 256          * @param string caption of the button
 257          * @see setText
 258          * @since 3.1.0
 259          */
 260         public function setData($value)
 261         {
 262                 $this->setText($value);
 263         }
 264
 265         /**
 266          * @return boolean whether postback event trigger by this button will cause input validation, default is true
 267          */
 268         public function getCausesValidation()
 269         {
 270                 return $this->getViewState('CausesValidation',true);
 271         }
 272
 273         /**
 274          * @param boolean whether postback event trigger by this button will cause input validation
 275          */
 276         public function setCausesValidation($value)
 277         {
 278                 $this->setViewState('CausesValidation',TPropertyValue::ensureBoolean($value),true);
 279         }
 280
 281         /**
 282          * @return string the command name associated with the {@link onCommand OnCommand} event.
 283          */
 284         public function getCommandName()
 285         {
 286                 return $this->getViewState('CommandName','');
 287         }
 288
 289         /**
 290          * @param string the command name associated with the {@link onCommand OnCommand} event.
 291          */
 292         public function setCommandName($value)
 293         {
 294                 $this->setViewState('CommandName',$value,'');
 295         }
 296
 297         /**
 298          * @return string the parameter associated with the {@link onCommand OnCommand} event
 299          */
 300         public function getCommandParameter()
 301         {
 302                 return $this->getViewState('CommandParameter','');
 303         }
 304
 305         /**
 306          * @param string the parameter associated with the {@link onCommand OnCommand} event.
 307          */
 308         public function setCommandParameter($value)
 309         {
 310                 $this->setViewState('CommandParameter',$value,'');
 311         }
 312
 313         /**
 314          * @return string the group of validators which the button causes validation upon postback
 315          */
 316         public function getValidationGroup()
 317         {
 318                 return $this->getViewState('ValidationGroup','');
 319         }
 320
 321         /**
 322          * @param string the group of validators which the button causes validation upon postback
 323          */
 324         public function setValidationGroup($value)
 325         {
 326                 $this->setViewState('ValidationGroup',$value,'');
 327         }
 328
 329         /**
 330          * @return TButtonType the type of the button. Defaults to TButtonType::Submit.
 331          */
 332         public function getButtonType()
 333         {
 334                 return $this->getViewState('ButtonType',TButtonType::Submit);
 335         }
 336
 337         /**
 338          * @param TButtonType the type of the button.
 339          */
 340         public function setButtonType($value)
 341         {
 342                 $this->setViewState('ButtonType',TPropertyValue::ensureEnum($value,'TButtonType'),TButtonType::Submit);
 343         }
 344 }
 345
 346 /**
 347  * TButtonType class.
 348  * TButtonType defines the enumerable type for the possible types that a {@link TButton} can take.
 349  *
 350  * The following enumerable values are defined:
 351  * - Submit: a normal submit button
 352  * - Reset: a reset button
 353  * - Button: a client button (normally does not perform form submission)
 354  *
 355  * @author Qiang Xue <qiang.xue@gmail.com>
 356  * @package System.Web.UI.WebControls
 357  * @since 3.0.4
 358  */
 359 class TButtonType extends TEnumerable
 360 {
 361         const Submit='Submit';
 362         const Reset='Reset';
 363         const Button='Button';
 364 }
 365