root/branches/gettext/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 );

/**
 * validateoin errors
 */
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',
    'autoFinalize'        =>    true,
    'defaultAttributes'    =>    array(),
    'elementCounter'    =>    0,
    'moduleDirs'        =>  array( '__all' => array() )
);

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

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

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

        '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();

   /**
    * add a directory where patForms should search for
    * modules.
    *
    * You may either pass a string or an array of directories.
    *
    * patTemplate will be searching for a module in the same
    * order you added them. If the module cannot be found in
    * the custom folders, it will look in
    * patForms/$moduleType.
    *
    * @static
    * @access   public
    * @param    string          module type or NULL for any
    * @param    string|array    directory or directories to search.
    */
    function addModuleDir($moduleType, $dir)
    {
        $dirs   =&  patForms::getStaticProperty( 'moduleDirs' );

        if (!is_array($dir)) {
            $dir    =   array($dir);
        }

        if ($moduleType === null) {
            $dirs['__all']  =   array_merge($dirs['__all'], $dir);
            return true;
        }

        if (!isset($dirs[$moduleType])) {
            $dirs[$moduleType]    =   array();
        }

        $dirs[$moduleType]    =   array_merge($dirs[$moduleType], $dir);
        return true;
    }
    
   /**
    * add a base directory where patForms should search for
    * modules.
    *
    * You may either pass a string or an array of directories.
    *
    * patForms will be searching for a module in the same
    * order you added them. It will first look in module specific 
    * directory (added with addModuleDir()), afterwards in module 
    * base dirs. If the module cannot be found in the custom 
    * folders, it will look in patForms/$moduleType.
    *
    * @static
    * @access   public
    * @param    string|array    directory or directories to search.
    * @see addModuleDir() 
    */
    function addModuleBaseDir($dir)
    {
        return patForms::addModuleDir(null, $dir);
    }

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

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

   /**
    * 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 far, and new ones inherit it too.
    *
    * @access    public
    * @param    bool    $state    True if it has been submitted, false otherwise (default).
    * @see        isSubmitted()
    * @see        submitted
    */
    function setSubmitted( $state )
    {
        if ($state == true) {
            $eventState    = $this->