crm.fsf.org/20131203/files/sites/all/modules-old/civicrm/packages/HTML/QuickForm/Page.php

   1 <?php
   2 /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
   3
   4 /**
   5  * Class representing a page of a multipage form.
   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_Controller
  17  * @author      Alexey Borzov <avb@php.net>
  18  * @author      Bertrand Mansion <bmansion@mamasam.com>
  19  * @copyright   2003-2007 The PHP Group
  20  * @license     http://www.php.net/license/3_01.txt PHP License 3.01
  21  * @version     CVS: $Id: Page.php,v 1.7 2007/05/18 09:34:18 avb Exp $
  22  * @link        http://pear.php.net/package/HTML_QuickForm_Controller
  23  */
  24
  25 /**
  26  * Create, validate and process HTML forms
  27  */
  28 require_once 'HTML/QuickForm.php';
  29
  30 /**
  31  * Class representing a page of a multipage form.
  32  *
  33  * Generally you'll need to subclass this and define your buildForm()
  34  * method that will build the form. While it is also possible to instantiate
  35  * this class and build the form manually, this is not the recommended way.
  36  *
  37  * @category    HTML
  38  * @package     HTML_QuickForm_Controller
  39  * @author      Alexey Borzov <avb@php.net>
  40  * @author      Bertrand Mansion <bmansion@mamasam.com>
  41  * @version     Release: 1.0.9
  42  */
  43 class HTML_QuickForm_Page extends HTML_QuickForm
  44 {
  45    /**
  46     * Contains the mapping of actions to corresponding HTML_QuickForm_Action objects
  47     * @var array
  48     */
  49     var $_actions = array();
  50
  51    /**
  52     * Contains a reference to a Controller object containing this page
  53     * @var      HTML_QuickForm_Controller
  54     * @access   public
  55     */
  56     var $controller = null;
  57
  58    /**
  59     * Should be set to true on first call to buildForm()
  60     * @var bool
  61     */
  62     var $_formBuilt = false;
  63
  64    /**
  65     * Class constructor
  66     *
  67     * @access public
  68     */
  69     function HTML_QuickForm_Page($formName, $method = 'post', $target = '', $attributes = null)
  70     {
  71         $this->HTML_QuickForm($formName, $method, '', $target, $attributes);
  72     }
  73
  74
  75    /**
  76     * Registers a handler for a specific action.
  77     *
  78     * @access public
  79     * @param  string                name of the action
  80     * @param  HTML_QuickForm_Action the handler for the action
  81     */
  82     function addAction($actionName, &$action)
  83     {
  84         $this->_actions[$actionName] =& $action;
  85     }
  86
  87
  88    /**
  89     * Handles an action.
  90     *
  91     * If an Action object was not registered here, controller's handle()
  92     * method will be called.
  93     *
  94     * @access public
  95     * @param  string Name of the action
  96     * @throws PEAR_Error
  97     */
  98     function handle($actionName)
  99     {
 100         if (isset($this->_actions[$actionName])) {
 101             return $this->_actions[$actionName]->perform($this, $actionName);
 102         } else {
 103             return $this->controller->handle($this, $actionName);
 104         }
 105     }
 106
 107
 108    /**
 109     * Returns a name for a submit button that will invoke a specific action.
 110     *
 111     * @access public
 112     * @param  string  Name of the action
 113     * @return string  "name" attribute for a submit button
 114     */
 115     function getButtonName($actionName, $subActionName = null)
 116     {
 117         if ( $subActionName != null ) {
 118             return '_qf_' . $this->getAttribute('id') . '_' . $actionName . '_' . $subActionName;
 119         } else {
 120             return '_qf_' . $this->getAttribute('id') . '_' . $actionName;
 121         }
 122     }
 123
 124
 125    /**
 126     * Loads the submit values from the array.
 127     *
 128     * The method is NOT intended for general usage.
 129     *
 130     * @param array  'submit' values
 131     * @access public
 132     */
 133     function loadValues($values)
 134     {
 135         $this->_flagSubmitted = true;
 136         $this->_submitValues = $values;
 137         foreach (array_keys($this->_elements) as $key) {
 138             $this->_elements[$key]->onQuickFormEvent('updateValue', null, $this);
 139         }
 140     }
 141
 142
 143    /**
 144     * Builds a form.
 145     *
 146     * You should override this method when you subclass HTML_QuickForm_Page,
 147     * it should contain all the necessary addElement(), applyFilter(), addRule()
 148     * and possibly setDefaults() and setConstants() calls. The method will be
 149     * called on demand, so please be sure to set $_formBuilt property to true to
 150     * assure that the method works only once.
 151     *
 152     * @access public
 153     * @abstract
 154     */
 155     function buildForm()
 156     {
 157         $this->_formBuilt = true;
 158     }
 159
 160
 161    /**
 162     * Checks whether the form was already built.
 163     *
 164     * @access public
 165     * @return bool
 166     */
 167     function isFormBuilt()
 168     {
 169         return $this->_formBuilt;
 170     }
 171
 172
 173    /**
 174     * Sets the default action invoked on page-form submit
 175     *
 176     * This is necessary as the user may just press Enter instead of
 177     * clicking one of the named submit buttons and then no action name will
 178     * be passed to the script.
 179     *
 180     * @access public
 181     * @param  string    default action name
 182     */
 183     function setDefaultAction($actionName)
 184     {
 185         if ($this->elementExists('_qf_default')) {
 186             $element =& $this->getElement('_qf_default');
 187             $element->setValue($this->getAttribute('id') . ':' . $actionName);
 188         } else {
 189             $this->addElement('hidden', '_qf_default', $this->getAttribute('id') . ':' . $actionName);
 190         }
 191     }
 192
 193
 194    /**
 195     * Returns 'safe' elements' values
 196     *
 197     * @param   mixed   Array/string of element names, whose values we want. If not set then return all elements.
 198     * @param   bool    Whether to remove internal (_qf_...) values from the resultant array
 199     */
 200     function exportValues($elementList = null, $filterInternal = false)
 201     {
 202         $values = parent::exportValues($elementList);
 203         if ($filterInternal) {
 204             foreach (array_keys($values) as $key) {
 205                 if (0 === strpos($key, '_qf_')) {
 206                     unset($values[$key]);
 207                 }
 208             }
 209         }
 210         return $values;
 211     }
 212 }
 213
 214 ?>