Flux CMS 1.5 : Vue détaillée de patForms.php

Classe: patForms - X-Ref

patForms form manager class - serialize form elements into any given output format
using element classes, and build the output via renderer classes.

setDefaultAttributes( $attributes ) X-Ref

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.

param: array $attributes The list of attributes to set with key => value pairs.

setLocale( $locale, $languageFile = null ) X-Ref

sets the locale (language) to use for the validation error messages of all elements
in the form.

param: string        language code
param: string        optional language file
return: bool        True on success

isCustomLocale($locale) X-Ref

checks, whether a locale is a custom locale

param: string locale name
return: boolean

getCustomLocale($locale, $key) X-Ref

get the custom locale for an element or a rule

param: string locale
param: string key
return: array

parseLocaleFile($filename) X-Ref

parses a locale file

param: string filename
return: array locale information

setFormat( $format ) X-Ref

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.

param: string $format The name of the format you have implemented in your element(s).
return: bool $result True on success

setMode( $mode ) X-Ref

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.

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'.

setSubmitted( $state ) X-Ref

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.

param: bool $state True if it has been submitted, false otherwise (default).

setMethod( $method ) X-Ref

sets the method for the request

param: string $method GET or POST

setAction( $action ) X-Ref

sets the action for the form

This is a only a wrapper for setAttribute()

param: string $action

setAutoFinalize( $mode ) X-Ref

Sets the AutoFinalize mode for the form. The AutoFinalize mode will tell patForms to
finalize all elements after the form has been validated successfully.

param: boolean $mode Whether to activate the AutoFinalize mode (true) or not (false).
return: boolean $success True if okay, a patError object otherwise.

applyFilter( &$filter ) X-Ref

Wrapper method that adds a filter to all elements
of the form at once instead of having to do it for
each element.

param: object &$filter The filter object to apply

createForm( $formDefinition = null, $attributes = null ) X-Ref

creates a new patForms object and returns it; this method is made to be called statically
to be able to create a new patForms object from anywhere.

param: array    $formDefinition        Optional form definition for elements that will be added to the form
param: array    $attributes            The attributes to set for the form itself
return: object patForms    $form    The new patForms object.

addRule( &$rule, $time = PATFORMS_RULE_AFTER_VALIDATION, $invalid = false, $revalidate = false ) X-Ref

add a custom validation rule

param: object patForms_Rule    validation rule
param: integer                    time to apply rule (before or after built-in validation)
param: boolean                    apply the rule, even if the form is invalid
param: boolean                    should form get revalidated (not implemented yet)
return: boolean                    currently always true

__construct() X-Ref

patForms PHP5 constructor - processes some intitialization tasks like merging the currently
set static properties with the internal properties.

patForms() X-Ref

patForms pre-PHP5 constructor - does nothing for the moment except being a wrapper
for the PHP5 contructor for older PHP versions support.

setRenderer( &$renderer, $args = array() X-Ref

sets a renderer object that will be used to render
the form.

param: object &$renderer The renderer object
return: mixed $success True on success, patError object otherwise.

setStorage( &$storage ) X-Ref

sets a storage container object that will be used to store data

param: object patForms_Storage

renderForm( $args = null ) X-Ref

renders the form with the renderer that was set via the {@link setRenderer()}
method.

WARNING: This is still in alpha state!

Should this method return a reference??
The return value could contain large blocks of HTML or large arrays!
Do we want to copy these?

param: mixed $args arguments that will be passed to the renderer
return: mixed $form The rendered form, or false if failed.

validateForm( $revalidate = false ) X-Ref

Validates all elements of the form.

param: boolean Flag to indicate, whether form should be validated again, if it already has been validated.
return: boolean True if all elements could be validated, false otherwise.

_applyRules( $time, $isValid = true ) X-Ref

apply rules

param: integer        time of validation
param: boolean        form is valid
return: boolean        rules are valid or not

finalizeForm() X-Ref

Finalizes the form by telling each fom element to finalize - finalizing means to
process any tasks that need to be done after the form has been validated, like
deleting any temporary files or whatever an element needs to do at that point.

return: bool $success Wether all elements could be finalized

createRenderer( $name ) X-Ref

creates a new renderer from the patForms renderer collection and returns it.

param: string The name of the renderer to create - have a look at the Renderer/ subfolder for a list of available renderers.
return: object patForms_Renderer The renderer object, or error object

createStorage( $name ) X-Ref

creates a new storage container and returns it.

param: string The name of the storage to create - have a look at the Storage/ subfolder for a list of available storage containers.
return: object patForms_Storage The storage container, or error object

createFilter( $name, $params = null ) X-Ref

Creates a new filter and returns it.

You may pass an array as second parameter that contains
parameters for the filter. patForms will check for setter methods
for all keys and set the corresponding values.

This eases the creating of simple filter objects.

param: string                        The name of the filter to create - have a look at the Filter/ subfolder for a list of available filters.
param: array                        Optional parameters for the filter, if you provide a parameter, make sure the filter implements a set[Paramname]() method.
return: object patForms_Filter        The filter, or error object

createRule( $name, $id = null ) X-Ref

creates a new rule from the patForms rule collection and returns it.

If your rules are not located in patForms/Rule you have to load and
instantiate them on your own.

param: string                    The name of the rule to create - have a look at the Rule/ subfolder for a list of available rules.
param: string                    The id of the rule, needed if the rule uses client side actions.
return: object patForms_Rule    The rule object, or error object

createObserver( $name ) X-Ref

creates a new observer from the patForms observer collection and returns it.

If your observers are not located in patForms/Observer you have to load and
instantiate them on your own.

param: string The name of the observer to create - have a look at the Observer/ subfolder for a list of available observers.
return: object patForms_Observer The observer object, or error object

_createModule( $type, $name ) X-Ref

creates a new module for patForms

param: string    $type        type of the module. Possible values are 'Renderer', 'Rule'
param: string    $name        The name of the renderer to create - have a look at the renderers/ subfolder for a list of available renderers.
return: object    $module        The module object, or an error object

addElement( &$element ) X-Ref

adds an element to the form - has to be a patForms_Element object. Use the {@link createElement()}
method to create a new element object. Also takes care of passing on the form's configuration
including the mode, format and submitted flags to the element.

param: object &$element The patForms_Element object to add to this form.
return: bool $success True if everything went well, false otherwise.

replaceElement( $element, &$replace ) X-Ref

replaces an element in the form

param: object    $element    The patForms_Element object to be replaced
param: object    &$replace    The element that will replace the old element
return: bool    $success    True if everything went well, false otherwise.

getElement( $name ) X-Ref

Get an element by its name.

param: string $name name of the element
return: object patForms element

getElementByName( $name ) X-Ref

Get an element by its name.

param: string $name name of the element
return: mixed either a patForms element or an array containing patForms elements

getElementById( $id ) X-Ref

Get an element by its id.

param: string $id id of the element
return: object patForms element

getElements() X-Ref

Get all elements of the form

return: array all elements of the form

createElement( $name, $type, $attributes, $filters = null, $children = null ) X-Ref

Creates a new form element and returns a reference to it.

The optional $filters array has to be in the following format:

<pre>
array(
array(
'filter' => 'Multiplier',
'params' => array( 'multiplier' => 6 )
)
)
</pre>

param: string    $name        The name of the element
param: string    $type        The type of the element; for a list of possible elements, have a look at the elements/ subfolder of the patForms package.
param: array    $attributes    Attributes for the element
param: array    $filters    Optional filters that will be applied
return: object patForms_Element    $element    The element object, or patError if failed.

getValidationErrors($withElements = true) X-Ref

retrieves the validation errors from all elements in the form. Use this if the validateForm()
method returned false.

return: array $errors Array containing an array with validation errors for each element in the form.

getValues( $fields = null, $type = PATFORMS_VALUES_NESTED ) X-Ref

retrieves the values for all elements in the form.

param: array        desired fields
param: integer        Mode that should be used to return values in groups
return: array        The values for all elements, as elementname => elementvalue.

setValues( $values, $overrideUserInput = false ) X-Ref

sets the values for all elements in the form. Use this to fill your form with external
data, like a db query. Caution: if you do this and set the form to submitted, the values
will be overwritten by any values present in the $_GET or $_POST variables.

param: array $values The values for all elements, as elementname => elementvalue.

getMode() X-Ref

retrieves the current mode of the form

return: string $mode The current form mode

getLocale() X-Ref

returns the locale that is currently set for the form.

return: string $locale The locale.

getFormat() X-Ref

retrieves the current format of the form

return: string $format The current form format

getMethod() X-Ref

retrieves the current method of the form

return: string $method The request method

getAction() X-Ref

retrieves the current action of the form

return: string $action Action of the form

setAttribute( $attributeName, $attributeValue ) X-Ref

adds an atribute to the form's attribute collection. If the attribute
already exists, it is overwritten.

param: string $attributeName The name of the attribute to add
param: string $atributeValue The value of the attribute

setAttributes( $attributes ) X-Ref

adds several attributes at once to the form's attribute collection.
Any existing attributes will be overwritten.

param: array $attributes The attributes to add

getAttribute( $attribute ) X-Ref

retrieves the value of a form attribute.

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.

getAttributes( $attributes = array() X-Ref

retrieves all attributes of the form, or only the specified attributes.

param: array $attributes Optional: The names of the attributes to retrieve. Only the attributes that exist will be returned.
return: array $result The attributes

loadAttributeDefaults() X-Ref

Loads the default attribute values into the attributes collection. Done directly
on startup (in the consructor).

The action defaults to the path of the current script, with session
ID appended automatically, if SID has been defined.

return: bool $success Always returns true.

isSubmitted() X-Ref

retrieves the form's current submitted state.

If autoValidate is used, it will check for the submitVar and
set the submitted flag accordingly

return: bool $state True if it has been submitted, false otherwise.

createCreator( $type ) X-Ref

Creates a new patForms_Creator object

return: object $creator The creator object, or a patError object on failure

getElementName() X-Ref

get the element name of the form

return: string name of the form

getErrorOffset( $requiredCodes = 100 ) X-Ref

get next error offset

return: integer

addValidatorErrorCodes( $defs, $offset = 1000 ) X-Ref

add error codes and messages for validator method

param: array defintions
param: integer offset for the error codes

addValidationError( $code, $vars = array() X-Ref

add a validation error to the whole form

This can be achieved by adding a validation rule to the form.

param: integer    $code
param: array    $vars    fill named placeholder with values
return: boolean $result    true on success

getElementId() X-Ref

Retrieves a new element id, used to give each added element a unique id for this
form (id can be overwritten by setting the id attribute specifically).

return: int $elementId The new element id.

attachObserver( &$observer, $where = PATFORMS_OBSERVER_ATTACH_TO_ELEMENTS ) X-Ref

attach an observer

param: object patForms_Observer

serializeStart() X-Ref

Retrieve the content for the start of the form, including any
additional content, e.g. global scripts if the scripts option
is enabled.

return: string $formStart The form start content

serializeStartHtmlDefault() X-Ref

Serializes the form's start element for html format, in default mode.

return: mixed $formStart The serialized start content, or a patError object.

serializeStartHtmlReadonly() X-Ref

Serializes the form's start element for html format, in readonly mode.

return: mixed $formStart The serialized start content, or a patError object.

serializeEnd() X-Ref

Retrieve the content for the end of the form.

return: string $formEnd The form end content

serializeEndHtmlDefault() X-Ref

Retrieves the content for the end of the form for html format,
in default mode.

return: string $formEnd The form end content

serializeEndHtmlReadonly() X-Ref

Retrieves the content for the end of the form for html format,
in readonly mode.

return: string $formEnd The form end content

getAttributesFor( $format ) X-Ref

validates the current attribute collection according to the attributes definition
and the given output format, and returns the list of valid attributes.

param: string $format The output format to retrieve the attributes for.
return: mixed $attributes The list of attributes, or false if failed.

_checkAttributeFormat( $attributeValue, $format ) X-Ref

checks the format of an attribute value according to the given format.

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.

enableOption( $option, $params = array() X-Ref

Enables a patForms option.

See the {@link $options} property for an exhaustive list of available options.

param: string    $option        The option to enable
param: array    $params        Optional parameters for the option
return: mixed    $result        True on success, patError object otherwise.

disableOption( $option ) X-Ref

Disables a patForms option

See the {@link $options} property for an exhaustive list of available options.

param: string $option The option to disable
return: mixed $result True on success, patError object otherwise.

optionEnabled( $option ) X-Ref

Checks whether the given option is enabled.

param: string $option The option to check
return: bool $enabled True if enabled, false otherwise.

getOptionParameters( $option ) X-Ref

returns the parameters that have been supplied for an option

param: string $option The option to check
return: array

setAutoValidate( $submitVar ) X-Ref

Set the form to auto validate

If you use this method, patForms will check the _GET and _POST variables
for the variable you specified. If it is set, patForms assumes, that
the form has been submitted.

When creating a start tag for the form, the value will be inserted automatically.

param: string $submitVar

registerEvent( $name ) X-Ref

register a new event

After registering an event, you may register one or more
event handlers for this event an then trigger the event.

This lets you extend the functionality of patForms.

param: string event name
return: boolean true, if event could be registered

registerEventHandler( $event, $handler ) X-Ref

Register an event handler

An event handler can be any valid PHP callback. You may pass
one of the following values:
- string functionname to call a globally declared function
- array( string classname, string methodname) to call a static method
- array( object obj, string methodname) to call a method of an object

When the handler is called, two parameters will be passed:
- object form  : a patForms object
- string event : the name of the event has should be handled.

An event handler should always return true. If false is returned,
the event will be cancelled.

Currently handlers for the following events can be registered:
- onSubmit
- onSuccess
- onError

param: string    event name
param: mixed    event handler
return: boolean    true, if the handler could be registered

registerEventHandlerObject( &$obj, $methods = array() X-Ref

set event handler object.

An event handler object is used to handle all
registered events. The object has to provide methods
for all events it should handle, the names of the methods
have to be the same as the names of the events.

param: object event handler object
param: array method names, used to change the names of the methods
return: boolean

triggerEvent( $event ) X-Ref

Trigger an event

In most cases there's no need to call this event
from outside the class. The method is declared public
to allow you to trigger custom events.

param: string Event name. The event name must not contain 'on', as this will be

toXML( $namespace = null ) X-Ref

Serializes the entire form to XML, all elements included

param: string $namespace Optional namespace to use for the tags
return: string $xml The XML representation of the form

setStaticProperty( $property, &$value ) X-Ref

Set a static property.

Static properties are stored in an array in a global variable,
until PHP5 is ready to use.

param: string property name
param: mixed property value

getStaticProperty( $property ) X-Ref

Get a static property.

Static properties are stored in an array in a global variable,
until PHP5 is ready to use.

param: string property name
return: mixed property value

getName() X-Ref

Retrieves the form's name

If no name is set, it will use 'patForms' as name.

return: string $name The name of the form.

getScripts() X-Ref

get the javascript for the form

This is still in alpha state. It will later
allow client side validation if the element
provides this feature.

return: string javascript needed by the form

_announce( $property, $value ) X-Ref

anounce a change in the element to all observers

param: string property that changed
param: mixed new value of the property

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
Poids:	2819 lignes (70 kb)
Inclus ou requis:	0 fois
Référencé:	0 fois
Nécessite:	0 fichiers

Code source de Flux CMS 1.5

/inc/ -> patForms.php (sommaire)

Définit 1 class

Généré le : Wed Nov 21 13:08:55 2007	par Balluche grâce à PHPXref 0.7