lib/pear/HTML/QuickForm/Renderer/Array.php

   1 <?php
   2 /* vim: set expandtab tabstop=4 shiftwidth=4: */
   3 // +----------------------------------------------------------------------+
   4 // | PHP version 4.0                                                      |
   5 // +----------------------------------------------------------------------+
   6 // | Copyright (c) 1997-2003 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: Alexey Borzov <borz_off@cs.msu.su>                          |
  17 // |          Adam Daniel <adaniel1@eesus.jnj.com>                        |
  18 // |          Bertrand Mansion <bmansion@mamasam.com>                     |
  19 // |          Thomas Schulz <ths@4bconsult.de>                            |
  20 // +----------------------------------------------------------------------+
  21 //
  22 // $Id$
  23
  24 require_once 'HTML/QuickForm/Renderer.php';
  25
  26 /**
  27  * A concrete renderer for HTML_QuickForm, makes an array of form contents
  28  *
  29  * Based on old toArray() code.
  30  *
  31  * The form array structure is the following:
  32  * array(
  33  *   'frozen'           => 'whether the form is frozen',
  34  *   'javascript'       => 'javascript for client-side validation',
  35  *   'attributes'       => 'attributes for <form> tag',
  36  *   'requirednote      => 'note about the required elements',
  37  *   // if we set the option to collect hidden elements
  38  *   'hidden'           => 'collected html of all hidden elements',
  39  *   // if there were some validation errors:
  40  *   'errors' => array(
  41  *     '1st element name' => 'Error for the 1st element',
  42  *     ...
  43  *     'nth element name' => 'Error for the nth element'
  44  *   ),
  45  *   // if there are no headers in the form:
  46  *   'elements' => array(
  47  *     element_1,
  48  *     ...
  49  *     element_N
  50  *   )
  51  *   // if there are headers in the form:
  52  *   'sections' => array(
  53  *     array(
  54  *       'header'   => 'Header text for the first header',
  55  *       'name'     => 'Header name for the first header',
  56  *       'elements' => array(
  57  *          element_1,
  58  *          ...
  59  *          element_K1
  60  *       )
  61  *     ),
  62  *     ...
  63  *     array(
  64  *       'header'   => 'Header text for the Mth header',
  65  *       'name'     => 'Header name for the Mth header',
  66  *       'elements' => array(
  67  *          element_1,
  68  *          ...
  69  *          element_KM
  70  *       )
  71  *     )
  72  *   )
  73  * );
  74  *
  75  * where element_i is an array of the form:
  76  * array(
  77  *   'name'      => 'element name',
  78  *   'value'     => 'element value',
  79  *   'type'      => 'type of the element',
  80  *   'frozen'    => 'whether element is frozen',
  81  *   'label'     => 'label for the element',
  82  *   'required'  => 'whether element is required',
  83  *   'error'     => 'error associated with the element',
  84  *   'style'     => 'some information about element style (e.g. for Smarty)',
  85  *   // if element is not a group
  86  *   'html'      => 'HTML for the element'
  87  *   // if element is a group
  88  *   'separator' => 'separator for group elements',
  89  *   'elements'  => array(
  90  *     element_1,
  91  *     ...
  92  *     element_N
  93  *   )
  94  * );
  95  *
  96  * @access public
  97  */
  98 class HTML_QuickForm_Renderer_Array extends HTML_QuickForm_Renderer
  99 {
 100    /**
 101     * An array being generated
 102     * @var array
 103     */
 104     var $_ary;
 105
 106    /**
 107     * Number of sections in the form (i.e. number of headers in it)
 108     * @var integer
 109     */
 110     var $_sectionCount;
 111
 112    /**
 113     * Current section number
 114     * @var integer
 115     */
 116     var $_currentSection;
 117
 118    /**
 119     * Array representing current group
 120     * @var array
 121     */
 122     var $_currentGroup = null;
 123
 124    /**
 125     * Additional style information for different elements
 126     * @var array
 127     */
 128     var $_elementStyles = array();
 129
 130    /**
 131     * true: collect all hidden elements into string; false: process them as usual form elements
 132     * @var bool
 133     */
 134     var $_collectHidden = false;
 135
 136    /**
 137     * true:  render an array of labels to many labels, $key 0 named 'label', the rest "label_$key"
 138     * false: leave labels as defined
 139     * @var bool
 140     */
 141     var $staticLabels = false;
 142
 143    /**
 144     * Constructor
 145     *
 146     * @param  bool    true: collect all hidden elements into string; false: process them as usual form elements
 147     * @param  bool    true: render an array of labels to many labels, $key 0 to 'label' and the oterh to "label_$key"
 148     * @access public
 149     */
 150     function HTML_QuickForm_Renderer_Array($collectHidden = false, $staticLabels = false)
 151     {
 152         $this->HTML_QuickForm_Renderer();
 153         $this->_collectHidden = $collectHidden;
 154         $this->_staticLabels  = $staticLabels;
 155     } // end constructor
 156
 157
 158    /**
 159     * Returns the resultant array
 160     *
 161     * @access public
 162     * @return array
 163     */
 164     function toArray()
 165     {
 166         return $this->_ary;
 167     }
 168
 169
 170     function startForm(&$form)
 171     {
 172         $this->_ary = array(
 173             'frozen'            => $form->isFrozen(),
 174             'javascript'        => $form->getValidationScript(),
 175             'attributes'        => $form->getAttributes(true),
 176             'requirednote'      => $form->getRequiredNote(),
 177             'errors'            => array()
 178         );
 179         if ($this->_collectHidden) {
 180             $this->_ary['hidden'] = '';
 181         }
 182         $this->_elementIdx     = 1;
 183         $this->_currentSection = null;
 184         $this->_sectionCount   = 0;
 185     } // end func startForm
 186
 187
 188     function renderHeader(&$header)
 189     {
 190         $this->_ary['sections'][$this->_sectionCount] = array(
 191             'header' => $header->toHtml(),
 192             'name'   => $header->getName()
 193         );
 194         $this->_currentSection = $this->_sectionCount++;
 195     } // end func renderHeader
 196
 197
 198     function renderElement(&$element, $required, $error)
 199     {
 200         $elAry = $this->_elementToArray($element, $required, $error);
 201         if (!empty($error)) {
 202             $this->_ary['errors'][$elAry['name']] = $error;
 203         }
 204         $this->_storeArray($elAry);
 205     } // end func renderElement
 206
 207
 208     function renderHidden(&$element)
 209     {
 210         if ($this->_collectHidden) {
 211             $this->_ary['hidden'] .= $element->toHtml() . "\n";
 212         } else {
 213             $this->renderElement($element, false, null);
 214         }
 215     } // end func renderHidden
 216
 217
 218     function startGroup(&$group, $required, $error)
 219     {
 220         $this->_currentGroup = $this->_elementToArray($group, $required, $error);
 221         if (!empty($error)) {
 222             $this->_ary['errors'][$this->_currentGroup['name']] = $error;
 223         }
 224     } // end func startGroup
 225
 226
 227     function finishGroup(&$group)
 228     {
 229         $this->_storeArray($this->_currentGroup);
 230         $this->_currentGroup = null;
 231     } // end func finishGroup
 232
 233
 234    /**
 235     * Creates an array representing an element
 236     *
 237     * @access private
 238     * @param  object    An HTML_QuickForm_element object
 239     * @param  bool      Whether an element is required
 240     * @param  string    Error associated with the element
 241     * @return array
 242     */
 243     function _elementToArray(&$element, $required, $error)
 244     {
 245         $ret = array(
 246             'name'      => $element->getName(),
 247             'value'     => $element->getValue(),
 248             'type'      => $element->getType(),
 249             'frozen'    => $element->isFrozen(),
 250             'required'  => $required,
 251             'error'     => $error
 252         );
 253         // render label(s)
 254         $labels = $element->getLabel();
 255         if (is_array($labels) && $this->_staticLabels) {
 256             foreach($labels as $key => $label) {
 257                 $key = is_int($key)? $key + 1: $key;
 258                 if (1 === $key) {
 259                     $ret['label'] = $label;
 260                 } else {
 261                     $ret['label_' . $key] = $label;
 262                 }
 263             }
 264         } else {
 265             $ret['label'] = $labels;
 266         }
 267
 268         // set the style for the element
 269         if (isset($this->_elementStyles[$ret['name']])) {
 270             $ret['style'] = $this->_elementStyles[$ret['name']];
 271         }
 272         if ('group' == $ret['type']) {
 273             $ret['separator'] = $element->_separator;
 274             $ret['elements']  = array();
 275         } else {
 276             $ret['html']      = $element->toHtml();
 277         }
 278         return $ret;
 279     }
 280
 281
 282    /**
 283     * Stores an array representation of an element in the form array
 284     *
 285     * @access private
 286     * @param array  Array representation of an element
 287     * @return void
 288     */
 289     function _storeArray($elAry)
 290     {
 291         // where should we put this element...
 292         if (is_array($this->_currentGroup) && ('group' != $elAry['type'])) {
 293             $this->_currentGroup['elements'][] = $elAry;
 294         } elseif (isset($this->_currentSection)) {
 295             $this->_ary['sections'][$this->_currentSection]['elements'][] = $elAry;
 296         } else {
 297             $this->_ary['elements'][] = $elAry;
 298         }
 299     }
 300
 301
 302    /**
 303     * Sets a style to use for element rendering
 304     *
 305     * @param mixed      element name or array ('element name' => 'style name')
 306     * @param string     style name if $elementName is not an array
 307     * @access public
 308     * @return void
 309     */
 310     function setElementStyle($elementName, $styleName = null)
 311     {
 312         if (is_array($elementName)) {
 313             $this->_elementStyles = array_merge($this->_elementStyles, $elementName);
 314         } else {
 315             $this->_elementStyles[$elementName] = $styleName;
 316         }
 317     }
 318 }
 319 ?>