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

   1 <?php
   2 /**
   3  * TImageButton class file
   4  *
   5  * @author Qiang Xue <qiang.xue@gmail.com>
   6  * @link https://github.com/pradosoft/prado
   7  * @copyright Copyright &copy; 2005-2016 The PRADO Group
   8  * @license https://github.com/pradosoft/prado/blob/master/COPYRIGHT
   9  * @package System.Web.UI.WebControls
  10  */
  11
  12 /**
  13  * Includes TImage class file
  14  */
  15 Prado::using('System.Web.UI.WebControls.TImage');
  16
  17 /**
  18  * TImageButton class
  19  *
  20  * TImageButton creates an image button on the page. It is used to submit data to a page.
  21  * You can create either a <b>submit</b> button or a <b>command</b> button.
  22  *
  23  * A <b>command</b> button has a command name (specified by
  24  * the {@link setCommandName CommandName} property) and and a command parameter
  25  * (specified by {@link setCommandParameter CommandParameter} property)
  26  * associated with the button. This allows you to create multiple TLinkButton
  27  * components on a Web page and programmatically determine which one is clicked
  28  * with what parameter. You can provide an event handler for
  29  * {@link onCommand OnCommand} event to programmatically control the actions performed
  30  * when the command button is clicked. In the event handler, you can determine
  31  * the {@link setCommandName CommandName} property value and
  32  * the {@link setCommandParameter CommandParameter} property value
  33  * through the {@link TCommandParameter::getName Name} and
  34  * {@link TCommandParameter::getParameter Parameter} properties of the event
  35  * parameter which is of type {@link TCommandEventParameter}.
  36  *
  37  * A <b>submit</b> button does not have a command name associated with the button
  38  * and clicking on it simply posts the Web page back to the server.
  39  * By default, a TImageButton control is a submit button.
  40  * You can provide an event handler for the {@link onClick OnClick} event
  41  * to programmatically control the actions performed when the submit button is clicked.
  42  * The coordinates of the clicking point can be obtained from the {@link onClick OnClick}
  43  * event parameter, which is of type {@link TImageClickEventParameter}.
  44  *
  45  * Clicking on button can trigger form validation, if
  46  * {@link setCausesValidation CausesValidation} is true.
  47  * And the validation may be restricted within a certain group of validator
  48  * controls by setting {@link setValidationGroup ValidationGroup} property.
  49  * If validation is successful, the data will be post back to the same page.
  50  *
  51  * TImageButton displays the {@link setText Text} property as the hint text to the displayed image.
  52  *
  53  * @author Qiang Xue <qiang.xue@gmail.com>
  54  * @package System.Web.UI.WebControls
  55  * @since 3.0
  56  */
  57 class TImageButton extends TImage implements IPostBackDataHandler, IPostBackEventHandler, IButtonControl
  58 {
  59         /**
  60          * @var integer x coordinate that the image is being clicked at
  61          */
  62         private $_x=0;
  63         /**
  64          * @var integer y coordinate that the image is being clicked at
  65          */
  66         private $_y=0;
  67         private $_dataChanged=false;
  68
  69         /**
  70          * @return string tag name of the button
  71          */
  72         protected function getTagName()
  73         {
  74                 return 'input';
  75         }
  76
  77         /**
  78          * @return boolean whether to render javascript.
  79          */
  80         public function getEnableClientScript()
  81         {
  82                 return $this->getViewState('EnableClientScript',true);
  83         }
  84
  85         /**
  86          * @param boolean whether to render javascript.
  87          */
  88         public function setEnableClientScript($value)
  89         {
  90                 $this->setViewState('EnableClientScript',TPropertyValue::ensureBoolean($value),true);
  91         }
  92
  93         /**
  94          * Adds attribute name-value pairs to renderer.
  95          * This overrides the parent implementation with additional button specific attributes.
  96          * @param THtmlWriter the writer used for the rendering purpose
  97          */
  98         protected function addAttributesToRender($writer)
  99         {
 100                 $page=$this->getPage();
 101                 $page->ensureRenderInForm($this);
 102                 $writer->addAttribute('type','image');
 103                 if(($uniqueID=$this->getUniqueID())!=='')
 104                         $writer->addAttribute('name',$uniqueID);
 105                 if($this->getEnabled(true))
 106                 {
 107                         if($this->getEnableClientScript() && $this->needPostBackScript())
 108                                 $this->renderClientControlScript($writer);
 109                 }
 110                 else if($this->getEnabled()) // in this case, parent will not render 'disabled'
 111                         $writer->addAttribute('disabled','disabled');
 112                 parent::addAttributesToRender($writer);
 113         }
 114
 115         /**
 116          * Renders the client-script code.
 117          */
 118         protected function renderClientControlScript($writer)
 119         {
 120                 $writer->addAttribute('id',$this->getClientID());
 121                 $cs = $this->getPage()->getClientScript();
 122                 $cs->registerPostBackControl($this->getClientClassName(),$this->getPostBackOptions());
 123         }
 124
 125         /**
 126          * Gets the name of the javascript class responsible for performing postback for this control.
 127          * This method overrides the parent implementation.
 128          * @return string the javascript class name
 129          */
 130         protected function getClientClassName()
 131         {
 132                 return 'Prado.WebUI.TImageButton';
 133         }
 134
 135         /**
 136          * @return boolean whether to perform validation if the button is clicked
 137          */
 138         protected function canCauseValidation()
 139         {
 140                 if($this->getCausesValidation())
 141                 {
 142                         $group=$this->getValidationGroup();
 143                         return $this->getPage()->getValidators($group)->getCount()>0;
 144                 }
 145                 else
 146                         return false;
 147         }
 148
 149         /**
 150          * @param boolean set by a panel to register this button as the default button for the panel.
 151          */
 152         public function setIsDefaultButton($value)
 153         {
 154                 $this->setViewState('IsDefaultButton', TPropertyValue::ensureBoolean($value),false);
 155         }
 156
 157         /**
 158          * @return boolean true if this button is registered as a default button for a panel.
 159          */
 160         public function getIsDefaultButton()
 161         {
 162                 return $this->getViewState('IsDefaultButton', false);
 163         }
 164
 165         /**
 166          * @return boolean whether the button needs javascript to do postback
 167          */
 168         protected function needPostBackScript()
 169         {
 170                 return $this->canCauseValidation() || $this->getIsDefaultButton();
 171         }
 172
 173         /**
 174          * Returns postback specifications for the button.
 175          * This method is used by framework and control developers.
 176          * @return array parameters about how the button defines its postback behavior.
 177          */
 178         protected function getPostBackOptions()
 179         {
 180                 $options['ID'] = $this->getClientID();
 181                 $options['CausesValidation'] = $this->getCausesValidation();
 182                 $options['ValidationGroup'] = $this->getValidationGroup();
 183                 $options['EventTarget'] = $this->getUniqueID();
 184
 185                 return $options;
 186         }
 187
 188         /**
 189          * This method checks if the TImageButton is clicked and loads the coordinates of the clicking position.
 190          * This method is primarly used by framework developers.
 191          * @param string the key that can be used to retrieve data from the input data collection
 192          * @param array the input data collection
 193          * @return boolean whether the data of the component has been changed
 194          */
 195         public function loadPostData($key,$values)
 196         {
 197                 $uid=$this->getUniqueID();
 198                 if(isset($values["{$uid}_x"]) && isset($values["{$uid}_y"]))
 199                 {
 200                         $this->_x=intval($values["{$uid}_x"]);
 201                         $this->_y=intval($values["{$uid}_y"]);
 202                         if($this->getPage()->getPostBackEventTarget()===null)
 203                                 $this->getPage()->setPostBackEventTarget($this);
 204                         $this->_dataChanged=true;
 205                 }
 206                 return false;
 207         }
 208
 209         /**
 210          * A dummy implementation for the IPostBackDataHandler interface.
 211          */
 212         public function raisePostDataChangedEvent()
 213         {
 214                 // no post data to handle
 215         }
 216
 217         /**
 218          * This method is invoked when the button is clicked.
 219          * The method raises 'OnClick' event to fire up the event handlers.
 220          * If you override this method, be sure to call the parent implementation
 221          * so that the event handler can be invoked.
 222          * @param TImageClickEventParameter event parameter to be passed to the event handlers
 223          */
 224         public function onClick($param)
 225         {
 226                 $this->raiseEvent('OnClick',$this,$param);
 227         }
 228
 229         /**
 230          * This method is invoked when the button is clicked.
 231          * The method raises 'OnCommand' event to fire up the event handlers.
 232          * If you override this method, be sure to call the parent implementation
 233          * so that the event handlers can be invoked.
 234          * @param TCommandEventParameter event parameter to be passed to the event handlers
 235          */
 236         public function onCommand($param)
 237         {
 238                 $this->raiseEvent('OnCommand',$this,$param);
 239                 $this->raiseBubbleEvent($this,$param);
 240         }
 241
 242         /**
 243          * Raises the postback event.
 244          * This method is required by {@link IPostBackEventHandler} interface.
 245          * If {@link getCausesValidation CausesValidation} is true, it will
 246          * invoke the page's {@link TPage::validate validate} method first.
 247          * It will raise {@link onClick OnClick} and {@link onCommand OnCommand} events.
 248          * This method is mainly used by framework and control developers.
 249          * @param TEventParameter the event parameter
 250          */
 251         public function raisePostBackEvent($param)
 252         {
 253                 if($this->getCausesValidation())
 254                         $this->getPage()->validate($this->getValidationGroup());
 255                 $this->onClick(new TImageClickEventParameter($this->_x,$this->_y));
 256                 $this->onCommand(new TCommandEventParameter($this->getCommandName(),$this->getCommandParameter()));
 257         }
 258
 259         /**
 260          * Returns a value indicating whether postback has caused the control data change.
 261          * This method is required by the IPostBackDataHandler interface.
 262          * @return boolean whether postback has caused the control data change. False if the page is not in postback mode.
 263          */
 264         public function getDataChanged()
 265         {
 266                 return $this->_dataChanged;
 267         }
 268
 269         /**
 270          * @return boolean whether postback event trigger by this button will cause input validation, default is true
 271          */
 272         public function getCausesValidation()
 273         {
 274                 return $this->getViewState('CausesValidation',true);
 275         }
 276
 277         /**
 278          * @param boolean whether postback event trigger by this button will cause input validation
 279          */
 280         public function setCausesValidation($value)
 281         {
 282                 $this->setViewState('CausesValidation',TPropertyValue::ensureBoolean($value),true);
 283         }
 284
 285         /**
 286          * @return string the command name associated with the {@link onCommand OnCommand} event.
 287          */
 288         public function getCommandName()
 289         {
 290                 return $this->getViewState('CommandName','');
 291         }
 292
 293         /**
 294          * @param string the command name associated with the {@link onCommand OnCommand} event.
 295          */
 296         public function setCommandName($value)
 297         {
 298                 $this->setViewState('CommandName',$value,'');
 299         }
 300
 301         /**
 302          * @return string the parameter associated with the {@link onCommand OnCommand} event
 303          */
 304         public function getCommandParameter()
 305         {
 306                 return $this->getViewState('CommandParameter','');
 307         }
 308
 309         /**
 310          * @param string the parameter associated with the {@link onCommand OnCommand} event.
 311          */
 312         public function setCommandParameter($value)
 313         {
 314                 $this->setViewState('CommandParameter',$value,'');
 315         }
 316
 317         /**
 318          * @return string the group of validators which the button causes validation upon postback
 319          */
 320         public function getValidationGroup()
 321         {
 322                 return $this->getViewState('ValidationGroup','');
 323         }
 324
 325         /**
 326          * @param string the group of validators which the button causes validation upon postback
 327          */
 328         public function setValidationGroup($value)
 329         {
 330                 $this->setViewState('ValidationGroup',$value,'');
 331         }
 332
 333         /**
 334          * @return string caption of the button
 335          */
 336         public function getText()
 337         {
 338                 return $this->getAlternateText();
 339         }
 340
 341         /**
 342          * @param string caption of the button
 343          */
 344         public function setText($value)
 345         {
 346                 $this->setAlternateText($value);
 347         }
 348
 349         /**
 350          * Registers the image button to receive postback data during postback.
 351          * This is necessary because an image button, when postback, does not have
 352          * direct mapping between post data and the image button name.
 353          * This method overrides the parent implementation and is invoked before render.
 354          * @param mixed event parameter
 355          */
 356         public function onPreRender($param)
 357         {
 358                 parent::onPreRender($param);
 359                 $this->getPage()->registerRequiresPostData($this);
 360         }
 361
 362         /**
 363          * Renders the body content enclosed between the control tag.
 364          * This overrides the parent implementation with nothing to be rendered.
 365          * @param THtmlWriter the writer used for the rendering purpose
 366          */
 367         public function renderContents($writer)
 368         {
 369         }
 370 }
 371
 372 /**
 373  * TImageClickEventParameter class
 374  *
 375  * TImageClickEventParameter encapsulates the parameter data for
 376  * {@link TImageButton::onClick Click} event of {@link TImageButton} controls.
 377  *
 378  * @author Qiang Xue <qiang.xue@gmail.com>
 379  * @package System.Web.UI.WebControls
 380  * @since 3.0
 381  */
 382 class TImageClickEventParameter extends TEventParameter
 383 {
 384         /**
 385          * the X coordinate of the clicking point
 386          * @var integer
 387          */
 388         private $_x=0;
 389         /**
 390          * the Y coordinate of the clicking point
 391          * @var integer
 392          */
 393         private $_y=0;
 394
 395         /**
 396          * Constructor.
 397          * @param integer X coordinate of the clicking point
 398          * @param integer Y coordinate of the clicking point
 399          */
 400         public function __construct($x,$y)
 401         {
 402                 $this->_x=$x;
 403                 $this->_y=$y;
 404         }
 405
 406         /**
 407          * @return integer X coordinate of the clicking point, defaults to 0
 408          */
 409         public function getX()
 410         {
 411                 return $this->_x;
 412         }
 413
 414         /**
 415          * @param integer X coordinate of the clicking point
 416          */
 417         public function setX($value)
 418         {
 419                 $this->_x=TPropertyValue::ensureInteger($value);
 420         }
 421
 422         /**
 423          * @return integer Y coordinate of the clicking point, defaults to 0
 424          */
 425         public function getY()
 426         {
 427                 return $this->_y;
 428         }
 429
 430         /**
 431          * @param integer Y coordinate of the clicking point
 432          */
 433         public function setY($value)
 434         {
 435                 $this->_y=TPropertyValue::ensureInteger($value);
 436         }
 437 }
 438