HTML_QuickForm
[ class tree: HTML_QuickForm ] [ index: HTML_QuickForm ] [ all elements ]

Source for file element.php

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

Documentation generated on Sat, 01 Oct 2011 09:00:09 +0000 by phpDocumentor 1.4.3. PEAR Logo Copyright © PHP Group 2004.