root/tags/RELEASE_0_9_0a2/patForms.php

<?php
/**
 * patForms form manager class - serialize form elements into any given output format
 * using element classes, and build the output via renderer classes.
 *
 * $Id$
 *
 * @package        patForms
 * @author        Sebastian Mordziol <argh@php-tools.net>
 * @author        gERD Schaufelberger <gerd@php-tools.net>
 * @author        Stephan Schmidt <schst@php-tools.net>
 * @copyright    2003-2004 PHP Application Tools
 * @license        LGPL
 * @link        http://www.php-tools.net
 */

/**
 * set the include path
 */
if( !defined( 'PATFORMS_INCLUDE_PATH' ) ) {
    define( 'PATFORMS_INCLUDE_PATH', dirname( __FILE__ ). '/patForms' );
}

/**
 * location of global javascripts
 */
define('PATFORMS_SCRIPT_PATH', PATFORMS_INCLUDE_PATH . '/Scripts');

/**
 * needs helper methods of patForms_Element
 */
include_once PATFORMS_INCLUDE_PATH . "/Element.php";
 
/**
 * error definition: renderer base class file (renderers/_base.php) could not 
 * be found.
 *
 * @see    patForms::_createModule()
 */                                    
define( "PATFORMS_ERROR_NO_MODULE_BASE_FILE", 1001 );

/**
 * error definition: the specified renderer could not be found.
 *
 * @see    patForms::_createModule()
 */                                    
define( "PATFORMS_ERROR_MODULE_NOT_FOUND", 1002 );

/**
 * error definition: the element added via the {@link patForms::addElement()}
 * is not an object. Use the {@link patForms::createElement()} method to
 * create an element object.
 *
 * @see    patForms::addElement()
 * @see    patForms::createElement()
 */                                    
define( "PATFORMS_ERROR_ELEMENT_IS_NO_OBJECT", 1003 );

/**
 * error definition: generic unexpected error.
 */                                    
define( "PATFORMS_ERROR_UNEXPECTED_ERROR", 1004 );

/**
 * element does not exist
 */                                    
define( "PATFORMS_ERROR_ELEMENT_NOT_FOUND", 1012 );

/**
 * renderer object has not been set - if you want to render the form, you have to
 * set a renderer object via the {@link patForms::setRenderer()} method. To create
 * a renderer, use the {@link patForms::createRenderer()} method.
 *
 * @see    patForms::setRenderer()
 * @see    patForms::createRenderer()
 */                                    
define( "PATFORMS_ERROR_NO_RENDERER_SET", 1013 );

/**
 * invalid renderer
 *
 * @see    createRenderer()
 */                                    
define( "PATFORMS_ERROR_INVALID_RENDERER", 1014 );

/**
 * invalid method
 *
 * @see    setMethod()
 */                                    
define( "PATFORMS_ERROR_INVALID_METHOD", 1015 );

/**
 * Given parameter is not a boolean value
 */                                    
define( "PATFORMS_ERROR_PARAMETER_NO_BOOL", 1016 );

/**
 * Given Static property does not exist
 */
define( "PATFORMS_ERROR_NO_STATIC_PROPERTY", 1017 );

/**
 * Unknown event
 */
define( "PATFORMS_ERROR_UNKNOWN_EVENT", 1018 );

/**
 * Invalid event handler
 */
define( "PATFORMS_ERROR_INVALID_HANDLER", 1019 );

/**
 * Event exists
 */
define( 'PATFORMS_NOTICE_EVENT_ALREADY_REGISTERED', 1020 );

/**
 * Invalid storage container
 */
define( 'PATFORMS_ERROR_INVALID_STORAGE', 1021 );

define( 'PATFORMS_NOTICE_ARRAY_EXPECTED', 1022 );

define( 'PATFORMS_NOTICE_ATTRIBUTE_NOT_SUPPORTED', 1023 );

define( 'PATFORMS_NOTICE_INVALID_OPTION', 1024 );

define( 'PATFORMS_ERROR_ATTRIBUTE_REQUIRED', 1025 );

define( 'PATFORMS_ERROR_CAN_NOT_VERIFY_FORMAT', 1026 );

define( 'PATFORMS_ERROR_METHOD_FOR_MODE_NOT_AVAILABLE', 1027 );


/**
 * errors apply on translating errors matching current locale settings
 */
define( 'PATFORMS_NOTICE_VALIDATOR_ERROR_LOCALE_UNDEFINED', 1028 );
define( 'PATFORMS_WARNING_VALIDATOR_ERROR_UNDEFINED', 1029 );

/**
 * Script file could not be loaded
 */
define( 'PATFORMS_WARNING_SCRIPTFILE_NOT_FOUND', 1040 );

/**
 * apply the rule before the built-in validation
 */
define( 'PATFORMS_RULE_BEFORE_VALIDATION', 1 );
 
/**
 * apply the rule after the built-in validation
 */
define( 'PATFORMS_RULE_AFTER_VALIDATION', 2 );

/**
 * apply the rule before AND after the built-in validation
 */
define( 'PATFORMS_RULE_BOTH', 3 );
    
/**
 * attach the observer to the elements
 */
define( 'PATFORMS_OBSERVER_ATTACH_TO_ELEMENTS', 1 );

/**
 * attach the observer to the form
 */
define( 'PATFORMS_OBSERVER_ATTACH_TO_FORM', 2 );

/**
 * attach the observer to the form and the elements
 */
define( 'PATFORMS_OBSERVER_ATTACH_TO_BOTH', 3 );

/**
 * group values should stay nested
 */
define('PATFORMS_VALUES_NESTED', 0);

/**
 * group values should be flattened
 */
define('PATFORMS_VALUES_FLATTENED', 1);

/**
 * group values should be prefixed
 */
define('PATFORMS_VALUES_PREFIXED', 2);

/**
 * Static patForms properties - used to emulate pre-PHP5 static properties.
 * 
 * @see    setStaticProperty()
 * @see    getStaticProperty()
 */
$GLOBALS['_patForms']    =    array(
    'format'            =>    'html',
    'locale'            =>    'C',
    'customLocales'        =>    array(),
    'autoFinalize'        =>    true,
    'defaultAttributes'    =>    array(),
    'elementCounter'    =>    0,
);

/**
 * patForms form manager class - serialize form elements into any given output format
 * using element classes, and build the output via renderer classes.
 *
 * @package        patForms
 * @author        Sebastian Mordziol <argh@php-tools.net>
 * @author        gERD Schaufelberger <gerd@php-tools.net>
 * @author        Stephan Schmidt <schst@php-tools.net>
 * @copyright    2003-2004 PHP Application Tools
 * @license        LGPL
 * @link        http://www.php-tools.net
 * @version        0.9.0a2
 * @todo        check the clientside functionality, as that can lead to broken pages
 */
class patForms
{
   /**
    * javascript that will 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();

   /**
    * stores the mode for the form. It defaults to 'default', and is only overwritten if
    * set specifically. It is passed on to any elements you create.
    *
    * @access    private
    * @see        setMode()
    */
    var $mode    =    'default';
    
   /**
    * XML entities
    *
    * @access    private
    * @see        toXML()
    * @todo        This is redundant to the Element's xmlEntities property - find a way to keep this in one place
    */
    var $xmlEntities = array(
        "<"    =>    "&lt;",
        ">"    =>    "&gt;",
        "&"    =>    "&amp;",
        "'"    =>    "&apos;",
        '"'    =>    "&quot;"
    );

   /**
    * stores the format for the element. It defaults to 'html', and is only overwritten if
    * set specifically. It is passed on to any elements you create.
    *
    * @access    private
    * @see        setFormat()
    */
    var $format    =    'html';
    
   /**
    * stores the flag telling the form whether it has been submitted - this is passed on to any
    * elements you create.
    *
    * @access    private
    * @see        setSubmitted()
    */
    var $submitted    =    false;

   /**
    * stores the element objects of this form.
    * @access    private
    * @see        addElement()
    */
    var $elements    =    array();
    
   /**
    * stores a renderer
    * @access    private
    * @see        setRenderer(), renderForm()
    */
    var $renderer        =    null;
    
   /**
    * stores the locale to use when adding validation errors for the whole form.
    *
    * @access    private
    * @var        string    $locale
    * @see        setLocale()
    */
    var    $locale        =    'C';
    
   /**
    * stores custom locale
    *
    * @access    private
    * @var        array
    * @see        setLocale()
    */
    var    $customLocales = array();

   /**
    * stores the element name
    * @access    private
    * @see        getElementName()
    */
    var $elementName = 'Form';
    
   /**
    * flag to indicate, whether form should be validated automatically
    * by renderForm()
    *
    * @access    private
    * @var        string
    * @see        setAutoValidate(), renderForm()
    */
    var    $autoValidate    =    false;
    
   /**
    * name of the variable that indicates, whether the form has
    * been submitted.
    *
    * @access    private
    * @var        string
    * @see        setAutoValidate()
    */
    var    $submitVar    =    null;
    
   /**
    * event handlers
    *
    * @access    private
    * @var        array
    * @see        registerEventHandler()
    * @see        registerEvent()
    */
    var    $_eventHandler    =    array();
    
   /**
    * events that can be triggered
    *
    * @access    private
    * @var        array
    * @see        registerEventHandler()
    * @see        triggerEvent()
    * @see        registerEvent()
    */
    var    $_validEvents    =    array( 'onInit', 'onSubmit', 'onError', 'onSuccess' );
    
   /**
    * Stores whether the current form has been validated
    *
    * @access    private
    */
    var $validated    =    false;
    
   /**
    * Stores whether the current form is valid or not (after the 
    * validation process)
    *
    * @access    private
    */
    var $valid    =    null;
    
   /**
    * Stores the names of all static properties that patForms will use as defaults
    * for the properties with the same name on startup.
    *
    * @access    private
    */
    var $staticProperties    =    array(
        'format'        =>    'setFormat',
        'autoFinalize'    =>    'setAutoFinalize',
        'locale'        =>    'setLocale',
    );
    
   /**
    * Stores the flag for the autoFinalize feature
    *
    * @access    private
    */
    var $autoFinalize    =    true;

   /**
    * custom validation rules
    * 
    * @access    private
    * @var        array
    */
    var $_rules            =    array();
    
   /**
    * define error codes an messages for the form
    *
    * Will be set by validation rules that have been
    * added to the form.
    *
    * @access private
    * @var    array    $validatorErrorCodes
    */
    var    $validatorErrorCodes  =   array();

   /**
    * stores any validation errors that can occurr during the
    * form's validation process.
    *
    * @access    private
    * @var        array    $validationErrors
    */
    var    $validationErrors  =   array();
    
   /**
    * next error offset for rules
    * @access    private
    * @var        integer
    */
    var $nextErrorOffset    =    1000;

   /**
    * Attributes of the form - needed to generate the form tag
    *
    * @access    private
    * @var        array    $attributes
    * @see        setAttribute()
    */
    var    $attributes    =    array();
    
   /**
    * Attribute definition for the form - defines which attribute the form
    * itself supports.
    *
    * @access    public
    */
    var    $attributeDefinition    =    array(    
            
        'id' =>    array(    
            'required'        =>    false,
            'format'        =>    'string',
            'outputFormats'    =>    array( 'html' ),
        ),
        
        'name' => array(    
            'required'        =>    true,
            'format'        =>    'string',
            'outputFormats'    =>    array( 'html' ),
        ),
        
        'method' => array(    
            'required'        =>    true,
            'format'        =>    'string',
            'default'        =>    'post',
            'outputFormats'    =>    array( 'html' ),
        ),

        'action' => array(    
            'required'        =>    true,
            'format'        =>    'string',
            'outputFormats'    =>    array( 'html' ),
        ),

        'accept' => array(    
            'required'        =>    false,
            'format'        =>    'string',
            'outputFormats'    =>    array( 'html' ),
        ),

        'accept-charset' => array(    
            'required'        =>    false,
            'format'        =>    'string',
            'outputFormats'    =>    array( 'html' ),
        ),

        'enctype' => array(    
            'required'        =>    false,
            'format'        =>    'string',
            'outputFormats'    =>    array( 'html' ),
        ),

        'onreset' => array(    
            'required'        =>    false,
            'format'        =>    'string',
            'outputFormats'    =>    array( 'html' ),
        ),

        'onsubmit' => array(    
            'required'        =>    false,
            'format'        =>    'string',
            'outputFormats'    =>    array( 'html' ),
        ),

        'target' => array(    
            'required'        =>    false,
            'format'        =>    'string',
            'outputFormats'    =>    array( 'html' ),
        ),
    );
    
   /**
    * Stores all available patForms options - these are inherited by all elements
    * and their dependencies, like rules.
    *
    * Short option overview:
    *
    * - scripts: enable client script integration
    *
    * @access    public
    */
    var $options    =    array(

        'scripts'    =>    array(
            'enabled'    =>    false,
            'params'    =>    array(
                                    'folder'    => PATFORMS_SCRIPT_PATH,
                                    'jsInclude' => false
                                ),
        ),

    );
    
   /**
    * observers of the form
    *
    * @access    private
    * @var        array
    */
    var    $observers = array();

   /**
    * Sets the default attributes that will be inherited by any elements you add to the form.
    *
    * <b>Note:</b> You have to call this method statically before creating a new form if you use 
    * patForm's automatic element creation feature via the {@link createForm()} method, as the
    * default attributes cannot be set after an element has been created.
    *
    * @static
    * @access    public
    * @param    array    $attributes    The list of attributes to set with key => value pairs.
    */
    function setDefaultAttributes( $attributes )
    {
        patForms::setStaticProperty( 'defaultAttributes', $attributes );
    }
    
   /**
    * sets the locale (language) to use for the validation error messages of all elements
    * in the form.
    *
    * @access    public
    * @param    string        language code
    * @param    string        optional language file
    * @return    bool        True on success
    */
    function setLocale( $locale, $languageFile = null )
    {
        if (!is_null($languageFile)) {
            $languageData   = patForms::parseLocaleFile($languageFile);

            $customLocales = patForms::getStaticProperty('customLocales');
            $customLocales[$locale] = $languageData;
            patForms::setStaticProperty('customLocales', $customLocales);
        }

        if( isset( $this ) && is_a( $this, 'patForms' ) ) {
            $this->locale = $locale;
        
            if( !empty( $this->elements ) ) {
                $cnt    =    count( $this->elements );
                for( $i=0; $i < $cnt; $i++ ) {
                    $this->elements[$i]->setLocale( $locale );
                }
            }
        } else {
            patForms::setStaticProperty('locale', $locale);
        }
        
        return true;
    }

   /**
    * checks, whether a locale is a custom locale
    *
    * @static
    * @access    public
    * @param    string        locale name
    * @return    boolean
    */
    function isCustomLocale($locale)
    {
        $customLocales = patForms::getStaticProperty('customLocales');
        if (isset($customLocales[$locale])) {
            return true;
        }
        return false;
    }

   /**
    * get the custom locale for an element or a rule
    *
    * @static
    * @access    public
    * @param    string        locale
    * @param    string        key
    * @return    array
    */
    function getCustomLocale($locale, $key)
    {
        $customLocales = patForms::getStaticProperty('customLocales');
        if (!isset($customLocales[$locale])) {
            return false;
        }
        if (!isset($customLocales[$locale][$key])) {
            return false;
        }
        return $customLocales[$locale][$key];
    }
    
   /**
    * parses a locale file
    *
    * @access    private
    * @param    string        filename
    * @return    array        locale information
    * @todo        add some file checks
    */
    function parseLocaleFile($filename)
    {
        return parse_ini_file($filename, true);
    }
    
   /**
    * sets the format of the element - this will be passed on to any elements you create. If you
    * have already added some elements when you call this method, it will be passed on to them too.
    *
    * @access    public
    * @param    string    $format    The name of the format you have implemented in your element(s).
    * @return    bool    $result    True on success
    * @see        setMode()
    * @see        format
    * @see        serialize()
    */
    function setFormat( $format )
    {
        if( isset( $this ) && is_a( $this, 'patForms' ) )
        {
            $this->format    =    strtolower( $format );
            
            if( !empty( $this->elements ) )
            {
                $cnt    =    count( $this->elements );
                for( $i=0; $i < $cnt; $i++ )
                {
                    $this->elements[$i]->setFormat( $format );
                }
            }
        }
        else
        {
            patForms::setStaticProperty( 'format', $format );
        }
        
        return true;
    }
    
   /**
    * sets the mode of the form - If you have already added some elements when you call this 
    * method, it will be passed on to them too.
    *
    * @access    public
    * @param    string    $mode    The mode to set the form to: default|readonly or any other mode you have implemented in your element class(es). Default is 'default'.
    * @see        setMode()
    * @see        mode
    * @see        serialize()
    */
    function setMode( $mode )
    {
        $this->mode    =    strtolower( $mode );

        if( !empty( $this->elements ) )
        {
            $cnt    =    count( $this->elements );
            for( $i=0; $i < $cnt; $i++ )
            {
                $this->elements[$i]->setMode( $mode );
            }
        }
    }

   /**
    * sets the current submitted state of the form. Set this to true if you want the form
    * to pick up its submitted data. It will pass on this information to all elements that 
    * have been added so f