/src-all/piwik/libs/HTML/QuickForm2/Renderer.php
PHP | 366 lines | 124 code | 25 blank | 217 comment | 16 complexity | e41241f63f32462989d7a8c9d7f4f18f MD5 | raw file
- <?php
- /**
- * Base class for HTML_QuickForm2 renderers
- *
- * PHP version 5
- *
- * LICENSE:
- *
- * Copyright (c) 2006-2010, Alexey Borzov <avb@php.net>,
- * Bertrand Mansion <golgote@mamasam.com>
- * All rights reserved.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
- * are met:
- *
- * * Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
- * * Redistributions in binary form must reproduce the above copyright
- * notice, this list of conditions and the following disclaimer in the
- * documentation and/or other materials provided with the distribution.
- * * The names of the authors may not be used to endorse or promote products
- * derived from this software without specific prior written permission.
- *
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
- * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
- * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
- * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
- * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
- * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
- * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
- * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
- * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
- * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
- * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * @category HTML
- * @package HTML_QuickForm2
- * @author Alexey Borzov <avb@php.net>
- * @author Bertrand Mansion <golgote@mamasam.com>
- * @license http://opensource.org/licenses/bsd-license.php New BSD License
- * @version SVN: $Id: Renderer.php 299706 2010-05-24 18:32:37Z avb $
- * @link http://pear.php.net/package/HTML_QuickForm2
- */
- /**
- * Class with static methods for loading classes and files
- */
- // require_once 'HTML/QuickForm2/Loader.php';
- /**
- * Abstract base class for QuickForm2 renderers
- *
- * This class serves two main purposes:
- * <ul>
- * <li>Defines the API all renderers should implement (render*() methods);</li>
- * <li>Provides static methods for registering renderers and their plugins
- * and {@link factory()} method for creating renderer instances.</li>
- * </ul>
- *
- * Note that renderers should always be instantiated through factory(), in the
- * other case it will not be possible to add plugins.
- *
- * @category HTML
- * @package HTML_QuickForm2
- * @author Alexey Borzov <avb@php.net>
- * @author Bertrand Mansion <golgote@mamasam.com>
- * @version Release: @package_version@
- */
- abstract class HTML_QuickForm2_Renderer
- {
- /**
- * List of registered renderer types
- * @var array
- */
- private static $_types = array(
- 'default' => array('HTML_QuickForm2_Renderer_Default', null),
- 'array' => array('HTML_QuickForm2_Renderer_Array', null)
- );
- /**
- * List of registered renderer plugins
- * @var array
- */
- private static $_pluginClasses = array(
- 'default' => array(),
- 'array' => array()
- );
- /**
- * Renderer options
- * @var array
- * @see setOption()
- */
- protected $options = array(
- 'group_hiddens' => true,
- 'required_note' => '<em>*</em> denotes required fields.',
- 'errors_prefix' => 'Invalid information entered:',
- 'errors_suffix' => 'Please correct these fields.',
- 'group_errors' => false
- );
- /**
- * Javascript builder object
- * @var HTML_QuickForm2_JavascriptBuilder
- */
- protected $jsBuilder;
- /**
- * Creates a new renderer instance of the given type
- *
- * A renderer is always wrapped by a Proxy, which handles calling its
- * "published" methods and methods of its plugins. Registered plugins are
- * added automagically to the existing renderer instances so that
- * <code>
- * $foo = HTML_QuickForm2_Renderer::factory('foo');
- * // Plugin implementing bar() method
- * HTML_QuickForm2_Renderer::registerPlugin('foo', 'Plugin_Foo_Bar');
- * $foo->bar();
- * </code>
- * will work.
- *
- * @param string Type name (treated case-insensitively)
- * @return HTML_QuickForm2_Renderer_Proxy A renderer instance of the given
- * type wrapped by a Proxy
- * @throws HTML_QuickForm2_InvalidArgumentException If type name is unknown
- * @throws HTML_QuickForm2_NotFoundException If class for the renderer can
- * not be found and/or loaded from file
- */
- final public static function factory($type)
- {
- $type = strtolower($type);
- if (!isset(self::$_types[$type])) {
- throw new HTML_QuickForm2_InvalidArgumentException(
- "Renderer type '$type' is not known"
- );
- }
- list ($className, $includeFile) = self::$_types[$type];
- if (!class_exists($className)) {
- HTML_QuickForm2_Loader::loadClass($className, $includeFile);
- }
- if (!class_exists('HTML_QuickForm2_Renderer_Proxy')) {
- HTML_QuickForm2_Loader::loadClass('HTML_QuickForm2_Renderer_Proxy');
- }
- return new HTML_QuickForm2_Renderer_Proxy(new $className, self::$_pluginClasses[$type]);
- }
- /**
- * Registers a new renderer type
- *
- * @param string Type name (treated case-insensitively)
- * @param string Class name
- * @param string File containing the class, leave empty if class already loaded
- * @throws HTML_QuickForm2_InvalidArgumentException if type already registered
- */
- final public static function register($type, $className, $includeFile = null)
- {
- $type = strtolower($type);
- if (!empty(self::$_types[$type])) {
- throw new HTML_QuickForm2_InvalidArgumentException(
- "Renderer type '$type' is already registered"
- );
- }
- self::$_types[$type] = array($className, $includeFile);
- if (empty(self::$_pluginClasses[$type])) {
- self::$_pluginClasses[$type] = array();
- }
- }
- /**
- * Registers a plugin for a renderer type
- *
- * @param string Renderer type name (treated case-insensitively)
- * @param string Plugin class name
- * @param string File containing the plugin class, leave empty if class already loaded
- * @throws HTML_QuickForm2_InvalidArgumentException if plugin is already registered
- */
- final public static function registerPlugin($type, $className, $includeFile = null)
- {
- $type = strtolower($type);
- // We don't check self::$_types, since a plugin may be registered
- // before renderer itself if it goes with some custom element
- if (empty(self::$_pluginClasses[$type])) {
- self::$_pluginClasses[$type] = array(array($className, $includeFile));
- } else {
- foreach (self::$_pluginClasses[$type] as $plugin) {
- if (0 == strcasecmp($plugin[0], $className)) {
- throw new HTML_QuickForm2_InvalidArgumentException(
- "Plugin '$className' for renderer type '$type' is already registered"
- );
- }
- }
- self::$_pluginClasses[$type][] = array($className, $includeFile);
- }
- }
- /**
- * Constructor
- *
- * Renderer instances should not be created directly, use {@link factory()}
- */
- protected function __construct()
- {
- }
- /**
- * Returns an array of "published" method names that should be callable through proxy
- *
- * Methods defined in HTML_QuickForm2_Renderer are proxied automatically,
- * only additional methods should be returned.
- *
- * @return array
- */
- public function exportMethods()
- {
- return array();
- }
- /**
- * Sets the option(s) affecting renderer behaviour
- *
- * The following options are available:
- * <ul>
- * <li>'group_hiddens' - whether to group hidden elements together or
- * render them where they were added (boolean)</li>
- * <li>'group_errors' - whether to group error messages or render them
- * alongside elements they apply to (boolean)</li>
- * <li>'errors_prefix' - leading message for grouped errors (string)</li>
- * <li>'errors_suffix' - trailing message for grouped errors (string)</li>
- * <li>'required_note' - note displayed if the form contains required
- * elements (string)</li>
- * </ul>
- *
- * @param string|array option name or array ('option name' => 'option value')
- * @param mixed parameter value if $nameOrConfig is not an array
- * @return HTML_QuickForm2_Renderer
- * @throws HTML_QuickForm2_NotFoundException in case of unknown option
- */
- public function setOption($nameOrOptions, $value = null)
- {
- if (is_array($nameOrOptions)) {
- foreach ($nameOrOptions as $name => $value) {
- $this->setOption($name, $value);
- }
- } else {
- if (!array_key_exists($nameOrOptions, $this->options)) {
- throw new HTML_QuickForm2_NotFoundException(
- "Unknown option '{$nameOrOptions}'"
- );
- }
- $this->options[$nameOrOptions] = $value;
- }
- return $this;
- }
- /**
- * Returns the value(s) of the renderer option(s)
- *
- * @param string parameter name
- * @return mixed value of $name parameter, array of all configuration
- * parameters if $name is not given
- * @throws HTML_QuickForm2_NotFoundException in case of unknown option
- */
- public function getOption($name = null)
- {
- if (null === $name) {
- return $this->options;
- } elseif (!array_key_exists($name, $this->options)) {
- throw new HTML_QuickForm2_NotFoundException(
- "Unknown option '{$name}'"
- );
- }
- return $this->options[$name];
- }
- /**
- * Returns the javascript builder object
- *
- * @return HTML_QuickForm2_JavascriptBuilder
- */
- public function getJavascriptBuilder()
- {
- if (empty($this->jsBuilder)) {
- if (!class_exists('HTML_QuickForm2_JavascriptBuilder')) {
- HTML_QuickForm2_Loader::loadClass('HTML_QuickForm2_JavascriptBuilder');
- }
- $this->jsBuilder = new HTML_QuickForm2_JavascriptBuilder();
- }
- return $this->jsBuilder;
- }
- /**
- * Sets the javascript builder object
- *
- * You may want to reuse the same builder object if outputting several
- * forms on one page.
- *
- * @param HTML_QuickForm2_JavascriptBuilder
- * @return HTML_QuickForm2_Renderer
- */
- public function setJavascriptBuilder(HTML_QuickForm2_JavascriptBuilder $builder = null)
- {
- $this->jsBuilder = $builder;
- return $this;
- }
- /**
- * Renders a generic element
- *
- * @param HTML_QuickForm2_Node Element being rendered
- */
- abstract public function renderElement(HTML_QuickForm2_Node $element);
- /**
- * Renders a hidden element
- *
- * @param HTML_QuickForm2_Node Hidden element being rendered
- */
- abstract public function renderHidden(HTML_QuickForm2_Node $element);
- /**
- * Starts rendering a form, called before processing contained elements
- *
- * @param HTML_QuickForm2_Node Form being rendered
- */
- abstract public function startForm(HTML_QuickForm2_Node $form);
- /**
- * Finishes rendering a form, called after processing contained elements
- *
- * @param HTML_QuickForm2_Node Form being rendered
- */
- abstract public function finishForm(HTML_QuickForm2_Node $form);
- /**
- * Starts rendering a generic container, called before processing contained elements
- *
- * @param HTML_QuickForm2_Node Container being rendered
- */
- abstract public function startContainer(HTML_QuickForm2_Node $container);
- /**
- * Finishes rendering a generic container, called after processing contained elements
- *
- * @param HTML_QuickForm2_Node Container being rendered
- */
- abstract public function finishContainer(HTML_QuickForm2_Node $container);
- /**
- * Starts rendering a group, called before processing grouped elements
- *
- * @param HTML_QuickForm2_Node Group being rendered
- */
- abstract public function startGroup(HTML_QuickForm2_Node $group);
- /**
- * Finishes rendering a group, called after processing grouped elements
- *
- * @param HTML_QuickForm2_Node Group being rendered
- */
- abstract public function finishGroup(HTML_QuickForm2_Node $group);
- }
- ?>