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