lib/pear/HTML/QuickForm/element.php

   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$
  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 ?>