root/tags/RELEASE_0_9_0B1/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 );

/**
 * locale file not found
 */
define('PATFORMS_WARNING_LOCALEFILE_NOT_FOUND', 1050);

/**
 * 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
 */
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()
    */
    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        boolean
    * @see        setAutoValidate(), renderForm()
    */
    var    $autoValidate = false;

   /**
    * flag to indicate, whether autovalidation has been
    * already called
    *
    * @access    private
    * @var        boolean
    */
    var    $autoValidateUsed = 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', 'onValidate', 'onSubmit', 'onError', 'onSuccess', 'onRender');

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

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

   /**
    * 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 default-encoding of the form / the site the form is displayed on.
    * 
    * This affects the encoding/decoding of html-entities in the form's element-value 
    * and attributes.
    * 
    * @static 
    * @access   public
    * @param    string  $encoding   the ISO code for the desired encoding (UTF-8, ISO-8859-1, ...)
    */
    function setDefaultEncoding( $encoding )
    {
        patForms::setStaticProperty( 'defaultEncoding', $encoding );
    }
   

   /**
    * 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);
            if (patErrorManager::isError($languageData)) {
                return $languageData;
            }
            $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 form's namespace
    *
    * @static
    * @access    public
    * @param    string        namespace
    * @return    string
    */
    function getNamespace()
    {
        return $this->namespace;
    }

   /**
    * set the form's namespace
    *
    * @static
    * @access    public
    * @param    string        namespace
    * @return    null
    */
    function setNamespace($namespace)
    {
        $this->namespace = $namespace;
        for($i=0; $i < count($this->elements); $i++) {
            $this->elements[$i]->setNamespace($namespace);
        }
    }

   /**
    * 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
    */
    function parseLocaleFile($filename)
    {
        if (!file_exists($filename) ||
            !is_file($filename) ||
            !is_readable($filename)) {
            return patErrorManager::raiseWarning(PATFORMS_WARNING_LOCALEFILE_NOT_FOUND, 'Could not locale-file ' . $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