root/trunk/patForms/Element.php

<?php
/**
 * base patForms element class with all needed base functionality that each element
 * should have.
 *
 * $Id$
 *
 * @package        patForms
 * @subpackage    Element
 * @access        protected
 * @author        Sebastian Mordziol <argh@php-tools.net>
 * @author        gERD Schaufelberger <gerd@php-tools.net>
 * @author        Stephan Schmidt <schst@php-tools.net>
 */

/**
 * error definition: the attribute that was set is not supported by this element (it is
 * not listed in the attributeDefinition property set in the element class).
 * @see    patForms_Element::attributeDefinition
 */
define( "PATFORMS_ELEMENT_NOTICE_ATTRIBUTE_NOT_SUPPORTED", 1101 );

/**
 * error definition: the setAttributes() method expects an array,
 * but given value was not.
 * @see    patForms_Element::setAttributes()
 */
define( "PATFORMS_ELEMENT_ERROR_ARRAY_EXPECTED", 1102 );

/**
 * error definition: the given attribute could not be set
 */
define( "PATFORMS_ELEMENT_ERROR_ADDING_ATTRIBUTE_FAILED", 1103 );

/**
 * error definition: the element method to serialize the element in the given mode is
 * not implemented.
 * @see    patForms_Element::serialize()
 */
define( "PATFORMS_ELEMENT_ERROR_METHOD_FOR_MODE_NOT_AVAILABLE", 1104 );

/**
 * error definition: the element returned an error
 */
define( "PATFORMS_ELEMENT_ERROR_ERROR_RETURNED", 1105 );

/**
 * error definition: the modifier that was set for the element is not an array.
 * @see    patForms_Element::_applyModifiers()
 */
define( "PATFORMS_ELEMENT_ERROR_MODIFIER_NOT_AN_ARRAY", 1107 );

/**
 * error definition: the method for the given modifier does not exist
 * @see    patForms_Element::_applyModifiers()
 */
define( "PATFORMS_ELEMENT_ERROR_METHOD_FOR_MODIFIER_NOT_FOUND", 1108 );

/**
 * error definition: the modifier returned an error, modifications could not be made.
 * @see    patForms_Element::_applyModifiers()
 */
define( "PATFORMS_ELEMENT_ERROR_MODIFIER_RETURNED_ERROR", 1109 );

/**
 * error definition: the given attribute is required for the specified output format.
 * @see    patForms_Element::getAttributesFor()
 */
define( "PATFORMS_ELEMENT_ERROR_ATTRIBUTE_REQUIRED", 1110 );

/**
 * error definition: given modifier could not be applied to specified attribute
 * @see    patForms_Element::getAttributesFor()
 */
define( "PATFORMS_ELEMENT_ERROR_UNABLE_TO_APPLY_MODIFIER_TO_ATTRIBUTE", 1111 );

/**
 * error definition: the given attribute is not available for output in the specified
 * output format.
 * @see    patForms_Element::getAttributesFor()
 */
define( "PATFORMS_ELEMENT_ERROR_ATTRIBUTE_NOT_AVAILABLE_FOR_OUTPUT", 1112 );

/**
 * error definition: format of the attribute could not be verified
 * @see    patForms_Element::getAttributesFor()
 */
define( "PATFORMS_ELEMENT_ERROR_CAN_NOT_VERIFY_FORMAT", 1113 );

/**
 * error definition: the attribute collection of the element could not be validated.
 * @see patForms_Element::toHtml()
 */
define( "PATFORMS_ELEMENT_ERROR_CAN_NOT_VALIDATE_ATTRIBUTE_COLLECTION", 1114 );

/**
 * error definition: validator undefined
 */
define( "PATFORMS_ELEMENT_ERROR_VALIDATOR_ERROR_UNDEFINED", 1115 );

/**
 * error definition: undefined locale for errors output
 */
define( "PATFORMS_ELEMENT_ERROR_VALIDATOR_ERROR_LOCALE_UNDEFINED", 1116 );

/**
 * error definition: the html source for the element could not be generated.
 */
define( "PATFORMS_ELEMENT_ERROR_NO_HTML_CONTENT", 1221 );

/**
 * error definition: not a valid renderer
 */
define( 'PATFORMS_ELEMENT_ERROR_INVALID_RENDERER', 1222 );

/**
 * error definition: this element does not support the use of a renderer
 */
define( 'PATFORMS_ELEMENT_RENDERER_NOT_SUPPORTED', 1223 );

/**
 * no values supplied
 */
define('PATFORMS_ELEMENT_WARNING_NO_VALUES',1224);

/**
 * error definition: this element type can't be converted to another type
 */
define( 'PATFORMS_ELEMENT_ERROR_TYPE_NOT_CONVERTABLE', 1224 );

/**
 * error definition: this element value can't be converted to the requested element type
 */
define( 'PATFORMS_ELEMENT_ERROR_VALUE_NOT_CONVERTABLE', 1225 );

/**
 * The filter is invalid
 */
define('PATFORMS_ELEMENT_ERROR_FILTER_INVALID', 1300);

/**
 * filter is located between patForms and browser
 */
define( 'PATFORMS_FILTER_TYPE_HTTP', 1 );

/**
 * filter is located between patForms and the PHP script
 */
define( 'PATFORMS_FILTER_TYPE_PHP', 2 );



/**
 * base patForms element class with all needed base functionality that each element
 * should have. Extend this class to create your own elements.
 *
 * $Id$
 *
 * @abstract
 * @package        patForms
 * @subpackage    Element
 * @access        protected
 * @author        Sebastian Mordziol <argh@php-tools.net>
 * @author        gERD Schaufelberger <gerd@php-tools.net>
 * @author        Stephan Schmidt <schst@php-tools.net>
 * @license        LGPL, see license.txt for details
 * @link        http://www.php-tools.net
 */
class patForms_Element
{
   /**
    * the type of the element, set this in your element class!
    * @access    protected
    */
    var $elementType    =    false;

   /**
    * javascript that will be displayed only once
    *
    * @access    private
    * @var        array
    */
    var $globalJavascript    =    array();

   /**
    * javascript that will be displayed once per instance
    *
    * @access    private
    * @var        array
    */
    var $instanceJavascript    =    array();

   /**
    * the value of the element
    * @access    protected
    */
    var $value        =    false;

   /**
    * filters that have been applied
    * @access    private
    */
    var $filters    =    array();

   /**
    * attribute filters that have been applied
    * @access   protected
    */
    var $attributeFilters    =   array();

   /**
    * observers that have been attached
    *
    * @access    private
    * @var        array
    */
    var $observers    =    array();

   /**
    * The elementName for the serialized version of the element
    *
    * This is needed for the toXML() method and also by the patForms
    * error management. If it is not set, the element name will be
    * created by extracting everything after the last underscore in
    * the classname.
    *
    * @access    protected
    * @see        toXML()
    */
    var $elementName    =    null;

   /**
    * the attribute collection of the element
    * @access    private
    * @see        setAttribute()
    * @see        setAttributes()
    * @see        getAttribute()
    * @see        getAttributes()
    */
    var $attributes    =    array();

   /**
    * the configuration for the attributes supported by the element. Overwrite this
    * in your element class.
    *
    * @abstract
    */
    var $attributeDefinition    =    array();

   /**
    * Stores the attribute defaults for the element, that will be used
    * if the given attributes have not been set by the user.
    *
    * @abstract
    * @access    private
    * @see        getAttributeDefaults()
    */
    var $attributeDefaults    =    array();

   /**
    * stores the mode for the element. It defaults to 'default', and is only overwritten if
    * set specifically.
    *
    * @access    protected
    * @see        setMode()
    */
    var $mode    =    "default";

   /**
    * stores the format for the element. It defaults to 'html', and is only overwritten if
    * set specifically.
    *
    * @access    protected
    * @see        setFormat()
    */
    var $format    =    "html";

   /**
    * stores the locale to use when adding validation errors. The specified locale has
    * to be set in the validationErrorCodes element class property, otherwise the default
    * 'C' (as in the programming language C => english) will be used.
    *
    * @access    private
    * @var        string    $locale
    * @see        setLocale()
    */
    var    $locale   =   "C";

   /**
    * the form's namespace
    *
    * @access    private
    * @var        string
    */
    var    $namespace = '';

   /**
    * stores the flag telling the element whether it has been submitted - this is used by the
    * getValue() method to determine where to get the element's value from.
    * @access    protected
    * @see        getValue()
    */
    var $submitted    =    false;

   /**
    * stores the flag whether the element is valid
    * @access    protected
    */
    var $valid    =    true;

   /**
    * stores any validation errors that can occurr during the element's validation process.
    *
    * @access    private
    * @var        array    $validationErrors
    */
    var    $validationErrors  =   array();

   /**
    * define error codes an messages for each form element
    *
    * @access    protected
    * @var        array    $validatorErrorCodes
    */
    var    $validatorErrorCodes  =   array();

   /**
    * defines the starting character for the modifier placeholders that can be inserted
    * in the attributes listed as having modifier support.
    *
    * @access    private
    * @var        string    $modifierStart
    */
    var $modifierStart    =    "[";

   /**
    * defines the starting character for the modifier placeholders that can be inserted
    * in the attributes listed as having modifier support.
    *
    * @access    private
    * @var        string    $modifierStart
    */
    var $modifierEnd    =    "]";

   /**
    * XML entities
    *
    * @access    protected
    * @see        toXML()
    */
    var $xmlEntities    =    array(
                                    "<"    =>    "&lt;",
                                    ">"    =>    "&gt;",
                                    "&"    =>    "&amp;",
                                    "'"    =>    "&apos;",
                                    '"'    =>    "&quot;"
                                );
   /**
    * shortcur to the session variables
    * If "false", no session will be used, otherwise it stores the session variables for this element
    *
    * @access private
    * @var    mixed    $sessionVar
    */
    var    $sessionVar = false;

   /**
    * custom validation rules
    *
    * @access    private
    * @var        array
    */
    var $_rules            =    array();

   /**
    * next error offset for rules
    * @access    private
    * @var        integer
    */
    var $nextErrorOffset    =    1000;

   /**
    * stores whether the element uses a renderer to serialize its content
    * @access    private
    * @var        bool
    */
    var $usesRenderer        =    false;

   /**
    * Stores the renderer object that can be set via the setRenderer method
    * @access    private
    * @var        object
    */
    var $renderer            =    false;

   /**
    * Stores all element options
    * @access    private
    */
    var $options    =    array();

   /**
    * flag to indicate, whether the element is a container element
    *
    * @access protected
    * @var    boolean
    */
    var $containerElement = false;

   /**
    * id of the last rule that has been added using the format attribute
    *
    * @access protected
    * @var    string
    */
    var $_formatRuleId = null;

   /**
    * contains the function name for calculating strlen of a string.
    * Maybe mb_strlen is available so this will be used instead.
    *
    * @access protected
    * @var    string
    */
    var $_lenFunc = 'strlen';

   /**
    * constructor - extend this in your class if you need to do specific operations
    * on startup. In that case, however, don't forget to call this constructor anyway
    * so that the thing happening here don't get lost.
    *
    * That's easy to do... just add the following line in your constructor:
    * parent::patForms_Element();
    *
    * @access    public
    * @param    mixed    $mode    Optional: the output format, e.g. 'html'
    */
    function __construct( $format = false )
    {
        if ($format !== false) {
            $this->format = $format;
        }

        if (function_exists('mb_strlen')){
            $this->_lenFunc = 'mb_strlen';
        }

        $this->loadAttributeDefaults();
    }

    /**
     *    patForms_Element    constructor for php4
     *
     *    @access    private
     *    @param    integer    $id
     *    @return boolean $result    true on success
     *    @see    __construct
     */
    function patForms_Element( $format = false )
    {
        $this->__construct( $format );
    }

   /**
    * Add any initialization routines for your element in your element class,
    * for everythig your element needs to do after it has been instantiated and
    * the attribute collection has been created.
    *
    * @abstract
    * @access    private
    * @return    mixed    $success    True on success, a patError object otherwise
    */
    function _init()
    {
        // your code here
        return true;
    }

   /**
    * sets the format of the element - this defines which method will be called in your
    * element class, along with the {@link mode} property.
    *
    * @access    public
    * @param    string    $format    The name of the format you have implemented in your element(s). Default is 'html'
    * @see        setFormat()
    * @see        format
    * @see        serialize()
    */
    function setFormat($format)
    {
        $this->format = strtolower($format);
    }

   /**
    * sets the mode of the element that defines which methods will be called in your
    * element class, along with the {@link format} property.
    *
    * @access    public
    * @param    string    $mode    The mode to set the element to: default|readonly or any other mode you have implemented in your element class(es). Default is 'default'.
    * @see        setFormat()
    * @see        mode
    * @see        serialize()
    */
    function setMode( $mode )
    {
        $this->mode    =    strtolower( $mode );
    }

   /**
    * sets the locale (language) to use for the validation error messages of the form.
    *
    * @access    public
    * @param    string    $lang
    * @return    bool    $result    True on success
    * @see        $locale
    */
    function setLocale( $lang )
    {
        $this->locale = $lang;

        // check, whether this is a custom locale
        if (patForms::isCustomLocale($lang)) {
            $errorMessages = patForms::getCustomLocale($lang, 'Element::' . $this->elementName);
            if (is_array($errorMessages)) {
                $this->validatorErrorCodes[$lang] = $errorMessages;
            }
        }

        return  true;
    }

   /**
    * get the element's namespace
    *
    * @access    public
    * @param    string        namespace
    * @return    string
    */
    function getNamespace()
    {
        return $this->namespace;
    }

   /**
    * set the element's namespace
    *
    * @access    public
    * @param    string        namespace
    * @return    null
    */
    function setNamespace($namespace)
    {
        $this->namespace = $namespace;
    }

   /**
    * sets the value of the element, which will be used to fill the element with. If none is
    * set and the element needs a value, it will load it using the {@link resolveValue()} method.
    *
    * This will override user input.
    *
    * @access    public
    * @param    mixed    $value    The value to set
    * @see        $value
    * @see        resolveValue()
    * @see        getValue()
    */
    function setValue($value)
    {
        $value = $this->_applyFilters($value, 'in', PATFORMS_FILTER_TYPE_PHP);
        $this->value = $value;
    }

   /**
    * sets the default value of the element, which will be used to fill the element with.
    *
    * @access    public
    * @param    mixed    $value    The value to set
    * @see        $value
    * @see        resolveValue()
    * @see        setValue()
    * @see        getValue()
    */
    function setDefaultValue($value)
    {
        $value = $this->_applyFilters($value, 'in', PATFORMS_FILTER_TYPE_PHP);
        $this->setAttribute('default', $value);
    }

   /**
    * sets the current submitted state of the element. Set this to true if you want the element
    * to pick up its submitted data.
    *
    * @access    public
    * @param    bool    $state    True if it has been submitted, false otherwise (default).
    * @see        getSubmitted()
    * @see        $submitted
    */
    function setSubmitted( $state )
    {
        $this->submitted    =    $state;
    }

   /**
    * sets the internal ID of the element - this is only used by the {@link patForms} class to
    * give each element a unique ID that will be added as ID attribute to each element if the
    * id attribute has not been defined.
    *
    * @access    public
    * @param    string    $id    The id to set for the element
    * @see        getId()
    */
    function setId( $id )
    {
        $this->attributes['id']    =    $id;
    }

   /**
    * gets the internal ID of the element
    *
    * @access    public
    * @return    string    $id    The id to set for the element
    * @see        setId()
    */
    function getId()
    {
        return $this->getAttribute( 'id' );
    }

   /**
    * checks whether a given attribute is supported by this element.
    *
    * @access    public
    * @param    string    $attributeName    The name of the attribute to check
    * @return    bool    $hasAttribute    True if it supports the attribute, false otherwise.
    */
    function hasAttribute( $attributeName )
    {
        if( isset( $this->attributeDefinition[$attributeName] ) )
        {
            return true;
        }

        return false;
    }

   /**
    * adds an attribute to the element's attribut3 collection. If the attribute
    * already exists, it is overwritten.
    *
    * @access    public
    * @param    string    $attributeName    The name of the attribute to add
    * @param    string    $attributeValue    The value of the attribute
    * @return    mixed    $success        True on success, a patError object otherwise
    */
    function setAttribute( $attributeName, $attributeValue )
    {
        if (!isset($this->attributeDefinition[$attributeName])) {
            return patErrorManager::raiseNotice(
                PATFORMS_ELEMENT_NOTICE_ATTRIBUTE_NOT_SUPPORTED,
                'Unknown attribute ['.$attributeName.']',
                'Ignored the attribute as the ['.$this->elementName.'] element does not support it.'
            );
        }

        if (isset($this->attributeDefinition[$attributeName]['setter'])) {
            $setter = $this->attributeDefinition[$attributeName]['setter'];
            call_user_func_array(array(&$this, $setter), array($attributeValue));
        } else {
            $result =   $this->_applyAttributeFilters( $attributeName, $attributeValue, 'set');
            if (patErrorManager::isError($result)) {
                return $result;
            }
            $this->attributes[$attributeName] = $attributeValue;
        }
        return true;
    }

   /**
    * adds several attribute at once to the element's attributes collection.
    * Any existing attributes will be overwritten.
    *
    * @access    public
    * @param    array    $attributes    The attributes to add
    * @return    mixed    $success    True on success, false otherwise
    */
    function setAttributes($attributes)
    {
        if (!is_array($attributes)) {
            return patErrorManager::raiseError(
                PATFORMS_ELEMENT_ERROR_ARRAY_EXPECTED,
                "Not an array given (setAttributes)"
            );
        }

        foreach ($attributes as $attributeName => $attributeValue) {
            $this->setAttribute($attributeName, $attributeValue);
        }

        return true;
    }

   /**
    * set the value format of the element
    *
    * @access public
    * @param  string    format (=rule) used for validation
    */
    function setValueFormat($format)
    {
        // remove the previously set rule
        if ($this->_formatRuleId !== null) {
            $this->removeRule($this->_formatRuleId);
        }

        switch (strtolower($format)) {
            case 'email':
                $ruleName = 'Email';
                break;
            case 'url':
                $ruleName = 'URL';
                break;
            default:
                $ruleName = $format;
                break;
        }

        $rule = &patForms::createRule($ruleName);
        $this->addRule($rule, PATFORMS_RULE_AFTER_VALIDATION);
        $this->attributes['format'] = $rule->getRuleName