368 lines
13 KiB
PHP
368 lines
13 KiB
PHP
<?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
|
|
*/
|
|
use Piwik\Plugin;
|
|
|
|
/**
|
|
* 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);
|
|
}
|
|
?>
|