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

   1 <?php
   2 /**
   3  * TCheckBox 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  * TCheckBox class
  14  *
  15  * TCheckBox displays a check box on the page.
  16  * You can specify the caption to display beside the check box by setting
  17  * the {@link setText Text} property.  The caption can appear either on the right
  18  * or left of the check box, which is determined by the {@link setTextAlign TextAlign}
  19  * property.
  20  *
  21  * To determine whether the TCheckBox component is checked, test the {@link getChecked Checked}
  22  * property. The {@link onCheckedChanged OnCheckedChanged} event is raised when
  23  * the {@link getChecked Checked} state of the TCheckBox component changes
  24  * between posts to the server. You can provide an event handler for
  25  * the {@link onCheckedChanged OnCheckedChanged} event to  to programmatically
  26  * control the actions performed when the state of the TCheckBox component changes
  27  * between posts to the server.
  28  *
  29  * If {@link setAutoPostBack AutoPostBack} is set true, changing the check box state
  30  * will cause postback action. And if {@link setCausesValidation CausesValidation}
  31  * is true, validation will also be processed, which can be further restricted within
  32  * a {@link setValidationGroup ValidationGroup}.
  33  *
  34  * Note, {@link setText Text} is rendered as is. Make sure it does not contain unwanted characters
  35  * that may bring security vulnerabilities.
  36  *
  37  * @author Qiang Xue <qiang.xue@gmail.com>
  38  * @package System.Web.UI.WebControls
  39  * @since 3.0
  40  */
  41 class TCheckBox extends TWebControl implements IPostBackDataHandler, IValidatable, IDataRenderer, ISurroundable
  42 {
  43         private $_dataChanged=false;
  44         private $_isValid=true;
  45
  46         /**
  47          * @return string tag name of the button
  48          */
  49         protected function getTagName()
  50         {
  51                 return 'input';
  52         }
  53
  54         /**
  55          * Loads user input data.
  56          * This method is primarly used by framework developers.
  57          * @param string the key that can be used to retrieve data from the input data collection
  58          * @param array the input data collection
  59          * @return boolean whether the data of the control has been changed
  60          */
  61         public function loadPostData($key,$values)
  62         {
  63                 $checked=$this->getChecked();
  64                 if($newChecked=isset($values[$key]))
  65                         $this->setValue($values[$key]);
  66                 $this->setChecked($newChecked);
  67                 return $this->_dataChanged=($newChecked!==$checked);
  68         }
  69
  70         /**
  71          * Raises postdata changed event.
  72          * This method raises {@link onCheckedChanged OnCheckedChanged} event.
  73          * This method is primarly used by framework developers.
  74          */
  75         public function raisePostDataChangedEvent()
  76         {
  77                 if($this->getAutoPostBack() && $this->getCausesValidation())
  78                         $this->getPage()->validate($this->getValidationGroup());
  79                 $this->onCheckedChanged(null);
  80         }
  81
  82         /**
  83          * Raises <b>OnCheckedChanged</b> event when {@link getChecked Checked} changes value during postback.
  84          * If you override this method, be sure to call the parent implementation
  85          * so that the event delegates can be invoked.
  86          * @param TEventParameter event parameter to be passed to the event handlers
  87          */
  88         public function onCheckedChanged($param)
  89         {
  90                 $this->raiseEvent('OnCheckedChanged',$this,$param);
  91         }
  92
  93         /**
  94          * Registers the checkbox to receive postback data during postback.
  95          * This is necessary because a checkbox if unchecked, when postback,
  96          * does not have direct mapping between post data and the checkbox name.
  97          *
  98          * This method overrides the parent implementation and is invoked before render.
  99          * @param mixed event parameter
 100          */
 101         public function onPreRender($param)
 102         {
 103                 parent::onPreRender($param);
 104                 if($this->getEnabled(true))
 105                         $this->getPage()->registerRequiresPostData($this);
 106         }
 107
 108         /**
 109          * Returns a value indicating whether postback has caused the control data change.
 110          * This method is required by the IPostBackDataHandler interface.
 111          * @return boolean whether postback has caused the control data change. False if the page is not in postback mode.
 112          */
 113         public function getDataChanged()
 114         {
 115                 return $this->_dataChanged;
 116         }
 117
 118         /**
 119          * Returns the value of the property that needs validation.
 120          * @return mixed the property value to be validated
 121          */
 122         public function getValidationPropertyValue()
 123         {
 124                 return $this->getChecked();
 125         }
 126
 127         /**
 128          * Returns true if this control validated successfully.
 129          * Defaults to true.
 130          * @return bool wether this control validated successfully.
 131          */
 132         public function getIsValid()
 133         {
 134             return $this->_isValid;
 135         }
 136         /**
 137          * @param bool wether this control is valid.
 138          */
 139         public function setIsValid($value)
 140         {
 141             $this->_isValid=TPropertyValue::ensureBoolean($value);
 142         }
 143
 144         /**
 145          * @return string the text caption of the checkbox
 146          */
 147         public function getText()
 148         {
 149                 return $this->getViewState('Text','');
 150         }
 151
 152         /**
 153          * Sets the text caption of the checkbox.
 154          * @param string the text caption to be set
 155          */
 156         public function setText($value)
 157         {
 158                 $this->setViewState('Text',$value,'');
 159         }
 160
 161         /**
 162          * @return string the value of the checkbox. Defaults to empty.
 163          */
 164         public function getValue()
 165         {
 166                 return $this->getViewState('Value','');
 167         }
 168
 169         /**
 170          * @param string the value of the checkbox
 171          */
 172         public function setValue($value)
 173         {
 174                 $this->setViewState('Value',TPropertyValue::ensureString($value),'');
 175         }
 176
 177         /**
 178          * @return TTextAlign the alignment (Left or Right) of the text caption, defaults to TTextAlign::Right.
 179          */
 180         public function getTextAlign()
 181         {
 182                 return $this->getViewState('TextAlign',TTextAlign::Right);
 183         }
 184
 185         /**
 186          * @param TTextAlign the alignment of the text caption. Valid values include Left and Right.
 187          */
 188         public function setTextAlign($value)
 189         {
 190                 $this->setViewState('TextAlign',TPropertyValue::ensureEnum($value,'TTextAlign'),TTextAlign::Right);
 191         }
 192
 193         /**
 194          * @return boolean whether the checkbox is checked
 195          */
 196         public function getChecked()
 197         {
 198                 return $this->getViewState('Checked',false);
 199         }
 200
 201         /**
 202          * Sets a value indicating whether the checkbox is to be checked or not.
 203          * @param boolean whether the checkbox is to be checked or not.
 204          */
 205         public function setChecked($value)
 206         {
 207                 $this->setViewState('Checked',TPropertyValue::ensureBoolean($value),false);
 208         }
 209
 210         /**
 211          * Returns the value indicating whether the checkbox is checked.
 212          * This method is required by {@link IDataRenderer}.
 213          * It is the same as {@link getChecked()}.
 214          * @return boolean whether the checkbox is checked.
 215          * @see getChecked
 216          * @since 3.1.0
 217          */
 218         public function getData()
 219         {
 220                 return $this->getChecked();
 221         }
 222
 223         /**
 224          * Sets the value indicating whether the checkbox is to be checked or not.
 225          * This method is required by {@link IDataRenderer}.
 226          * It is the same as {@link setChecked()}.
 227          * @param boolean whether the checkbox is to be checked
 228          * @see setChecked
 229          * @since 3.1.0
 230          */
 231         public function setData($value)
 232         {
 233                 $this->setChecked($value);
 234         }
 235
 236         /**
 237          * @return boolean whether clicking on the checkbox will post the page.
 238          */
 239         public function getAutoPostBack()
 240         {
 241                 return $this->getViewState('AutoPostBack',false);
 242         }
 243
 244         /**
 245          * Sets a value indicating whether clicking on the checkbox will post the page.
 246          * @param boolean whether clicking on the checkbox will post the page.
 247          */
 248         public function setAutoPostBack($value)
 249         {
 250                 $this->setViewState('AutoPostBack',TPropertyValue::ensureBoolean($value),false);
 251         }
 252
 253         /**
 254          * @return boolean whether postback event triggered by this checkbox will cause input validation, default is true.
 255          */
 256         public function getCausesValidation()
 257         {
 258                 return $this->getViewState('CausesValidation',true);
 259         }
 260
 261         /**
 262          * Sets the value indicating whether postback event trigger by this checkbox will cause input validation.
 263          * @param boolean whether postback event trigger by this checkbox will cause input validation.
 264          */
 265         public function setCausesValidation($value)
 266         {
 267                 $this->setViewState('CausesValidation',TPropertyValue::ensureBoolean($value),true);
 268         }
 269
 270         /**
 271          * @return string the group of validators which the checkbox causes validation upon postback
 272          */
 273         public function getValidationGroup()
 274         {
 275                 return $this->getViewState('ValidationGroup','');
 276         }
 277
 278         /**
 279          * @param string the group of validators which the checkbox causes validation upon postback
 280          */
 281         public function setValidationGroup($value)
 282         {
 283                 $this->setViewState('ValidationGroup',$value,'');
 284         }
 285
 286         /**
 287          * @return string the id of the surrounding tag or this clientID if no such tag needed
 288          */
 289         public function getSurroundingTagID()
 290         {
 291         return $this->getSpanNeeded() ? $this->getClientID().'_parent' : $this->getClientID();
 292         }
 293
 294         /**
 295          * Renders the checkbox control.
 296          * This method overrides the parent implementation by rendering a checkbox input element
 297          * and a span element if needed.
 298          * @param THtmlWriter the writer used for the rendering purpose
 299          */
 300         public function render($writer)
 301         {
 302                 $this->getPage()->ensureRenderInForm($this);
 303                 if($this->getHasStyle())
 304                         $this->getStyle()->addAttributesToRender($writer);
 305                 if(($tooltip=$this->getToolTip())!=='')
 306                         $writer->addAttribute('title',$tooltip);
 307                 if($this->getHasAttributes())
 308                 {
 309                         $attributes=$this->getAttributes();
 310                         $value=$attributes->remove('value');
 311                         // onclick js should only be added to input tag
 312                         if(($onclick=$attributes->remove('onclick'))===null)
 313                                 $onclick='';
 314                         if($attributes->getCount())
 315                                 $writer->addAttributes($attributes);
 316                         if($value!==null)
 317                                 $attributes->add('value',$value);
 318                 }
 319                 else
 320                         $onclick='';
 321         if($needspan=$this->getSpanNeeded())
 322         {
 323             $writer->addAttribute('id',$this->getSurroundingTagID());
 324                         $writer->renderBeginTag('span');
 325         }
 326                 $clientID=$this->getClientID();
 327                 if(($text=$this->getText())!=='')
 328                 {
 329                         if($this->getTextAlign()===TTextAlign::Left)
 330                         {
 331                                 $this->renderLabel($writer,$clientID,$text);
 332                                 $this->renderInputTag($writer,$clientID,$onclick);
 333                         }
 334                         else
 335                         {
 336                                 $this->renderInputTag($writer,$clientID,$onclick);
 337                                 $this->renderLabel($writer,$clientID,$text);
 338                         }
 339                 }
 340                 else
 341                         $this->renderInputTag($writer,$clientID,$onclick);
 342                 if($needspan)
 343                         $writer->renderEndTag();
 344         }
 345
 346         /**
 347          * @return TMap list of attributes to be rendered for label beside the checkbox
 348          */
 349         public function getLabelAttributes()
 350         {
 351                 if($attributes=$this->getViewState('LabelAttributes',null))
 352                         return $attributes;
 353                 else
 354                 {
 355                         $attributes=new TAttributeCollection;
 356                         $this->setViewState('LabelAttributes',$attributes,null);
 357                         return $attributes;
 358                 }
 359         }
 360
 361         /**
 362          * @return TMap list of attributes to be rendered for the checkbox
 363          */
 364         public function getInputAttributes()
 365         {
 366                 if($attributes=$this->getViewState('InputAttributes',null))
 367                         return $attributes;
 368                 else
 369                 {
 370                         $attributes=new TAttributeCollection;
 371                         $this->setViewState('InputAttributes',$attributes,null);
 372                         return $attributes;
 373                 }
 374         }
 375
 376         /**
 377          * @return string the value attribute to be rendered
 378          */
 379         protected function getValueAttribute()
 380         {
 381                 if(($value=$this->getValue())!=='')
 382                         return $value;
 383                 else
 384                 {
 385                         $attributes=$this->getViewState('InputAttributes',null);
 386                         if($attributes && $attributes->contains('value'))
 387                                 return $attributes->itemAt('value');
 388                         else if($this->hasAttribute('value'))
 389                                 return $this->getAttribute('value');
 390                         else
 391                                 return '';
 392                 }
 393         }
 394
 395         /**
 396          * @return boolean whether to render javascript.
 397          */
 398         public function getEnableClientScript()
 399         {
 400                 return $this->getViewState('EnableClientScript',true);
 401         }
 402
 403         /**
 404          * @param boolean whether to render javascript.
 405          */
 406         public function setEnableClientScript($value)
 407         {
 408                 $this->setViewState('EnableClientScript',TPropertyValue::ensureBoolean($value),true);
 409         }
 410
 411     /**
 412      * Check if we need a span tag to surround this control. The span tag will be created if
 413      * the Text property is set for this control.
 414      *
 415      * @return bool wether this control needs a surrounding span tag
 416      */
 417     protected function getSpanNeeded() {
 418         return $this->getText()!=='';
 419     }
 420
 421         /**
 422          * Renders a label beside the checkbox.
 423          * @param THtmlWriter the writer for the rendering purpose
 424          * @param string checkbox id
 425          * @param string label text
 426          */
 427         protected function renderLabel($writer,$clientID,$text)
 428         {
 429                 $writer->addAttribute('for',$clientID);
 430                 if($attributes=$this->getViewState('LabelAttributes',null))
 431                         $writer->addAttributes($attributes);
 432                 $writer->renderBeginTag('label');
 433                 $writer->write($text);
 434                 $writer->renderEndTag();
 435         }
 436
 437         /**
 438          * Renders a checkbox input element.
 439          * @param THtmlWriter the writer for the rendering purpose
 440          * @param string checkbox id
 441          * @param string onclick js
 442          */
 443         protected function renderInputTag($writer,$clientID,$onclick)
 444         {
 445                 if($clientID!=='')
 446                         $writer->addAttribute('id',$clientID);
 447                 $writer->addAttribute('type','checkbox');
 448                 if(($value=$this->getValueAttribute())!=='')
 449                         $writer->addAttribute('value',$value);
 450                 if(!empty($onclick))
 451                         $writer->addAttribute('onclick',$onclick);
 452                 if(($uniqueID=$this->getUniqueID())!=='')
 453                         $writer->addAttribute('name',$uniqueID);
 454                 if($this->getChecked())
 455                         $writer->addAttribute('checked','checked');
 456                 if(!$this->getEnabled(true))
 457                         $writer->addAttribute('disabled','disabled');
 458
 459                 $page=$this->getPage();
 460                 if($this->getEnabled(true)
 461                         && $this->getEnableClientScript()
 462                         && $this->getAutoPostBack()
 463                         && $page->getClientSupportsJavaScript())
 464                 {
 465                         $this->renderClientControlScript($writer);
 466                 }
 467
 468                 if(($accesskey=$this->getAccessKey())!=='')
 469                         $writer->addAttribute('accesskey',$accesskey);
 470                 if(($tabindex=$this->getTabIndex())>0)
 471                         $writer->addAttribute('tabindex',"$tabindex");
 472                 if($attributes=$this->getViewState('InputAttributes',null))
 473                         $writer->addAttributes($attributes);
 474                 $writer->renderBeginTag('input');
 475                 $writer->renderEndTag();
 476         }
 477
 478         /**
 479          * Renders the client-script code.
 480          */
 481         protected function renderClientControlScript($writer)
 482         {
 483                 $cs = $this->getPage()->getClientScript();
 484                 $cs->registerPostBackControl($this->getClientClassName(),$this->getPostBackOptions());
 485         }
 486
 487         /**
 488          * Gets the name of the javascript class responsible for performing postback for this control.
 489          * This method overrides the parent implementation.
 490          * @return string the javascript class name
 491          */
 492         protected function getClientClassName()
 493         {
 494                 return 'Prado.WebUI.TCheckBox';
 495         }
 496
 497         /**
 498          * Gets the post back options for this checkbox.
 499          * @return array
 500          */
 501         protected function getPostBackOptions()
 502         {
 503                 $options['ID'] = $this->getClientID();
 504                 $options['ValidationGroup'] = $this->getValidationGroup();
 505                 $options['CausesValidation'] = $this->getCausesValidation();
 506                 $options['EventTarget'] = $this->getUniqueID();
 507                 return $options;
 508         }
 509 }
 510
 511 /**
 512  * TTextAlign class.
 513  * TTextAlign defines the enumerable type for the possible text alignments
 514  *
 515  * The following enumerable values are defined:
 516  * - Left: left aligned
 517  * - Right: right aligned
 518  *
 519  * @author Qiang Xue <qiang.xue@gmail.com>
 520  * @package System.Web.UI.WebControls
 521  * @since 3.0.4
 522  */
 523 class TTextAlign extends TEnumerable
 524 {
 525         const Left='Left';
 526         const Right='Right';
 527 }
 528