Abstract Class ZFormElement

Description

Implements interfaces:

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


	
			
Direct descendents
Class Description
 class ZFormWebElement
Class Constant Summary
Variable Summary
Method Summary
 void __construct ([string $id = null], [ZFormElement $parentNode = null])
 void addEventListener (string $type, mixed $listener)
 void addValidator (ZFormElementValidator $validator)
 void fireEvent (ZFormElementEvent $event)
 string getAttribute (string $name)
 array getAttributes ()
 array getBehaviors ()
 array getChildNodes ()
 ZFormElement getElementById (string $id, [boolean $recursive = false])
 string getErrorMessage (ZFormElement $child)
 array getEventListeners ([ $type = null])
 string getID ()
 string getIDPath ()
 boolean getIsProcessing ()
 mixed getMemento ()
 array getValidators ()
 mixed getValue ()
 boolean hasChildNodes ()
 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 (boolean $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:
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)
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)
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)
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, [boolean $recursive = false])
  • string $id
  • boolean $recursive: true - recursively search child, false - child search the children
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)
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:
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:
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)

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)
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)
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 = ''])
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

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:
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)
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 (boolean $process)
  • boolean $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:
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)
_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)
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 Thu, 18 Jan 2007 10:01:34 -0800 by phpDocumentor 1.3.1