## ZFormElement

Description

Implements interfaces:

- ZFormElementEventListenerInterface

- abstract:
- license: Zend Framework License version 1.0
- copyright: Copyright (c) 2005-2006 Zend Technologies USA Inc. (http://www.zend.com)

Located in /library/Zend/Form/ZFormElement.php (line 47)

Direct descendents

Class | Description
--- | ---
ZFormWebElement |

Class Constant Summary
PATH_SEPARATOR = '-'
Variable Summary
array; $_attributes
array $_behaviors
array $_childNodes
boolean $_eatEvents
mixed $_errors
array $_eventListeners
array $_events
string $_idPath
ZFormElement $_parentNode
toolean $_process
array $_validators
Method Summary
void __construct ([string $id = null], [ZFormElement $parentNode = null])
void addBehavior (ZFormElementBehaviorAbstract $behavior)
void addEventListener (string $type, mixed $listener)
void addValidator (ZFormElementValidator $validator)
ZFormElement appendChild (ZFormElement $child)
void fireEvent (ZFormElementEvent $event)
string getAttribute (string $name)
array getAttributes ()
array getBehaviors ()
array getChildNodes ()
ZFormElement getElementById (string $id, [mixed $recursive = false])
string getErrorMessage (ZFormElement $child)
array getEventListeners ([ $type = null])
string getID ()
string getIDPath ()
boolean getIsProcessing ()
mixed getMemento ()
ZFormElement getParentNode ()
ZFormElement getRoot ()
array getValidationErrors ()
array getValidators ()
mixed getValue ()
void handleEvent (ZFormElementEvent $event)
boolean hasChildNodes ()
void invokeApplication ()
boolean loadRequestData ()
void persist ()
void process ()
boolean removeChild (ZFormElement $child)
boolean removedBehavior (ZFormElementBehavior $behavior)
boolean removedValidator (ZFormElementValidator $validator)
void removeEventListener (string $type, [ZFormElementEventListenerInterface $listener = ''])
boolean restoreState ()
void setAllowEvents (boolean $allow)
void setAttribute (string $name, $value)
void setID (string $id)
void setMemento ( $memento)
void setParentNode (ZFormElement $parent)
void setProcess (mixed $process)
void setValue (mixed $value)
array validate ()
boolean _appendToList (mixed $item, array &$list)
string _computeIDPath ()
void _gatherMementos (ZFormElement $visiting, &$mementos, array $mementos)
boolean _isLegalName (string $id)
void _performValidation ([ &$errors = null], array $errors)
boolean _processEvents ()
boolean _removeFromList (mixed $element, array &$list)
void _restoreMementos (ZFormElement $visiting, &$mementos, array $mementos)
Variables
array; $_attributes = null (line 107)

Associative array containing the attributes associated with the element

- access: protected

array $_behaviors = null (line 85)

Contains the list of client side behaviors registered on

this element

- access: protected

array $_childNodes = null (line 92)

Contains the list of children associated with the element

- access: protected

boolean $_eatEvents = false (line 124)

Boolean property specifing weather to allow events to fire or not.

- access: protected

mixed $_errors = null (line 78)

- access: protected

array $_eventListeners = null (line 69)

Contains the list of client event hooks registered on

this element

- access: protected

array $_events = null (line 62)

Contains the list of the server side events to be fired

this element

- access: protected

string $_idPath = null (line 117)

The full path name of the element. Elements must be uniquely identified within the context of their parent. The _idPath is construct by combining the parent references and the ID of the element into a path separated by PATH_SEPARATOR.

- access: protected

ZFormElement $_parentNode = null (line 99)

Contains a reference to the parent of the element

- access: protected

toolean $_process = false (line 132)

Boolean property used to signify if processing of the element should continue

- access: protected

array $_validators = null (line 76)

Contains the list of client/server side validators registered on

this element

- access: protected

Methods
Constructor __construct (line 153)

Class constructor. Initializes internal instance variables. $id is

optional however it is recommended the each element by name. If an $id is not passed a unique one will be generated. Additionally, if a $parentNode is passed upon exit from the constructor the new instance is appended to the child list.

- access: public
- throws: ZFormElementException When the ID collides within the parent name space.

void __construct ([string $id = null], [ZFormElement $parentNode = null])

- string $id: Optional unique name within the context of the $parentNode if not specified a unique one will be generated.
- ZFormElement $parentNode: The parent element of the element being created

Redefined in descendants as:

- ZFormWebElement::__construct()
- ZForm::__construct() : Class constructor. Sets up the ZForm element, types it a a 'FORM' element
- ZFormInputElement::__construct() : Class constructor. Sets up the ZForm element, types it as a 'INPUT' element.
- ZFormButton::__construct() : Class constructor. Sets up the ZForm element, types it as a 'FORM' element
- ZFormCheckbox::__construct() : Class constructor. Sets up the ZForm element, types it as a 'CHECKBOX' element
- ZFormEntryField::__construct() : Class constructor. Sets up the ZForm element, types it as a 'TEXT' element
- ZFormFile::__construct() : Class constructor. Sets up the ZForm element, types it as a 'FILE' element
- ZFormHiddenField::__construct() : Class constructor. Sets up the ZForm element, types it as a 'HIDDEN' element
- ZFormImage::__construct() : Class constructor. Sets up the ZForm element, types it as a 'IMAGE' element
- ZFormPasswordField::__construct() : Class constructor. Sets up the ZForm element, types it as a 'PASSWORD' element.
- ZFormRadioButton::__construct() : Class constructor. Sets up the ZForm element, types it as a 'RADIO' element.
- ZFormResetButton::__construct() : Class constructor. Sets up the ZForm element, types it as a 'RESET' element.
- ZFormSubmitButton::__construct() : Class constructor. Sets up the ZForm element, types it as a 'SUBMIT' element.
- ZFormLink::__construct() : Class constructor.
- ZFormOption::__construct() : Class constructor. Sets up the ZForm element, types it as a 'OPTION' element.
- ZFormSelect::__construct() : Class constructor. Sets up the ZForm element, types it as a 'SELECT' element.

addBehavior (line 796)

Add the given behavior to the list of behaviors associated with the element. If the behavior is already contained in the list no action is taken. Elements support multiple behaviors on a FIFO basis. When a behaviors fails the remaining behaviors (if any) are not called.

- access: public

void addBehavior (ZFormElementBehaviorAbstract $behavior)

- ZFormElementBehavior $behavior

addEventListener (line 699)

Adds an event listener of the element for the given $type

- access: public

void addEventListener (string $type, mixed $listener)

- string $type: (@see ZFormElementEvent for event types)
- mixed $listener

addValidator (line 753)

Add the given validator to the list of validators associated with the element. If the validator is already contained in the list no action is taken. Elements support multiple validators on a FIFO basis. When a validator fails the remaining validators (if any) are not called.

- access: public

void addValidator (ZFormElementValidator $validator)

- ZFormElementValidator $validator

appendChild (line 321)

Adds the $child to the list of children associated with the element The parent of the $child is set to the element

- return: The newly added $child (the one passed in).
- access: public

ZFormElement appendChild (ZFormElement $child)

- ZFormElement $child

fireEvent (line 651)

Fire the given event into the element tree. Elements are not

delivered right away, they are queued for delivery at the appropriate time of the process cycle (@see process())

- access: public

void fireEvent (ZFormElementEvent $event)

- ZFormElementEvent $event

getAttribute (line 246)

Returns the value of the $name attribute associated with the element

- access: public

string getAttribute (string $name)

- string $name

getAttributes (line 269)

Return the associative array of attribute maintained by the element.

- access: public

array getAttributes ()
getBehaviors (line 824)

Returns the list (array) of behaviors associated with the element

- access: public

array getBehaviors ()
getChildNodes (line 217)

Return the list (array) of children contained by the element

- access: public

array getChildNodes ()
getElementById (line 839)

Returns the childs whose ID is $id. If the $recursive = true, continue search depth first for the child

- return: If found, null otherwise
- access: public

ZFormElement getElementById (string $id, [mixed $recursive = false])

- string $id

getErrorMessage (line 485)

Returns the error message originated by the $child

- return: The error message if the child generated an error message or ''
- access: public

string getErrorMessage (ZFormElement $child)

- ZFormElement $child

getEventListeners (line 737)

Simple getter for the event listeners associated with the web element

- return: All the events and listeners associated with the web elements Format: array(n) { ["submit"] => array(m) { [0] => eventlistener, [m] = eventlistener}, ["click"] => array(m) ....}
- access: public

array getEventListeners ([ $type = null])

- $type

getID (line 189)

Return simple ID of the element

- access: public

string getID ()
getIDPath (line 174)

Compute, if necessary, and return the fully qualified path of the element within the containment structured defined via the parentnode

- access: public

string getIDPath ()
getIsProcessing (line 472)

Returns the status of the processing flag

- return: true of the element is currently in a processing loop, false otherwise
- access: public

boolean getIsProcessing ()
getMemento (line 868)

Default implementation of retriving the memento associated with the element

that will be used during persistent (@see persist()) The default implementation does not persist anything, we implement it here so subclasses are not required to

- return: null for the default implementation, subclasses should override.
- access: public
- abstract:

mixed getMemento ()

Redefined in descendants as:

- ZFormWebElement::getMemento() : Default implementation of retriving the memento associated with the element
- ZFormInputElement::getMemento() : Retrieve the memento which will be stored with the session data representing the state of the input field. The default implemention is to simply ask the input element for its value
- ZFormCheckbox::getMemento() : Create a memento which saves the state of the Checkbox for storage in the session.
- ZFormImage::getMemento() : Create a memento which saves the state of the FormImage for storage in the session.
- ZFormRadioButton::getMemento() : Default implementation of retriving the memento associated with the element
- ZFormLink::getMemento() : Returns the memento used to persist the state of the link, which is simply the text.

getParentNode (line 280)

Return the parent node reference maintained by the element

- access: public

ZFormElement getParentNode ()
getRoot (line 202)

Searchs the parent chain defined by the _parentNode reference until the top of the tree is reached. If the element has no parents then the element is the 'root'

- access: public

ZFormElement getRoot ()
getValidationErrors (line 502)

Returns the array of validation errors associated with the element.

The array is an assoc array whose key is the ID path of the child element and the value which is an array of validators that reported the error

- access: public

array getValidationErrors ()
getValidators (line 782)

Returns the list of validators associated with the element

- access: public

array getValidators ()
getValue (line 364)

Abstract method used to retrive the value associated with the

element. Each element maintains an abstract value which can be changed which triggers a value change event. This method is abstract so subclasses can define the contents of that value

- access: public
- abstract:

mixed getValue ()

Redefined in descendants as:

- ZFormWebElement::getValue() : Overridden implementation of getValue which returns the 'value' attribute of the ZFormWebElement

handleEvent (line 884)

Default implementation of the ZFormElementEventListenerInterface interface which simply does nothing. Intended to make subclassing more easy.

- access: public

void handleEvent (ZFormElementEvent $event)

- ZFormElementEvent $event

Implementation of:

ZFormElementEventListenerInterface::handleEvent()
  This interface introduces the most basic of event handling protocol to elements. All elements implement this interface by default in ZFormElement

hasChildNodes (line 308)

Does the element contain children?

- access: public

boolean hasChildNodes ()
invokeApplication (line 574)

Abstract implementation of invoking the application component associated

with the element. This method simply recurs over the children of the element calling the invokeApplication of each child. Subclasses should call this method (e.g. parent::invokeApplication) to invoke application logic that is associated with its children

- access: public

void invokeApplication ()
loadRequestData (line 591)

Abstract implementation that interates of the children of the element invoking loadRequestData. During this phase of the processing cycle elements should retrieve input data from the ZRequest object

- return: true if all children were processed, false otherwise
- access: public

boolean loadRequestData ()

Redefined in descendants as:

- ZFormWebElement::loadRequestData() : Retrieves the data associated with this element from the ZRequest object.
- ZFormCheckbox::loadRequestData() : The method is called when a ZForm is being processed to give the ZFormCheckbox and opportunity to initialize itself even when there is not data being directly targed to the ZFormWebElement
- ZFormImage::loadRequestData() : The methods will loaded the x & y position of the image click into the ZFormImage component.
- ZFormRadioButton::loadRequestData() : Retrieves the data associated with this element from the ZRequest object.
- ZFormSelect::loadRequestData() : Abstract implementation that interates of the children of the element invoking loadRequestData. During this phase of the processing cycle elements should retrieve input data from the ZRequest object

persist (line 633)

Persists the elements to the session for subsequent restoration and presentation to the user (this is useful with multi-page forms).

Persisting an element consists of asking itself and each of its children for a memento which is place into the session object. Upon restoreState the memento is passed to the object for reconstitution.

- access: public

void persist ()
process (line 414)

This method (process) does much of the work associated with the element.

In general, ZFormElement enables the processing of input data(request and persistent) to be loaded/validated and committed to the application model. ZFormElements can be wired-up to each other so that events can be triggered in one element and consumed in another. Processing of an element and its children does not render the element tree, it simply gives the controls a chance to interact with each other and the controller of the application. Rendering is defined by subclasses and/or templating engines. Processing consists of: 1) If the element is persistent restore the saved state @see restoreState() 2) Allow events to be process after restoring the state 3) Ask the elements to load state from the request parameter. 4) Allow events to be process after loading data from request 5) Validate the data loaded 6) Allow events to be process after loading data from request 7) Invoke the application to allow the elements to communicate with the model 8) One last chance to process events NOTE: Events are queued during steps 1, 3, 5, 7 until the whole child tree has been visited.

- access: public

void process ()
removeChild (line 341)

Remove the given $child from the list (array) of children associated with the element

- return: true if removed, false otherwise
- access: public

boolean removeChild (ZFormElement $child)

- ZFormElement $child

removedBehavior (line 813)

Removes behavior from the list of behaviors associated with the element

- return: true if removed false otherwise
- access: public

boolean removedBehavior (ZFormElementBehavior $behavior)

- ZFormElementBehavior $behavior: The validator instance to remove

removedValidator (line 771)

Removes validator from the list of validators associated with the element

- return: true if removed false otherwise
- access: public

boolean removedValidator (ZFormElementValidator $validator)

- ZFormElementValidator $validator: The validator instance to remove

removeEventListener (line 676)

Remove the event listener associated with the given event type from the list of listeners. If $listener is not specified all events of the given type will be removed from the listeners

- access: public

void removeEventListener (string $type, [ZFormElementEventListenerInterface $listener = ''])

- string $type: (@see ZFormElementEvent for event types)
- ZFormElementEventListenerInterface $listener

restoreState (line 613)

An element can persist itself between requests (@see persist()), if so it is during this stage of the processing cycle that elements restore their state. Persistent data is retrieved from the session object under the elements idPath.

- access: public

boolean restoreState ()
setAllowEvents (line 721)

Turns of processing events, that is events delivered to the fireEvent method (@see fireEvent()) are not process, they are ignored

- access: public

void setAllowEvents (boolean $allow)

- boolean $allow: true - allow events, otherwise ignore them

setAttribute (line 258)

Set the value of the $name attribute within the element

- access: public

void setAttribute (string $name, $value)

- string $name
- $value

setID (line 232)

Sets the ID of the element. The ID is checked for validitiy within

the parent naming space. NOTE: IDs must be unique within the parent name space. If the name collides a ZFormElementException is thrown Additionally, the id path is recalcuated when the ID is changed

- access: public
- see: ZFormElement::_computeIDPath()

void setID (string $id)

- string $id

setMemento (line 876)

The bookend implementation to @see getMemento(). This function is a void

implementation of the protocol to simplify the task of subclassing

- access: public
- abstract:

void setMemento ( $memento)

- $memento

Redefined in descendants as:

- ZFormWebElement::setMemento() : The bookend implementation to @see getMemento(). This function is a void
- ZFormInputElement::setMemento() : Restores the state of the input element from its memento which was returned by getMemento above. The default implementation is to set the value of the input element to the memento.
- ZFormCheckbox::setMemento() : Restores the state of the checkbox from its memento which was returned by getMemento.
- ZFormImage::setMemento() : Restores the state of the ZFormImage from its memento which was returned by getMemento.
- ZFormRadioButton::setMemento() : The bookend implementation to @see getMemento(). This function is a void
- ZFormLink::setMemento() : Retores the state of the link from its memento

setParentNode (line 292)

Changes the parent node associated with the element to the new $parent specified in the parameter.

- access: protected

void setParentNode (ZFormElement $parent)

- ZFormElement $parent

setProcess (line 460)

Sets the processing flag, at any point during the process loop an element can terminate futher process by setting this flag to false

- access: public

void setProcess (mixed $process)
setValue (line 376)

Implementation of the setValue which ONLY generates a ONVALUECHANGE event if the new $value is different from the current value. This means the subclasses MUST call this implementation and store the value.

- access: public

void setValue (mixed $value)

- mixed $value

Redefined in descendants as:

- ZFormWebElement::setValue() : Overridden implementation of setValue which sets the 'value' of the attribute for the ZFormWebElement
- ZFormCheckbox::setValue() : Overrides setValue in the parent to also set the checked status of the ZCheckBox.
- ZFormRadioButton::setValue() : Overridden implementation of setValue which sets the 'value' of the attribute for the ZFormWebElement

validate (line 517)

Validates the element and all its children by applying the validators associated with the element and then recursively invoking validate on the children.

- return: an assoc array whose key is the ID path of the child element and the value which is an array of validators the reported the error.
- access: public

array validate ()
_appendToList (line 898)

Helper array management routines to add/remove and item if it doesn't already exist to an array

- return: true if added, false otherwise
- access: protected

boolean _appendToList (mixed $item, array &$list)

- mixed $item
- array &$list

_computeIDPath (line 937)

Generates the unique ID path for the element which consists of its ancestor IDs concatenated with the element's ID.

- access: protected

string _computeIDPath ()
_gatherMementos (line 1016)

Support methods for gathering and redistributing mementos to th children of the element (@see persist(), @see restoreState())

- access: protected

void _gatherMementos (ZFormElement $visiting, &$mementos, array $mementos)

- ZFormElement $visiting
- array $mementos
- &$mementos

_isLegalName (line 962)

Determines if a given $id is unique within the element children names.

- return: true or throws ZFormElementException
- access: protected
- throws: ZFormElementException

boolean _isLegalName (string $id)

- string $id

_performValidation (line 533)

Iterates over the validators associated with the elements and inokes the validator on the element. Errors are collected in the $errors array

- access: protected

void _performValidation ([ &$errors = null], array $errors)

- array $errors
- &$errors

_processEvents (line 986)

Process the list (array) of queued events ready for delivery (@see process(), @see fireEvent()).

- return: true of all child events were processed
- access: protected

boolean _processEvents ()
_removeFromList (line 916)

Helper array management that removes a given element for a list

- return: true if removed false otherwise
- access: protected

boolean _removeFromList (mixed $element, array &$list)

- mixed $element
- array &$list

_restoreMementos (line 1039)

Support methods for gathering and redistributing mementos to th children of the element (@see persist(), @see restoreState())

- access: protected

void _restoreMementos (ZFormElement $visiting, &$mementos, array $mementos)

- ZFormElement $visiting
- array $mementos
- &$mementos

Class Constants
PATH_SEPARATOR = '-' (line 55)

Elements are uniquely addressable via the path generated

by walking the parent chain and seperating each name segment with this string @see _computeIDPath()

Documentation generated on Tue, 11 Jul 2006 12:24:28 -0500 by phpDocumentor 1.3.0RC6