[Sommaire] [Imprimer]

   1  <?php
   2  /* vim: set expandtab tabstop=4 shiftwidth=4: */
   3  // +----------------------------------------------------------------------+
   4  // | PHP version 4.0                                                      |
   5  // +----------------------------------------------------------------------+
   6  // | Copyright (c) 1997, 1998, 1999, 2000, 2001 The PHP Group             |
   7  // +----------------------------------------------------------------------+
   8  // | This source file is subject to version 2.0 of the PHP license,       |
   9  // | that is bundled with this package in the file LICENSE, and is        |
  10  // | available at through the world-wide-web at                           |
  11  // | http://www.php.net/license/2_02.txt.                                 |
  12  // | If you did not receive a copy of the PHP license and are unable to   |
  13  // | obtain it through the world-wide-web, please send a note to          |
  14  // | license@php.net so we can mail you a copy immediately.               |
  15  // +----------------------------------------------------------------------+
  16  // | Authors: Adam Daniel <adaniel1@eesus.jnj.com>                        |
  17  // |          Bertrand Mansion <bmansion@mamasam.com>                     |
  18  // +----------------------------------------------------------------------+
  19  //
  20  // $Id: element.php,v 1.1 2005/12/06 01:50:39 matthieu_ Exp $
  21  
  22  require_once('Html/Common.php');
  23  
  24  /**
  25   * Base class for form elements
  26   * 
  27   * @author       Adam Daniel <adaniel1@eesus.jnj.com>
  28   * @author       Bertrand Mansion <bmansion@mamasam.com>
  29   * @version      1.3
  30   * @since        PHP4.04pl1
  31   * @access       public
  32   * @abstract
  33   */
  34  class HTML_QuickForm_element extends HTML_Common
  35  {
  36      // {{{ properties
  37  
  38      /**
  39       * Label of the field
  40       * @var       string
  41       * @since     1.3
  42       * @access    private
  43       */
  44      var $_label = '';
  45  
  46      /**
  47       * Form element type
  48       * @var       string
  49       * @since     1.0
  50       * @access    private
  51       */
  52      var $_type = '';
  53  
  54      /**
  55       * Flag to tell if element is frozen
  56       * @var       boolean
  57       * @since     1.0
  58       * @access    private
  59       */
  60      var $_flagFrozen = false;
  61  
  62      /**
  63       * Does the element support persistant data when frozen
  64       * @var       boolean
  65       * @since     1.3
  66       * @access    private
  67       */
  68      var $_persistantFreeze = false;
  69      
  70      // }}}
  71      // {{{ constructor
  72      
  73      /**
  74       * Class constructor
  75       * 
  76       * @param    string     Name of the element
  77       * @param    mixed      Label(s) for the element
  78       * @param    mixed      Associative array of tag attributes or HTML attributes name="value" pairs
  79       * @since     1.0
  80       * @access    public
  81       * @return    void
  82       */
  83      function HTML_QuickForm_element($elementName=null, $elementLabel=null, $attributes=null)
  84      {
  85          HTML_Common::HTML_Common($attributes);
  86          if (isset($elementName)) {
  87              $this->setName($elementName);
  88          }
  89          if (isset($elementLabel)) {
  90              $this->setLabel($elementLabel);
  91          }
  92      } //end constructor
  93      
  94      // }}}
  95      // {{{ apiVersion()
  96  
  97      /**
  98       * Returns the current API version
  99       *
 100       * @since     1.0
 101       * @access    public
 102       * @return    float
 103       */
 104      function apiVersion()
 105      {
 106          return 2.0;
 107      } // end func apiVersion
 108  
 109      // }}}
 110      // {{{ getType()
 111  
 112      /**
 113       * Returns element type
 114       *
 115       * @since     1.0
 116       * @access    public
 117       * @return    string
 118       */
 119      function getType()
 120      {
 121          return $this->_type;
 122      } // end func getType
 123  
 124      // }}}
 125      // {{{ setName()
 126  
 127      /**
 128       * Sets the input field name
 129       * 
 130       * @param     string    $name   Input field name attribute
 131       * @since     1.0
 132       * @access    public
 133       * @return    void
 134       */
 135      function setName($name)
 136      {
 137          // interface method
 138      } //end func setName
 139      
 140      // }}}
 141      // {{{ getName()
 142  
 143      /**
 144       * Returns the element name
 145       * 
 146       * @since     1.0
 147       * @access    public
 148       * @return    string
 149       */
 150      function getName()
 151      {
 152          // interface method
 153      } //end func getName
 154      
 155      // }}}
 156      // {{{ setValue()
 157  
 158      /**
 159       * Sets the value of the form element
 160       *
 161       * @param     string    $value      Default value of the form element
 162       * @since     1.0
 163       * @access    public
 164       * @return    void
 165       */
 166      function setValue($value)
 167      {
 168          // interface
 169      } // end func setValue
 170  
 171      // }}}
 172      // {{{ getValue()
 173  
 174      /**
 175       * Returns the value of the form element
 176       *
 177       * @since     1.0
 178       * @access    public
 179       * @return    mixed
 180       */
 181      function getValue()
 182      {
 183          // interface
 184          return null;
 185      } // end func getValue
 186      
 187      // }}}
 188      // {{{ freeze()
 189  
 190      /**
 191       * Freeze the element so that only its value is returned
 192       * 
 193       * @access    public
 194       * @return    void
 195       */
 196      function freeze()
 197      {
 198          $this->_flagFrozen = true;
 199      } //end func freeze
 200  
 201      // }}}
 202      // {{{ unfreeze()
 203  
 204     /**
 205      * Unfreezes the element so that it becomes editable
 206      *
 207      * @access public
 208      * @return void
 209      * @since  3.2.4
 210      */
 211      function unfreeze()
 212      {
 213          $this->_flagFrozen = false;
 214      }
 215  
 216      // }}}
 217      // {{{ getFrozenHtml()
 218  
 219      /**
 220       * Returns the value of field without HTML tags
 221       * 
 222       * @since     1.0
 223       * @access    public
 224       * @return    string
 225       */
 226      function getFrozenHtml()
 227      {
 228          $value = $this->getValue();
 229          return ('' != $value? htmlspecialchars($value): '&nbsp;') .
 230                 $this->_getPersistantData();
 231      } //end func getFrozenHtml
 232      
 233      // }}}
 234      // {{{ _getPersistantData()
 235  
 236     /**
 237      * Used by getFrozenHtml() to pass the element's value if _persistantFreeze is on
 238      * 
 239      * @access private
 240      * @return string
 241      */
 242      function _getPersistantData()
 243      {
 244          if (!$this->_persistantFreeze) {
 245              return '';
 246          } else {
 247              $id = $this->getAttribute('id');
 248              return '<input' . $this->_getAttrString(array(
 249                         'type'  => 'hidden',
 250                         'name'  => $this->getName(),
 251                         'value' => $this->getValue()
 252                     ) + (isset($id)? array('id' => $id): array())) . ' />';
 253          }
 254      }
 255  
 256      // }}}
 257      // {{{ isFrozen()
 258  
 259      /**
 260       * Returns whether or not the element is frozen
 261       *
 262       * @since     1.3
 263       * @access    public
 264       * @return    bool
 265       */
 266      function isFrozen()
 267      {
 268          return $this->_flagFrozen;
 269      } // end func isFrozen
 270  
 271      // }}}
 272      // {{{ setPersistantFreeze()
 273  
 274      /**
 275       * Sets wether an element value should be kept in an hidden field
 276       * when the element is frozen or not
 277       * 
 278       * @param     bool    $persistant   True if persistant value
 279       * @since     2.0
 280       * @access    public
 281       * @return    void
 282       */
 283      function setPersistantFreeze($persistant=false)
 284      {
 285          $this->_persistantFreeze = $persistant;
 286      } //end func setPersistantFreeze
 287  
 288      // }}}
 289      // {{{ setLabel()
 290  
 291      /**
 292       * Sets display text for the element
 293       * 
 294       * @param     string    $label  Display text for the element
 295       * @since     1.3
 296       * @access    public
 297       * @return    void
 298       */
 299      function setLabel($label)
 300      {
 301          $this->_label = $label;
 302      } //end func setLabel
 303  
 304      // }}}
 305      // {{{ getLabel()
 306  
 307      /**
 308       * Returns display text for the element
 309       * 
 310       * @since     1.3
 311       * @access    public
 312       * @return    string
 313       */
 314      function getLabel()
 315      {
 316          return $this->_label;
 317      } //end func getLabel
 318  
 319      // }}}
 320      // {{{ _findValue()
 321  
 322      /**
 323       * Tries to find the element value from the values array
 324       * 
 325       * @since     2.7
 326       * @access    private
 327       * @return    mixed
 328       */
 329      function _findValue(&$values)
 330      {
 331          if (empty($values)) {
 332              return null;
 333          }
 334          $elementName = $this->getName();
 335          if (isset($values[$elementName])) {
 336              return $values[$elementName];
 337          } elseif (strpos($elementName, '[')) {
 338              $myVar = "['" . str_replace(array(']', '['), array('', "']['"), $elementName) . "']";
 339              return eval("return (isset(\$values$myVar)) ? \$values$myVar : null;");
 340          } else {
 341              return null;
 342          }
 343      } //end func _findValue
 344  
 345      // }}}
 346      // {{{ onQuickFormEvent()
 347  
 348      /**
 349       * Called by HTML_QuickForm whenever form event is made on this element
 350       *
 351       * @param     string    $event  Name of event
 352       * @param     mixed     $arg    event arguments
 353       * @param     object    $caller calling object
 354       * @since     1.0
 355       * @access    public
 356       * @return    void
 357       */
 358      function onQuickFormEvent($event, $arg, &$caller)
 359      {
 360          switch ($event) {
 361              case 'createElement':
 362                  $className = get_class($this);
 363                  $this->$className($arg[0], $arg[1], $arg[2], $arg[3], $arg[4]);
 364                  break;
 365              case 'addElement':
 366                  $this->onQuickFormEvent('createElement', $arg, $caller);
 367                  $this->onQuickFormEvent('updateValue', null, $caller);
 368                  break;
 369              case 'updateValue':
 370                  // constant values override both default and submitted ones
 371                  // default values are overriden by submitted
 372                  $value = $this->_findValue($caller->_constantValues);
 373                  if (null === $value) {
 374                      $value = $this->_findValue($caller->_submitValues);
 375                      if (null === $value) {
 376                          $value = $this->_findValue($caller->_defaultValues);
 377                      }
 378                  }
 379                  if (null !== $value) {
 380                      $this->setValue($value);
 381                  }
 382                  break;
 383              case 'setGroupValue':
 384                  $this->setValue($arg);
 385          }
 386          return true;
 387      } // end func onQuickFormEvent
 388  
 389      // }}}
 390      // {{{ accept()
 391  
 392     /**
 393      * Accepts a renderer
 394      *
 395      * @param object     An HTML_QuickForm_Renderer object
 396      * @param bool       Whether an element is required
 397      * @param string     An error message associated with an element
 398      * @access public
 399      * @return void 
 400      */
 401      function accept(&$renderer, $required=false, $error=null)
 402      {
 403          $renderer->renderElement($this, $required, $error);
 404      } // end func accept
 405  
 406      // }}}
 407      // {{{ _generateId()
 408  
 409     /**
 410      * Automatically generates and assigns an 'id' attribute for the element.
 411      * 
 412      * Currently used to ensure that labels work on radio buttons and
 413      * checkboxes. Per idea of Alexander Radivanovich.
 414      *
 415      * @access private
 416      * @return void 
 417      */
 418      function _generateId()
 419      {
 420          static $idx = 1;
 421  
 422          if (!$this->getAttribute('id')) {
 423              $this->updateAttributes(array('id' => 'qf_' . substr(md5(microtime() . $idx++), 0, 6)));
 424          }
 425      } // end func _generateId
 426  
 427      // }}}
 428      // {{{ exportValue()
 429  
 430     /**
 431      * Returns a 'safe' element's value
 432      *
 433      * @param  array   array of submitted values to search
 434      * @param  bool    whether to return the value as associative array
 435      * @access public
 436      * @return mixed
 437      */
 438      function exportValue(&$submitValues, $assoc = false)
 439      {
 440          $value = $this->_findValue($submitValues);
 441          if (null === $value) {
 442              $value = $this->getValue();
 443          }
 444          return $this->_prepareValue($value, $assoc);
 445      }
 446      
 447      // }}}
 448      // {{{ _prepareValue()
 449  
 450     /**
 451      * Used by exportValue() to prepare the value for returning
 452      *
 453      * @param  mixed   the value found in exportValue()
 454      * @param  bool    whether to return the value as associative array
 455      * @access private
 456      * @return mixed
 457      */
 458      function _prepareValue($value, $assoc)
 459      {
 460          if (null === $value) {
 461              return null;
 462          } elseif (!$assoc) {
 463              return $value;
 464          } else {
 465              $name = $this->getName();
 466              if (!strpos($name, '[')) {
 467                  return array($name => $value);
 468              } else {
 469                  $valueAry = array();
 470                  $myIndex  = "['" . str_replace(array(']', '['), array('', "']['"), $name) . "']";
 471                  eval("\$valueAry$myIndex = \$value;");
 472                  return $valueAry;
 473              }
 474          }
 475      }
 476      
 477      // }}}
 478  } // end class HTML_QuickForm_element
 479  ?>