cookbooks/dmca/files/default/html/HTML/QuickForm/element.php

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