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

Source for file group.php

Documentation is available at group.php

  1. <?php
  2. /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
  3.  
  4. /**
  5.  * HTML class for a form element group
  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: group.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 form elements
  28.  */ 
  29. require_once 'HTML/QuickForm/element.php';
  30.  
  31. /**
  32.  * HTML class for a form element group
  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.  */
  42. {
  43.     // {{{ properties
  44.         
  45.     /**
  46.      * Name of the element
  47.      * @var       string 
  48.      * @since     1.0
  49.      * @access    private
  50.      */
  51.     var $_name '';
  52.  
  53.     /**
  54.      * Array of grouped elements
  55.      * @var       array 
  56.      * @since     1.0
  57.      * @access    private
  58.      */
  59.     var $_elements = array();
  60.  
  61.     /**
  62.      * String to separate elements
  63.      * @var       mixed 
  64.      * @since     2.5
  65.      * @access    private
  66.      */
  67.     var $_separator = null;
  68.  
  69.     /**
  70.      * Required elements in this group
  71.      * @var       array 
  72.      * @since     2.5
  73.      * @access    private
  74.      */
  75.     var $_required = array();
  76.  
  77.    /**
  78.     * Whether to change elements' names to $groupName[$elementName] or leave them as is
  79.     * @var      bool 
  80.     * @since    3.0
  81.     * @access   private
  82.     */
  83.     var $_appendName = true;
  84.  
  85.     // }}}
  86.     // {{{ constructor
  87.  
  88.     /**
  89.      * Class constructor
  90.      * 
  91.      * @param     string    $elementName    (optional)Group name
  92.      * @param     array     $elementLabel   (optional)Group label
  93.      * @param     array     $elements       (optional)Group elements
  94.      * @param     mixed     $separator      (optional)Use a string for one separator,
  95.      *                                       use an array to alternate the separators.
  96.      * @param     bool      $appendName     (optional)whether to change elements' names to
  97.      *                                       the form $groupName[$elementName] or leave
  98.      *                                       them as is.
  99.      * @since     1.0
  100.      * @access    public
  101.      * @return    void 
  102.      */
  103.     function HTML_QuickForm_group($elementName=null$elementLabel=null$elements=null$separator=null$appendName = true)
  104.     {
  105.         $this->HTML_QuickForm_element($elementName$elementLabel);
  106.         $this->_type 'group';
  107.         if (isset($elements&& is_array($elements)) {
  108.             $this->setElements($elements);
  109.         }
  110.         if (isset($separator)) {
  111.             $this->_separator $separator;
  112.         }
  113.         if (isset($appendName)) {
  114.             $this->_appendName $appendName;
  115.         }
  116.     //end constructor
  117.     
  118.     // }}}
  119.     // {{{ setName()
  120.  
  121.     /**
  122.      * Sets the group name
  123.      * 
  124.      * @param     string    $name   Group name
  125.      * @since     1.0
  126.      * @access    public
  127.      * @return    void 
  128.      */
  129.     function setName($name)
  130.     {
  131.         $this->_name $name;
  132.     //end func setName
  133.     
  134.     // }}}
  135.     // {{{ getName()
  136.  
  137.     /**
  138.      * Returns the group name
  139.      * 
  140.      * @since     1.0
  141.      * @access    public
  142.      * @return    string 
  143.      */
  144.     function getName()
  145.     {
  146.         return $this->_name;
  147.     //end func getName
  148.  
  149.     // }}}
  150.     // {{{ setValue()
  151.  
  152.     /**
  153.      * Sets values for group's elements
  154.      * 
  155.      * @param     mixed    Values for group's elements
  156.      * @since     1.0
  157.      * @access    public
  158.      * @return    void 
  159.      */
  160.     function setValue($value)
  161.     {
  162.         $this->_createElementsIfNotExist();
  163.         foreach (array_keys($this->_elementsas $key{
  164.             if (!$this->_appendName{
  165.                 $v $this->_elements[$key]->_findValue($value);
  166.                 if (null !== $v{
  167.                     $this->_elements[$key]->onQuickFormEvent('setGroupValue'$v$this);
  168.                 }
  169.  
  170.             else {
  171.                 $elementName $this->_elements[$key]->getName();
  172.                 $index       strlen($elementName$elementName $key;
  173.                 if (is_array($value)) {
  174.                     if (isset($value[$index])) {
  175.                         $this->_elements[$key]->onQuickFormEvent('setGroupValue'$value[$index]$this);
  176.                     }
  177.                 elseif (isset($value)) {
  178.                     $this->_elements[$key]->onQuickFormEvent('setGroupValue'$value$this);
  179.                 }
  180.             }
  181.         }
  182.     //end func setValue
  183.     
  184.     // }}}
  185.     // {{{ getValue()
  186.  
  187.     /**
  188.      * Returns the value of the group
  189.      *
  190.      * @since     1.0
  191.      * @access    public
  192.      * @return    mixed 
  193.      */
  194.     function getValue()
  195.     {
  196.         $value = null;
  197.         foreach (array_keys($this->_elementsas $key{
  198.             $element =$this->_elements[$key];
  199.             switch ($element->getType()) {
  200.                 case 'radio'
  201.                     $v $element->getChecked()$element->getValue(): null;
  202.                     break;
  203.                 case 'checkbox'
  204.                     $v $element->getChecked()? true: null;
  205.                     break;
  206.                 default:
  207.                     $v $element->getValue();
  208.             }
  209.             if (null !== $v{
  210.                 $elementName $element->getName();
  211.                 if (is_null($elementName)) {
  212.                     $value $v;
  213.                 else {
  214.                     if (!is_array($value)) {
  215.                         $value is_null($value)? array(): array($value);
  216.                     }
  217.                     if ('' === $elementName{
  218.                         $value[$v;
  219.                     else {
  220.                         $value[$elementName$v;
  221.                     }
  222.                 }
  223.             }
  224.         }
  225.         return $value;
  226.     // end func getValue
  227.  
  228.     // }}}
  229.     // {{{ setElements()
  230.  
  231.     /**
  232.      * Sets the grouped elements
  233.      *
  234.      * @param     array     $elements   Array of elements
  235.      * @since     1.1
  236.      * @access    public
  237.      * @return    void 
  238.      */
  239.     function setElements($elements)
  240.     {
  241.         $this->_elements array_values($elements);
  242.         if ($this->_flagFrozen{
  243.             $this->freeze();
  244.         }
  245.     // end func setElements
  246.  
  247.     // }}}
  248.     // {{{ getElements()
  249.  
  250.     /**
  251.      * Gets the grouped elements
  252.      *
  253.      * @since     2.4
  254.      * @access    public
  255.      * @return    array 
  256.      */
  257.     function &getElements()
  258.     {
  259.         $this->_createElementsIfNotExist();
  260.         return $this->_elements;
  261.     // end func getElements
  262.  
  263.     // }}}
  264.     // {{{ getGroupType()
  265.  
  266.     /**
  267.      * Gets the group type based on its elements
  268.      * Will return 'mixed' if elements contained in the group
  269.      * are of different types.
  270.      *
  271.      * @access    public
  272.      * @return    string    group elements type
  273.      */
  274.     function getGroupType()
  275.     {
  276.         $this->_createElementsIfNotExist();
  277.         $prevType '';
  278.         foreach (array_keys($this->_elementsas $key{
  279.             $type $this->_elements[$key]->getType();
  280.             if ($type != $prevType && $prevType != ''{
  281.                 return 'mixed';
  282.             }
  283.             $prevType $type;
  284.         }
  285.         return $type;
  286.     // end func getGroupType
  287.  
  288.     // }}}
  289.     // {{{ toHtml()
  290.  
  291.     /**
  292.      * Returns Html for the group
  293.      * 
  294.      * @since       1.0
  295.      * @access      public
  296.      * @return      string 
  297.      */
  298.     function toHtml()
  299.     {
  300.         include_once('HTML/QuickForm/Renderer/Default.php');
  301.         $renderer =new HTML_QuickForm_Renderer_Default();
  302.         $renderer->setElementTemplate('{element}');
  303.         $this->accept($renderer);
  304.         return $renderer->toHtml();
  305.     //end func toHtml
  306.     
  307.     // }}}
  308.     // {{{ getElementName()
  309.  
  310.     /**
  311.      * Returns the element name inside the group such as found in the html form
  312.      * 
  313.      * @param     mixed     $index  Element name or element index in the group
  314.      * @since     3.0
  315.      * @access    public
  316.      * @return    mixed     string with element name, false if not found
  317.      */
  318.     function getElementName($index)
  319.     {
  320.         $this->_createElementsIfNotExist();
  321.         $elementName = false;
  322.         if (is_int($index&& isset($this->_elements[$index])) {
  323.             $elementName $this->_elements[$index]->getName();
  324.             if (isset($elementName&& $elementName == ''{
  325.                 $elementName $index;
  326.             }
  327.             if ($this->_appendName{
  328.                 if (is_null($elementName)) {
  329.                     $elementName $this->getName();
  330.                 else {
  331.                     $elementName $this->getName().'['.$elementName.']';
  332.                 }
  333.             }
  334.  
  335.         elseif (is_string($index)) {
  336.             foreach (array_keys($this->_elementsas $key{
  337.                 $elementName $this->_elements[$key]->getName();
  338.                 if ($index == $elementName{
  339.                     if ($this->_appendName{
  340.                         $elementName $this->getName().'['.$elementName.']';
  341.                     }
  342.                     break;
  343.                 elseif ($this->_appendName && $this->getName().'['.$elementName.']' == $index{
  344.                     break;
  345.                 }
  346.             }
  347.         }
  348.         return $elementName;
  349.     //end func getElementName
  350.  
  351.     // }}}
  352.     // {{{ getFrozenHtml()
  353.  
  354.     /**
  355.      * Returns the value of field without HTML tags
  356.      * 
  357.      * @since     1.3
  358.      * @access    public
  359.      * @return    string 
  360.      */
  361.     function getFrozenHtml()
  362.     {
  363.         $flags = array();
  364.         $this->_createElementsIfNotExist();
  365.         foreach (array_keys($this->_elementsas $key{
  366.             if (false === ($flags[$key$this->_elements[$key]->isFrozen())) {
  367.                 $this->_elements[$key]->freeze();
  368.             }
  369.         }
  370.         $html $this->toHtml();
  371.         foreach (array_keys($this->_elementsas $key{
  372.             if (!$flags[$key]{
  373.                 $this->_elements[$key]->unfreeze();
  374.             }
  375.         }
  376.         return $html;
  377.     //end func getFrozenHtml
  378.  
  379.     // }}}
  380.     // {{{ onQuickFormEvent()
  381.  
  382.     /**
  383.      * Called by HTML_QuickForm whenever form event is made on this element
  384.      *
  385.      * @param     string    $event  Name of event
  386.      * @param     mixed     $arg    event arguments
  387.      * @param     object    &$caller calling object
  388.      * @since     1.0
  389.      * @access    public
  390.      * @return    void 
  391.      */
  392.     function onQuickFormEvent($event$arg&$caller)
  393.     {
  394.         switch ($event{
  395.             case 'updateValue':
  396.                 $this->_createElementsIfNotExist();
  397.                 foreach (array_keys($this->_elementsas $key{
  398.                     if ($this->_appendName{
  399.                         $elementName $this->_elements[$key]->getName();
  400.                         if (is_null($elementName)) {
  401.                             $this->_elements[$key]->setName($this->getName());
  402.                         elseif ('' === $elementName{
  403.                             $this->_elements[$key]->setName($this->getName('[' $key ']');
  404.                         else {
  405.                             $this->_elements[$key]->setName($this->getName('[' $elementName ']');
  406.                         }
  407.                     }
  408.                     $this->_elements[$key]->onQuickFormEvent('updateValue'$arg$caller);
  409.                     if ($this->_appendName{
  410.                         $this->_elements[$key]->setName($elementName);
  411.                     }
  412.                 }
  413.                 break;
  414.  
  415.             default:
  416.                 parent::onQuickFormEvent($event$arg$caller);
  417.         }
  418.         return true;
  419.     // end func onQuickFormEvent
  420.  
  421.     // }}}
  422.     // {{{ accept()
  423.  
  424.    /**
  425.     * Accepts a renderer
  426.     *
  427.     * @param HTML_QuickForm_Renderer    renderer object
  428.     * @param bool                       Whether a group is required
  429.     * @param string                     An error message associated with a group
  430.     * @access public
  431.     * @return void 
  432.     */
  433.     function accept(&$renderer$required = false$error = null)
  434.     {
  435.         $this->_createElementsIfNotExist();
  436.         $renderer->startGroup($this$required$error);
  437.         $name $this->getName();
  438.         foreach (array_keys($this->_elementsas $key{
  439.             $element =$this->_elements[$key];
  440.             
  441.             if ($this->_appendName{
  442.                 $elementName $element->getName();
  443.                 if (isset($elementName)) {
  444.                     $element->setName($name '['(strlen($elementName)$elementName$key.']');
  445.                 else {
  446.                     $element->setName($name);
  447.                 }
  448.             }
  449.  
  450.             $required !$element->isFrozen(&& in_array($element->getName()$this->_required);
  451.  
  452.             $element->accept($renderer$required);
  453.  
  454.             // restore the element's name
  455.             if ($this->_appendName{
  456.                 $element->setName($elementName);
  457.             }
  458.         }
  459.         $renderer->finishGroup($this);
  460.     // end func accept
  461.  
  462.     // }}}
  463.     // {{{ exportValue()
  464.  
  465.    /**
  466.     * As usual, to get the group's value we access its elements and call
  467.     * their exportValue() methods
  468.     */
  469.     function exportValue(&$submitValues$assoc = false)
  470.     {
  471.         $value = null;
  472.         foreach (array_keys($this->_elementsas $key{
  473.             $elementName $this->_elements[$key]->getName();
  474.             if ($this->_appendName{
  475.                 if (is_null($elementName)) {
  476.                     $this->_elements[$key]->setName($this->getName());
  477.                 elseif ('' === $elementName{
  478.                     $this->_elements[$key]->setName($this->getName('[' $key ']');
  479.                 else {
  480.                     $this->_elements[$key]->setName($this->getName('[' $elementName ']');
  481.                 }
  482.             }
  483.             $v $this->_elements[$key]->exportValue($submitValues$assoc);
  484.             if ($this->_appendName{
  485.                 $this->_elements[$key]->setName($elementName);
  486.             }
  487.             if (null !== $v{
  488.                 // Make $value an array, we will use it like one
  489.                 if (null === $value{
  490.                     $value = array();
  491.                 }
  492.                 if ($assoc{
  493.                     // just like HTML_QuickForm::exportValues()
  494.                     $value HTML_QuickForm::arrayMerge($value$v);
  495.                 else {
  496.                     // just like getValue(), but should work OK every time here
  497.                     if (is_null($elementName)) {
  498.                         $value $v;
  499.                     elseif ('' === $elementName{
  500.                         $value[$v;
  501.                     else {
  502.                         $value[$elementName$v;
  503.                     }
  504.                 }
  505.             }
  506.         }
  507.         // do not pass the value through _prepareValue, we took care of this already
  508.         return $value;
  509.     }
  510.  
  511.     // }}}
  512.     // {{{ _createElements()
  513.  
  514.    /**
  515.     * Creates the group's elements.
  516.     * 
  517.     * This should be overriden by child classes that need to create their
  518.     * elements. The method will be called automatically when needed, calling
  519.     * it from the constructor is discouraged as the constructor is usually
  520.     * called _twice_ on element creation, first time with _no_ parameters.
  521.     * 
  522.     * @access private
  523.     * @abstract
  524.     */
  525.     function _createElements()
  526.     {
  527.         // abstract
  528.     }
  529.  
  530.     // }}}
  531.     // {{{ _createElementsIfNotExist()
  532.  
  533.    /**
  534.     * A wrapper around _createElements()
  535.     *
  536.     * This method calls _createElements() if the group's _elements array
  537.     * is empty. It also performs some updates, e.g. freezes the created
  538.     * elements if the group is already frozen.
  539.     *
  540.     * @access private
  541.     */
  542.     function _createElementsIfNotExist()
  543.     {
  544.         if (empty($this->_elements)) {
  545.             $this->_createElements();
  546.             if ($this->_flagFrozen{
  547.                 $this->freeze();
  548.             }
  549.         }
  550.     }
  551.  
  552.     // }}}
  553.     // {{{ freeze()
  554.  
  555.     function freeze()
  556.     {
  557.         parent::freeze();
  558.         foreach (array_keys($this->_elementsas $key{
  559.             $this->_elements[$key]->freeze();
  560.         }
  561.     }
  562.  
  563.     // }}}
  564.     // {{{ unfreeze()
  565.  
  566.     function unfreeze()
  567.     {
  568.         parent::unfreeze();
  569.         foreach (array_keys($this->_elementsas $key{
  570.             $this->_elements[$key]->unfreeze();
  571.         }
  572.     }
  573.  
  574.     // }}}
  575.     // {{{ setPersistantFreeze()
  576.  
  577.     function setPersistantFreeze($persistant = false)
  578.     {
  579.         parent::setPersistantFreeze($persistant);
  580.         foreach (array_keys($this->_elementsas $key{
  581.             $this->_elements[$key]->setPersistantFreeze($persistant);
  582.         }
  583.     }
  584.  
  585.     // }}}
  586. //end class HTML_QuickForm_group
  587. ?>

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