[Sommaire] [Imprimer]

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