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