<?php
/**
 * base patForms element class with all needed base functionality that each element
 * should have.
 *
 * $Id: Element.php 1347 2009-12-03 21:06:36Z francois $
 *
 * @package    patForms
 * @subpackage patForms_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 utility class {@link patForms_FormatChecker} could not be found, this is
 * needed for the format validation of certain variable types.
 * @see        patForms_FormatChecker
 * @see        patForms_Element::validateFormat()
 */
define( "PATFORMS_ELEMENT_ERROR_FORMAT_CHECKER_NOT_FOUND", 1106 );

/**
 * 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 );

/**
 * 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: Element.php 1347 2009-12-03 21:06:36Z francois $
 *
 * @abstract
 * @package    patForms
 * @subpackage patForms_Element
 * @access     protected
 * @version    0.1
 * @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();

   /**
	* 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";

   /**
	* 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();

   /**
	* 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;
		}

		$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;
	}

   /**
	* 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 )
	{
		$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.'
			);
		}

		$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;
	}

   /**
	* sets a renderer object that will be used to render
	* the element. Use the serialize() method to retrieve
	* the rendered content of the element.
	*
	* Only enabled in elements that support renderers, like
	* the radio element.
	*
	* @access     public
	* @param      object	&$renderer	The renderer object
	*/
	function setRenderer( &$renderer )
	{
		if ( !$this->usesRenderer )
		{
			return patErrorManager::raiseWarning(
				PATFORMS_ELEMENT_RENDERER_NOT_SUPPORTED,
				'The element \''.$this->elementName.'\' does not support the use of renderers - you do not have to set a renderer for this element.'
			);
		}

		if ( !is_object( $renderer ) )
		{
			return patErrorManager::raiseError(
				PATFORMS_ELEMENT_ERROR_INVALID_RENDERER,
				'You can only set a patForms_Renderer object with the setRenderer() method, "'.gettype( $renderer ).'" given.'
			);
		}

		$this->renderer	=	&$renderer;
	}

   /**
	* retrieves the value of an attribute.
	*
	* @access     public
	* @param      string	$attribute	The name of the attribute to retrieve
	* @return     mixed	$attributeValue	The value of the attribute, or false if it does not exist in the attributes collection.
	* @see        setAttribute()
	*/
	function getAttribute( $attribute )
	{
		if ( !isset( $this->attributes[$attribute] ) )
		{
			return false;
		}

		return $this->attributes[$attribute];
	}

   /**
	* retrieves all attributes, or only the specified attributes.
	*
	* @access     public
	* @param      array	$attributes	Optional: The names of the attributes to retrieve. Only the attributes that exist will be returned.
	* @return     array	$result		The attributes
	* @see        getAttribute()
	*/
	function getAttributes( $attributes = array() )
	{
		if ( empty( $attributes ) )
		{
			return $this->attributes;
		}

		$result	=	array();
		foreach ( $attributes as $attribute )
		{
			if ( $attributeValue = $this->getAttribute( $attribute ) )
			{
				$result[$attribute]	=	$attributeValue;
			}
		}

		return $result;
	}

   /**
	* Loads the default attribute values into the attributes collection. Done directly
	* on startup (in the consructor), so make sure you call this if your element needs
	* this feature and you have implemented a custom constructor in your element.
	*
	* @access     public
	* @return     bool	$success	Always returns true.
	* @see        $attributeDefaults
	*/
	function loadAttributeDefaults()
	{
		foreach ( $this->attributeDefinition as $attributeName => $attributeDef )
		{
			if ( isset( $attributeDef['default'] ) )
			{
				$this->attributes[$attributeName]	=	$attributeDef['default'];
			}
		}

		return true;
	}

   /**
	* retrieves the current value of the element. If none is set, will try to retrieve the
	* value from submitted form data.
	*
	* @access     public
	* @param      boolean		Determines whether the method is used from an external script
	* @return     mixed		The value, or an empty string if none found.
	* @see        setValue()
	* @see        value
	* @see        resolveValue()
	*/
	function getValue( $external = true )
	{
		if ( $this->value === false )
		{
			$this->resolveValue();

			// could not be resolved
			if ( $this->value === false )
			{
				$value	=	'';
			}
			else
			{
				$value	=	$this->value;
			}
		}
		else
		{
			$value	=	$this->value;
		}

		if ( $external === false )
		{
			return $value;
		}

		$value			=	$this->_applyFilters( $value, 'out', PATFORMS_FILTER_TYPE_PHP );

		return $value;
	}

   /**
	* resolves the scope the value of the element may be stored in, and returns it.
	*
	* @access     protected
	* @see        getValue()
	* @see        value
	* @todo       parse element name, if it uses the array syntax
	*/
	function resolveValue()
	{
		$varName	=	$this->attributes['name'];

		if ( $this->submitted && isset( $_POST[$varName] ) )
		{
			$this->value	=	$_POST[$varName];
			if ( ini_get( 'magic_quotes_gpc' ) )
				$this->value = $this->rStripSlashes( $this->value );
			$this->value	=	$this->_applyFilters( $this->value, 'in', PATFORMS_FILTER_TYPE_HTTP );
			return true;
		}

		if ( $this->submitted && isset( $_GET[$varName] ) )
		{
			$this->value	=	$_GET[$varName];
			if ( ini_get( 'magic_quotes_gpc' ) )
				$this->value = $this->rStripSlashes( $this->value );
			$this->value	=	$this->_applyFilters( $this->value, 'in', PATFORMS_FILTER_TYPE_HTTP );
			return true;
		}

		if ( isset( $this->attributes['default'] ) )
		{
			$this->value	=	$this->attributes['default'];
			$this->value	=	$this->_applyFilters( $this->value, 'in', PATFORMS_FILTER_TYPE_PHP );

			return true;
		}

		return true;
	}

   /**
	* recursively strip slashes
	*
	* This method is used to 'fix' magic_quotes_gpc.
	*
	* @access     public
	* @param      mixed		user input (get or post)
	* @return     mixed		data with slashes stripped
	*/
	function rStripSlashes( $value )
	{
		if ( is_scalar( $value ) )
			return stripslashes( $value );
		if ( is_array( $value ) )
		{
			foreach ( $value as $key => $val )
			{
				$value[$key] = $this->rStripSlashes( $val );
			}
		}
		return $value;
	}

   /**
	* apply filters to a value
	*
	* @access     private
	* @param      mixed		value
	* @param      string		direction of the filter ('in' or 'out')
	* @param      integer		type of filters to apply
	* @return     mixed		filtered value
	*/
	function _applyFilters( $value, $dir = 'in', $type = PATFORMS_FILTER_TYPE_PHP )
	{
		if ( empty( $this->filters ) )
			return $value;

			/**
			 * apply filters!
			 */
			$cnt	=	count( $this->filters );
			for ( $i = 0; $i < $cnt; $i++ )
			{
				/**
				 * check, whether filter is located between php script and form
				 */
				if ( $this->filters[$i]->getType() != $type )
				{
					continue;
				}

				$value	=	$this->filters[$i]->$dir( $value );
			}
		return $value;
	}

   /**
	* retrieves the current mode of the element
	*
	* @access     public
	* @return     string	$mode	The current element mode
	* @see        setMode()
	* @see        mode
	*/
	function getMode()
	{
		return $this->mode;
	}

   /**
	* retrieves the current format of the element
	*
	* @access     public
	* @return     string	$format	The current element format
	* @see        setFormat()
	* @see        format
	*/
	function getFormat()
	{
		return $this->format;
	}

   /**
	* retrieves the element's current submitted state.
	*
	* @access     public
	* @return     bool	$state	True if it has been submitted, false otherwise.
	* @see        setSubmitted()
	* @see        submitted
	*/
	function getSubmitted()
	{
		return $this->submitted;
	}

   /**
	* retrieves the name of the element
	*
	* @access     public
	* @return     string	$name	name of the element
	* @uses       getAttribute()
	*/
	function getName()
	{
		return $this->getAttribute( 'name' );
	}

   /**
	* add a custom validation rule
	*
	* @access     public
	* @param      object patForms_Rule	validation rule
	* @param      integer					time, when rule has to be applied, can be before or after validation.
	*									If set to null, it will use the default value as specified in the rule
	* @return     boolean					currently always true
	*/
	function addRule( &$rule, $time = null )
	{
		if ( is_null( $time ) )
		{
			$time	=	$rule->getTime();
		}

		$rule->prepareRule( $this );

		$this->_rules[]	= array(
									'rule'			=>	&$rule,
									'time'			=>	$time,
								);
		return true;
	}

   /**
	* adds an observer to the element
	*
	* @access     public
	* @param      object patForms_Observer	observer
	* @return     boolean						currently always true
	*/
	function attachObserver( &$observer )
	{
		$this->observers[] = &$observer;
		return true;
	}

   /**
	* dispatches the serialization of the element in the format that was set to the
	* corresponding method in the element class. These methods must be named in the
	* folowing scheme:
	*
	* serialize[format][mode](), e.g. serializeHtmlDefault()
	*
	* @access     public
	* @return     string	$element		The created element according to the specified mode.
	* @see        setFormat()
	* @see        setMode()
	* @todo       serialize*() methods should return a patError object instead of false!!!!
	*           Has to be changed asap!
	*/
	function serialize()
	{
		$methodName	=	"serialize".ucfirst( $this->getFormat() ).ucfirst( $this->getMode() );

		if ( !method_exists( $this, $methodName ) )
		{
			return patErrorManager::raiseError(
				PATFORMS_ELEMENT_ERROR_METHOD_FOR_MODE_NOT_AVAILABLE,
				"Element method for form mode '".$this->getMode()."' (".$methodName.") is not available."
			);
		}

		/**
		 * get the value for internal use
		 * The PHP-filters will not be applied
		 */
		$value	=	$this->getValue( false );

		$element = $this->$methodName( $value );
		if ( patErrorManager::isError( $element ) )
		{
			return $element;
		}

		return $element;
	}

   /**
	* Template method that applies rules and calls the elements
	* validation method
	*
	* @final
	* @access     public
	* @return     bool	$success	True on success, false otherwise
	*/
	function validate()
	{
		// apply locale, if the current locale is a custom locale
		if (patForms::isCustomLocale($this->locale)) {
			$cnt = count( $this->_rules );
			for ( $i = 0; $i < $cnt; $i++ ) {
				$this->_rules[$i]['rule']->setLocale($this->locale);
			}
		}

		/**
		 * validate custom rules
		 */
		if ( !$this->_applyRules( PATFORMS_RULE_BEFORE_VALIDATION ) )
		{
			$this->_announce( 'status', 'error' );
			return false;
		}

		/**
		 * the the unfiltered value
		 */
		$value	=	$this->getValue( false );

		$valid  =   $this->validateElement( $value );
		if ( $valid === false )
		{
			$this->_announce( 'status', 'error' );
			return false;
		}

		/**
		 * validate custom rules
		 */
		if ( !$this->_applyRules( PATFORMS_RULE_AFTER_VALIDATION ) )
		{
			$this->_announce( 'status', 'error' );
			return false;
		}

		$this->_announce( 'status', 'validated' );
		return true;
	}

   /**
	* validates the given data with the element's validation routines
	* and returns the data with any needed modifications.
	*
	* @abstract
	* @access     private
	* @return     bool	$success	True on success, false otherwise
	*/
	function validateElement()
	{
		// your code here
		return true;
	}

   /**
	* apply rules
	*
	* @access     private
	* @param      integer		time of validation
	* @return     boolean		rules are valid or not
	* @todo       add documentation
	*/
	function _applyRules( $time )
	{
		$valid	=	true;

		$cnt	=	count( $this->_rules );
		for ( $i = 0; $i < $cnt; $i++ )
		{
			if ( ( $this->_rules[$i]['time'] & $time ) != $time )
				continue;

			$result	=	$this->_rules[$i]['rule']->applyRule( $this, $time );
			if ( $result === false )
			{
				$valid	=	false;
			}
		}
		return	$valid;
	}

   /**
	* finalize the element.
	*
	* Used as a template method.
	*
	* @final
	* @access     protected
	* @return     bool	$success	True on success, false otherwise
	* @uses       finalizeElement() to call the user code
	*/
	function finalize()
	{
		$value	=	$this->getValue( false );
		return $this->finalizeElement( $value );
	}

   /**
	* finalize the element
	*
	* Offers the possibility to process any needed operations after the element
	* has been validated. Implement any tasks that you need to do then here - a
	* good example is the File element, where this method enables the moving of
	* the uploaded file to the correct location.
	*
	* @abstract
	* @access     private
	* @param      mixed	value of the element
	* @return     bool	$success	True on success, false otherwise
	*/
	function finalizeElement( $value )
	{
		return true;
	}

   /**
	* Enables an element option.
	*
	* See the {@link patForms::$options} property for an exhaustive list of available options.
	*
	* @access     public
	* @param      string	$option		The option to enable
	* @param      array	$params		Optional parameters for the option
	* @see        disableOption()
	* @see        $options
	*/
	function enableOption( $option, $params = array() )
	{
		if ( !isset( $this->options[$option] ) )
			$this->options[$option]	=	array();

		$this->options[$option]['enabled']	=	true;
		$this->options[$option]['params']	=	$params;
	}

   /**
	* Disables an element option
	*
	* See the {@link patForms::$options} property for an exhaustive list of available options.
	*
	* @access     public
	* @param      string	$option	The option to disable
	* @see        enableOption()
	* @see        $options
	*/
	function disableOption( $option )
	{
		if ( !isset( $this->options[$option] ) )
			$this->options[$option]	=	array();

		$this->options[$option]['enabled']	=	false;
	}

   /**
	* [helper method] validates the given value according to the specified method. It first
	* checks if there is a method to check the format in the {@link patForms_FormatChecker}
	* class, then checks in the element class itself.
	*
	* @access     public
	* @param      mixed	$value		The value to validate the format of
	* @param      string	$format		The format to validate the value with
	* @return     bool	$isValid	True if valid, false if invalid or no method exists to validate the format.
	* @see        patForms_FormatChecker
	*/
	function validateFormat( $value, $format )
	{
		if ( !class_exists( "patForms_FormatChecker" ) )
		{
			$checkerFile	=	dirname( __FILE__ )."/FormatChecker.php";
			if ( !file_exists( $checkerFile ) )
			{
				$this->valid	=	false;
				return patErrorManager::raiseError(
					PATFORMS_ELEMENT_ERROR_FORMAT_CHECKER_NOT_FOUND,
					"Type checker could not be found, aborting validation."
				);
			}

			include_once( $checkerFile );
		}

		$format	=	strtolower( $format );

		$methodName	=	"is_".$format;
		$option		=	false;

		if ( method_exists( $this, $methodName ) )
		{
			return $this->$methodName( $value );
		}

		if ( in_array( $methodName, get_class_methods( "patForms_FormatChecker" ) ) )
		{
			return call_user_func( array( 'patForms_FormatChecker', $methodName ), $value );
		}

		return false;
	}

   /**
	* get next error offset
	*
	* @access     public
	* @return     integer
	*/
	function getErrorOffset( $requiredCodes = 100 )
	{
		$offset					= $this->nextErrorOffset;
		$this->nextErrorOffset	= $this->nextErrorOffset + $requiredCodes;
		return $offset;
	}

   /**
	* add error codes and messages for validator method
	*
	* @access     public
	* @param      array	defintions
	* @param      integer	offset for the error codes
	*/
	function addValidatorErrorCodes( $defs, $offset = 1000 )
	{
		foreach ( $defs as $lang => $codes )
		{
			if ( !isset( $this->validatorErrorCodes[$lang] ) ) {
				$this->validatorErrorCodes[$lang]	=	array();
			}

			foreach ( $codes as $code => $message ) {
				$this->validatorErrorCodes[$lang][($offset+$code)]	=	$message;
			}
		}
	}

	/**
	* getValidationErrors
	*
	* @access     public
	* @return     array	errors that occured during the validation
	*/
	function    getValidationErrors()
	{
		return  $this->validationErrors;
	}

	/**
	* addValidationError
	*
	*
	* @access     public
	* @param      integer	$code
	* @param      array	$vars	fill named placeholder with values
	* @return     boolean $result	true on success
	*/
	function    addValidationError( $code, $vars = array() )
	{
		$error		=	false;
		$lang		=	$this->locale;
		$element	=	$this->getElementName();

		// find error message for selected language
		while ( true )
		{
			// error message matches language code
			if ( isset( $this->validatorErrorCodes[$lang][$code] ) )
			{
				$error	=	array( "element" => $element, "code" => $code, "message" => $this->validatorErrorCodes[$lang][$code] );
				break;
			}
			// no message found and no fallback-langauage available
			else if ( $lang == "C" )
			{
				break;
			}

			$lang_old	=	$lang;

			// look for other languages
			if ( strlen( $lang ) > 5 )
			{
				list( $lang, $trash	) =	explode( ".", $lang );
			}
			else if ( strlen( $lang ) > 2 )
			{
				list( $lang, $trash	) =	explode( "_", $lang );
			}
			else
			{
				$lang	=	"C";
			}

			// inform developer about missing language
			patErrorManager::raiseNotice(
				PATFORMS_ELEMENT_ERROR_VALIDATOR_ERROR_LOCALE_UNDEFINED,
				"Required Validation Error-Code for language: $lang_old not available. Now trying language: $lang",
				"Add language definition in used element or choose other language"
			);

		}

		// get default Error!
		if ( !$error )
		{
	 		patErrorManager::raiseWarning(
				PATFORMS_ELEMENT_ERROR_VALIDATOR_ERROR_UNDEFINED,
				"No Error Message for this validation Error was defined",
				"Review the error-definition for validation-errors in your element '$element'."
			);
			$error	=	array( "element" => $element, "code" => 0, "message" => "Unknown validation Error" );
		}

		// insert values to placeholders
		if ( !empty( $vars ) )
		{
			foreach ( $vars as $key => $value )
			{
				$error["message"]	=	str_replace( "[". strtoupper( $key ) ."]", $value, $error["message"] );
			}
		}

		array_push( $this->validationErrors, $error );
		$this->valid	=	false;
		return  true;
	}

   /**
	* applies the specified modifiers to an attribute value, as set in the attribute definition.
	*
	* @access     private
	* @param      mixed	$attributeValue	The value of the attribute to modify
	* @param      array	$modifiers		Array containing the list of modifiers and their options to apply.
	* @return     mixed	$attributeValue	The modified attribute value.
	* @see        createAttributes()
	*/
	function _applyModifiers( $attributeValue, $modifiers )
	{
		if ( !is_array( $modifiers ) )
		{
			return patErrorManager::raiseError(
				PATFORMS_ELEMENT_ERROR_MODIFIER_NOT_AN_ARRAY,
				"Modifiers are not an array"
			);
		}

		foreach ( $modifiers as $modifier => $modifierOptions )
		{
			// compute method name for this definition and check if it exists
			$modifierMethod	=	"_modifier".ucfirst( $modifier );

			if ( !method_exists( $this, $modifierMethod ) )
			{
				return patErrorManager::raiseError(
					PATFORMS_ELEMENT_ERROR_METHOD_FOR_MODIFIER_NOT_FOUND,
					"Method not found for modifier '" . $modifier . "' (".$modifierMethod.") in class '" . get_class( $this ) . "'"
				);
			}

			$modifiedValue	=	$this->$modifierMethod( $attributeValue );

			if ( $modifiedValue === false )
			{
				return patErrorManager::raiseError(
					PATFORMS_ELEMENT_ERROR_MODIFIER_RETURNED_ERROR,
					"Modifier '".$modifier."' returned an error."
				);
			}

			$attributeValue	=	$modifiedValue;
		}

		return $attributeValue;
	}

   /**
	* insertSpecials attribute value modifier
	*
	* you can use special placeholders to insert dynamic values into the attribute values.
	* This method inserts the correct information for each placeholder in the given string.
	*
	* @access     private
	* @param      string	$string	The string to insert the specials in
	* @return     string	$string	The string with all needed replacements
	* @see        _applyModifiers()
	* @todo       Maybe make this configurable
	* @todo       Add any other relevant information
	*/
	function _modifierInsertSpecials( $modifyValue, $options = array() )
	{
		if ( is_array( $modifyValue ) || is_object( $modifyValue ) || is_array( $this->value ) )
			return $modifyValue;

		// go through each attribute in the attribute definition and replace the strings
		// with the corresponding attribute values.
		foreach ( $this->attributeDefinition as $attributeName => $attributeDef )
		{
			// if attribute was not set, strip the variable by setting it to empty.
			$attributeValue	=	"";

			// retrieve real attribute value if it was set
			if ( isset( $this->attributes[$attributeName] ) && is_string( $this->attributes[$attributeName] ) )
			{
				$attributeValue	=	$this->attributes[$attributeName];
			}

			$search	=	$this->modifierStart."ELEMENT_".strtoupper( $attributeName ).$this->modifierEnd;

			// make the replacement
			$modifyValue	=	str_replace( $search, $attributeValue, $modifyValue );
		}

		// the element's value is special...
		$modifyValue	=	str_replace( $this->modifierStart."ELEMENT_VALUE".$this->modifierEnd, $this->value, $modifyValue );

		return $modifyValue;
	}

   /**
	* checks the format of an attribute value according to the given format.
	*
	* @access     private
	* @param      mixed	$attributeValue	The attribute value to check
	* @param      string	$format			The format to check the attribute value against
	* @return     bool	$result			True if format check succeeded, false otherwise.
	* @see        createAttributes()
	* @todo       Implement this method sometime
	*/
	function _checkAttributeFormat( $attributeValue, $format )
	{
		return true;
	}

   /**
	* validates the current attribute collection according to the attributes definition
	* and the given output format, and returns the list of valid attributes.
	*
	* @access     private
	* @param      string	$format		The output format to retrieve the attributes for.
	* @return     mixed	$attributes	The list of attributes, or false if failed.
	*/
	function getAttributesFor( $format )
	{
		$attributes	=	array();

		foreach ( $this->attributeDefinition as $attributeName => $attributeDef )
		{
			if ( !isset( $this->attributes[$attributeName] ) )
			{
				if ( $attributeDef["required"] )
				{
					return patErrorManager::raiseError(
						PATFORMS_ELEMENT_ERROR_ATTRIBUTE_REQUIRED,
						'The element "'.$this->getElementName().'" needs the attribute "'.$attributeName.'" to be set.',
						'See the attribute definition of the element class "'.get_class( $this ).'"'
					);
				}

				continue;
			}

			$attributeValue	=	$this->attributes[$attributeName];

			// special case disabled attribute: skip this if it is not set to yes
			// to avoid generating a disabled field anyway (empty HTML attribute)
			if ( $attributeName == 'disabled' && $attributeValue != 'yes' )
			{
				continue;
			}

			if ( isset( $attributeDef["modifiers"] ) && !empty( $attributeDef["modifiers"] ) )
			{
				$modifiedValue	=	$this->_applyModifiers( $attributeValue, $attributeDef["modifiers"] );
				if ( $modifiedValue === false )
				{
					return patErrorManager::raiseError(
						PATFORMS_ELEMENT_ERROR_UNABLE_TO_APPLY_MODIFIER_TO_ATTRIBUTE,
						"Could not apply modifier to attribute '".$attributeName."' (value:'".$attributeValue."')"
					);
				}

				$attributeValue	=	$modifiedValue;

				// store this for later use too
				$this->attributes[$attributeName]	=	$attributeValue;
			}

			if ( !in_array( $format, $attributeDef["outputFormats"] ) )
			{
				continue;
			}

			if ( isset( $attributeDef["format"] ) )
			{
				if ( !$this->_checkAttributeFormat( $attributeValue, $attributeDef["format"] ) )
				{
					return patErrorManager::raiseError(
						PATFORMS_ELEMENT_ERROR_CAN_NOT_VERIFY_FORMAT,
						"Format '".$attributeDef["format"]."' could not be verified for attribute '".$attributeName."' => '".$attributeValue."'"
					);
				}
			}

			$attributes[$attributeName]	=	$attributeValue;
		}

		return $attributes;
	}

   /**
	* [helper method] wrapper for the {@link createTag()} method which automates the tag
	* creation by creating the tag from the current attribute collection and element type.
	*
	* @access     protected
	* @return     mixed	$result	The created tag, or false if failed.
	* @see        elementType
	* @see        attributes
	* @see        createTag()
	*/
	function toHtml()
	{
		$attributes	= $this->getAttributesFor( $this->getFormat() );
		if ( patErrorManager::isError( $attributes ) )
		{
			return $attributes;
		}

		return $this->createTag( $this->elementType[$this->getFormat()], "full", $attributes );
	}

   /**
	* [helper method] create a hidden field with the given value. Retrieves all other needed
	* attributes from the attributes collection.
	* @access     public
	*/
	function createHiddenTag( $value )
	{
		$attribs	=	array(	'type'	=>	'hidden',
								'name'	=>	$this->attributes['name'],
								'value'	=>	$value,
								'id'	=>	$this->attributes['id'],
							);

		return $this->createTag( "input", "full", $attribs );
	}

   /**
	* [helper method] creates a hidden field with the given value. Used for the
	* display=no attribute, and is the same as the createHiddenTag() method, only
	* that the attributes collection is initialized to ensure that any variables
	* in the element's attributes  get replaced.
	*
	* @access     private
	* @param      mixed	$value		The value of the element
	* @return     string	$element	The serialized hidden tag
	* @see        createHiddenTag()
	*/
	function createDisplaylessTag( $value )
	{
		// call this to initialize all attributes. This is needed
		// here to make sure that if there are
		$this->getAttributesFor( $this->getFormat() );

		return $this->createHiddenTag( $value );
	}

   /**
	* [helper method] create an element HTML source from its attribute collection and
	* returns it.
	*
	* @static
	* @access     protected
	* @param      string	$tagname		The name of the element / tag
	* @param      string	$type			Optional: the type of element to generate. Valid parameters are full|opening|closing|empty. Defaults to "full".
	* @param      mixed	$value			The value of the element
	* @return     string	$element		The HTML source of the element
	*/
	function createTag( $tagname, $type = "full", $attributes = array(), $value = false )
	{
		switch( $type )
		{
			case "closing":
				return	"</$tagname>";
				break;

			case "empty":
			case "opening":
				$tag	=	"<".$tagname;

				// create attribute collection
				foreach ( $attributes as $attributeName => $attributeValue )
				{
					$tag	=	$tag . " ".$attributeName."=\"".htmlentities( (string)$attributeValue )."\"";
				}

				// empty tag?
				if ( $type == "empty" )
				{
					$tag	=	$tag . " />";
					return	$tag;
				}

				$tag	=	$tag . ">";
				return	$tag;

				break;

			case "full":
				if ( $value === false )
				{
					return patForms_Element::createTag( $tagname, "empty", $attributes );
				}

				return patForms_Element::createTag( $tagname, "opening", $attributes ).htmlentities( $value ).patForms_Element::createTag( $tagname, "closing" );
				break;
		}
	}

   /**
	* create XML representation of the element
	*
	* This can be used when you need to store the structure
	* of your form in flat files or create form templates that can
	* be read by patForms_Parser at a later point.
	*
	* @access     public
	* @param      string		namespace
	* @uses       getElementName()
	* @see        patForms_Parser
	*/
	function toXML( $namespace = null )
	{
		$tagName	=	$this->getElementName();

		// prepend Namespace
		if ( $namespace != null )
		{
			$tagName	=	$namespace.':'.$tagName;
		}

		// get all attributes
		$attributes	=	$this->getAttributes();

		// create valid XML attributes
		foreach ( $attributes as $key => $value )
		{
			$attributes[$key]	=	strtr( $value, $this->xmlEntities );
		}

		$value	=	strtr( $this->getValue(), $this->xmlEntities );

		if ( $value != false )
		{
			return	$this->createTag( $tagName, "full", $attributes, $value );
		}
		return	$this->createTag( $tagName, "empty", $attributes );
	}

   /**
	* apply a filter
	*
	* This is still in alpha state!
	*
	* @access     public
	* @param      object patForms_Filter
	* @todo       add error management and docs
	* @todo       allow filter to be an array containg two callbacks
	*			array( 'in' => 'myInFunc', 'out' => 'myOutFunc' ) )
	*/
	function applyFilter( &$filter )
	{
		$this->filters[]	=	&$filter;
		return true;
	}

   /**
	* Get the name of the element, as stored in the elementName property.
	*
	* This is used when serializing an element to XML to
	* create a now form template.
	*
	* This method checks for the $elementName property and if it
	* is set to null, it will extract the element name from the class name
	*
	* @access     public
	* @return     string		tag name
	*/
	function getElementName()
	{
		if ( $this->elementName != null )
		{
			return	$this->elementName;
		}

		$class	=	get_class( $this );
		$name	=	substr( strrchr( $class, "_" ), 1 );
		return	ucfirst( $name );
	}

   /**
	* checks wheter sessions are used or switch session usage on or of
	*
	* If switch argument is missing, this function just reports if sessions
	* will be used or not
	*
	* @access     protected
	* @param      string $switch switch sessions on ("yes") or off ("yes")
	* @return     boolean $result true if sessions will be used, false otherwise
	* @see        setSessionValue()
	* @see        getSessionValue()
	* @see        unsetSessionValue()
	* @todo       destroy session variables if sessions won't be usead any further
	*/
	function useSession( $switch = null )
	{
		// switch sessions on or off
		if ( $switch == "yes" )
		{
			$this->attributes["usesession"]	=	"yes";
		}
		else if ( $switch == "no" )
		{
			$this->attributes["usesession"]	=	"no";
			return false;
		}

		if ( isset( $this->attributes["usesession"] ) && $this->attributes["usesession"] == "yes" )
		{
			if ( !$this->sessionVar )
			{
				if ( !defined( "SID" ) )
				{
					session_start();
				}

				$name	=	$this->attributes["name"];
				if ( !isset( $_SESSION["_patforms_element"][$name] ) )
				{
					$_SESSION["_patforms_element"][$name]	=	array();
				}

				$this->sessionVar	=&	$_SESSION["_patforms_element"][$name];
			}

			return true;
		}
		return false;
	}

   /**
	* save a variable to the session
	*
	* @access     protected
	* @param      string $name name to identify the variable
	* @param      mixed $value
	* @return     boolean $result true on success
	* @see        getSessionValue()
	* @see        unsetSessionValue()
	*/
	function setSessionValue( $name, $value )
	{
		if ( !$this->useSession() )
		{
			return false;
		}

		$this->sessionVar[$name]	=	$value;
		return true;
	}

   /**
	* get a variable from session
	*
	* @access     protected
	* @param      string $name name to identify the variable
	* @return     mixed $result false if no sessions are used, null if variable is not set or the value of the variable
	* @see        getSessionValue()
	* @see        unsetSessionValue()
	*/
	function getSessionValue( $name )
	{
		if ( !$this->useSession() )
		{
			return false;
		}

		if ( isset( $this->sessionVar[$name] ) )
		{
			return $this->sessionVar[$name];
		}
		return null;
	}

   /**
	* remove a variable from session
	*
	* @access     protected
	* @param      string $name name to identify the variable
	* @return     mixed $result false if no sessions are used, null if variable is not set or the value of the variable
	* @see        getSessionValue()
	* @see        setSessionValue)
	*/
	function unsetSessionValue( $name )
	{
		if ( !$this->useSession() )
		{
			return false;
		}

		$value	=	null;
		if ( isset( $this->sessionVar[$name] ) )
		{
			$value	=	$this->sessionVar[$name];
			unset( $this->sessionVar[$name] );
		}
		return $value;
	}

   /**
	* get the global javascript of the element
	*
	* @access     public
	* @return     string
	*/
	/*
	function getGlobalJavascript()
	{
		if ( !isset( $this->globalJavascript[$this->format] ) )
		{
			$script	=	'';
		}
		else
		{
			$script	=	$this->globalJavascript[$this->format];
		}

		$cnt	=	count( $this->_rules );
		for ( $i = 0; $i < $cnt; $i++ )
		{
			$tmp	=	$this->_rules[$i]['rule']->getGlobalJavascript();
			if ( $tmp === false )
				continue;
			$script	.=	$tmp;
		}

		return $script;
	}
	*/

   /**
	* get the instance javascript of the element
	*
	* @access     public
	* @return     string	javascript for this instance
	*/
	/*
	function getInstanceJavascript()
	{
		if ( !isset( $this->instanceJavascript[$this->format] ) )
		{
			$script	=	'';
		}
		else
		{
			$script	=	$this->instanceJavascript[$this->format];

			$script	=	str_replace( '[ELEMENT::NAME]', $this->getName(), $script );
			$script	=	str_replace( '[ELEMENT::ID]', $this->getId(), $script );
		}

		$cnt	=	count( $this->_rules );
		for ( $i = 0; $i < $cnt; $i++ )
		{
			$tmp	=	$this->_rules[$i]['rule']->getInstanceJavascript();
			if ( $tmp === false )
				continue;
			$script	.=	$tmp;
		}

		return $script;
	}
	*/

	function registerJavascripts(&$form) {

		if ($script = $this->getGlobalJavascript()) {
			$form->registerGlobalJavascript($this->elementName, $script);
		}

		if ($script = $this->getInstanceJavascript()) {
			$form->registerInstanceJavascript($script);
		}

		foreach ($this->_rules as $rule) {
			$rule['rule']->registerJavascripts($form);
		}
	}

	function getGlobalJavascript() {

		if (isset($this->globalJavascript[$this->format])) {
			return $this->globalJavascript[$this->format];
		}
	}

	function getInstanceJavascript() {

		if (isset($this->instanceJavascript[$this->format])) {
			$script	= $this->instanceJavascript[$this->format];
			$script	= str_replace('[ELEMENT::NAME]', $this->getName(), $script);
			$script	= str_replace('[ELEMENT::ID]', $this->getId(), $script);
			return $script;
		}
	}

   /**
	* retrieves the element's current submitted state.
	*
	* @access     public
	* @return     bool	$state	True if it has been submitted, false otherwise.
	* @see        submitted
	*/
	function isSubmitted()
	{
		if ( $this->submitted === true ) {
			return true;
		}
		return false;
	}

   /**
	* returns the locale that is currently set for the form.
	*
	* @access     public
	* @return     string	$locale	The locale.
	* @see        setLocale()
	* @see        $locale
	*/
	function getLocale()
	{
		return $this->locale;
	}

   /**
	* anounce a change in the element to all observers
	*
	* @access     private
	* @param      string		property that changed
	* @param      mixed		new value of the property
	*/
	function _announce( $property, $value )
	{
		$cnt = count( $this->observers );
		for ( $i = 0; $i < $cnt; $i++ )
		{
			$this->observers[$i]->notify( $this, $property, $value );
		}
		return true;
	}
}