Docs For Class Structures

void __construct(
mixed
$callback, [boolean
$submitObjects = false], [mixed
$errorCallback = null])

Constructor. Sets the callbacks then registers any default element or rule types.

A callback must be passed in so that the form knows what to do with the values that are collected by the form. Optionally, the user may tell the form to pass the widgets themselves, not the values, to the callback. The user may also define an error callback, which will be called if any rules are viloated. If no error callback is defined, the default callback ($this->defaultErrorCallback()) will be used. The default just passes the errors on to the renderer.

Throws: Structures_Form_Exception
Access: public

Parameters:

mixed	`$callback`	—	The method to call when the form is submitted.
boolean	`$submitObjects`	—	Send the widgets to the callback not the values.
mixed	`$errorCallback`	—	A callback for handling errors.

[ Top ]

object A addElement(
string
$type, string
$name)

Creates and adds an element to the form.

Only elements types that are registered with Structures_Form may be added to the form. This helps to ensure that the elements implement the proper interface.

To avoid overhead, type registration is not checked until the type is added to the form.

This method passes any extra arguments on to the element constructor. This allows one method to be used for creating many types of elements. The exact number and type of arguments that is passed to this method varies depending on the type of element to be created. If the wrong number or type of arguments is passed, the element constructor should throw an exception.

An exception may be thrown by createElement or addElementObject. If so it will be bubble up through this method.

Return: Structures_Form element
Throws: Structures_Form_Exception
Access: public

Parameters:

string	`$type`	—	The element type.
string	`$name`	—	The element name.

[ Top ]

object The addElementObject(
object
$element)

Adds an element to the form.

Only elements types that are registered with Structures_Form may be added to the form. This helps to ensure that the elements implement the proper interface.

To avoid overhead, type registration is not checked until the type is added to the form.

Return: added element.
Access: public

Parameters:

object $element —

[ Top ]

boolean addElementObjectToGroup(
string
$element, string
$group)

Adds an element object to a group.

A group is just a way to logically and visually group form elements. Elements can be added to or removed from a group without removing them from the form all together. However, obviously if the element is removed from the form, it will be removed from the group. If you readd the same element object, it will NOT be readded to the group.

This method returns true if the element has been added to the group and false in all other cases including when the element is not part of the form or the group does not exist.

Elements may only be part of one group. If the element is already part of another group, it will not be added to this group.

An element must be part of the form before it can be added to the group. This is normally not a problem as elements should be created using addElement or createElement.

Return: true if the element has been added to the group.
Access: public

Parameters:

string	`$element`	—	The element.
string	`$group`	—	The name of the group.

[ Top ]

boolean addElementToGroup(
string
$name, string
$group)

Adds an element to a group.

A group is just a way to logically and visually group form elements. Elements can be added to or removed from a group without removing them from the form all together. However, obviously if the element is removed from the form, it will be removed from the group. If you readd the same element object, it will NOT be readded to the group.

Elements may only be part of one group. If the element is already part of another group, it will not be added to this group.

Return: true if the element has been added to the group.
Access: public

Parameters:

string	`$name`	—	The name of the element.
string	`$group`	—	The name of the group.

[ Top ]

boolean addRule(
string
$name, string
$rule)

Associates a rule with a form element.

When a form is submitted, the values will be checked against any rules that have been associated with the elements. A rule of a give type can only be added to an individual element once. Attempting to add a rule to the same element twice will have no extra effect.

This method passes any extra arguments on to the rule constructor. This allows one method to be used for creating many types of rules. The exact number and type of arguments that is passed to this method varies depending on the type of rule to be created. If the wrong number or type of arguments is passed, the rule constructor should throw an exception.

Return: true if the rule was applied.
Access: public

Parameters:

string	`$name`	—	The name of the element.
string	`$rule`	—	The name of the rule.

[ Top ]

boolean addRuleToObject(
object
$element, string
$rule)

Associates a rule with a form element object.

When a form is submitted, the values will be checked against any rules that have been associated with the elements. A rule of a give type can only be added to an individual element once. Attempting to add a rule to the same element twice will have no extra effect.

This method passes any extra arguments on to the rule constructor. This allows one method to be used for creating many types of rules. The exact number and type of arguments that is passed to this method varies depending on the type of rule to be created. If the wrong number or type of arguments is passed, the rule constructor should throw an exception.

Return: true if the rule was applied.
Access: public

Parameters:

object	`$element`	—	The form element object
string	`$rule`	—	The form rule name.

[ Top ]

array clearValues(
)

Clears the values of all form elements (if possible).

Return: An array of elements whose value has been cleared.
Access: public

[ Top ]

object A createElement(
string
$type, string
$name)

Creates an element but does not add it to the form.

Only elements types that are registered with Structures_Form may be added to the form. This helps to ensure that the elements implement the proper interface.

To avoid overhead, type registration is not checked until the type is added to the form.

This method passes any extra arguments on to the element constructor. This allows one method to be used for creating many types of elements. The exact number and type of arguments that is passed to this method varies depending on the type of element to be created. If the wrong number or type of arguments is passed, the element constructor should throw an exception.

Return: Structures_Form element
Throws: Structures_Form_Exception
Access: public

Parameters:

string	`$type`	—	The element type.
string	`$name`	—	The element name.

[ Top ]

boolean createRule(
string
$rule)

Creates a rule object.

When a form is submitted, the values will be checked against any rules that have been associated with the elements. A rule of a give type can only be added to an individual element once. Attempting to add a rule to the same element twice will have no extra effect.

This method passes any extra arguments on to the rule constructor. This allows one method to be used for creating many types of rules. The exact number and type of arguments that is passed to this method varies depending on the type of rule to be created. If the wrong number or type of arguments is passed, the rule constructor should throw an exception.

Return: true if the rule was applied.
Access: public

Parameters:

string $rule — The name of the rule.

[ Top ]

void defaultErrorCallback(
array
$errors)

Simply passes the error array on to the renderer.

It might be a good idea to re-render the form after errors are added but that is the responsibility of the developer and the renderer. It cannot be determined here if the user wants to re-render. Nor can the form reliably be changed form here.

If errors need to be handled in a different way, you should set a custom error callback either when the form is constructed or by using setErrorCallback().

Access: public

Parameters:

array $errors — An array of error messages.

[ Top ]

array disbandGroup(
string
$group)

Disbands a group.

This method disbands a group. It does not destroy the elements in the group or even remove them from the form. It simply disbands the group and makes the elements free floating individuals. The elements are inserted where the group used to be.

This method returns an array containing the names of any elements that were in the group before it was disbanded.

If the group does not exist, this method will return an empty array.

Access: public

Parameters:

string $group — The name of the group to disband.

[ Top ]

boolean elementExists(
string
$name)

Returns whether or not the given element is associated with this form.

Return: true if the element is part of this form.
Access: public

Parameters:

string $name — The name of the element to check.

[ Top ]

boolean elementObjectExists(
object
$element)

Returns whether or not the element object is associated with this form.

Return: true if the element is part of the form.
Access: public

Parameters:

object $element — The element object.

[ Top ]

array getAllElements(
)

Returns an array of all elements.

Return: An array of elements array(<name> => <element>)
Access: public

[ Top ]

object. getDefaultRenderer(
)

Creates a default renderer object.

This method may be called by group elements that need to renderer elements but do not have a renderer set.

Access: public

[ Top ]

array getDefaults(
)

Returns the array of default values.

Access: public

[ Top ]

mixed getElement(
string
$name)

Returns the form element with the given name.

Return: Either the object or false if the object was not found.
Access: public

Parameters:

string $name — The element name.

[ Top ]

array getElementsByType(
string
$type)

Returns all of the elements in the form of the given type.

Access: public

Parameters:

string $type — The element type name.

[ Top ]

mixed getErrorCallback(
)

Returns the error callback.

Return: A string or array.
Access: public

[ Top ]

string getErrorMessage(
integer
$errorCode)

Returns an error message for the given error code.

Return: An error message.
Access: public

Parameters:

integer $errorCode — The error code to get a message for.

[ Top ]

array getGroup(
string
$group)

Returns the group element.

If the group does not exists, this method returns false.

Access: public

Parameters:

string $group — The name of the group.

[ Top ]

array getGroupElements(
string
$name)

Returns an array containing the names of the elements in the given group.

If the group does not exist, this method returns an empty array.

Access: public

Parameters:

string $name — The name of the group

[ Top ]

array getGroups(
)

Returns an array containing all groups.

Access: public

[ Top ]

integer getPosition(
string
$name)

Returns the current position of the element.

Return: The current position.
Access: public

Parameters:

string $name — The element name.

[ Top ]

object The getRenderedForm(
)

Returns the most recently rendered widget.

This method will not render the form! It only returns the widget created when render() was called!

Return: rendered form.
Access: public

[ Top ]

string getRequiredNote(
)

Returns the current required note.

Access: public

[ Top ]

string getRequiredSymbol(
)

Returns the current required symbol.

Access: public

[ Top ]

mixed getSubmitCallback(
)

Returns the submit callback.

Return: A string or array.
Access: public

[ Top ]

mixed getValue(
string
$name)

Returns the current value for the given element.

Return: The value of the element or group of elements.
Throws: Structures_Form_Exception
Access: public

Parameters:

string $name — The element name.

[ Top ]

array getValues(
)

Returns the current value for all elements in an associative array.

The array will be of the form: array(<name> => <value>);

Access: public

[ Top ]

boolean groupExists(

$group, string
$name)

Returns whether or not the given group exists in this form.

Return: true if the group exists.
Access: public

Parameters:

string	`$name`	—	The name of the group.
	`$group`	—

[ Top ]

object The insertElement(
object
$element, [
$position = -1])

Inserts an element object at the given location.

Only elements types that are registered with Structures_Form may be added to the form. This helps to ensure that the elements implement the proper interface.

To avoid overhead, type registration is not checked until the type is added to the form.

Return: inserted object.
Access: public

Parameters:

object	`$element`	—	The element object.
	`$position`	—

[ Top ]

boolean isElementRegistered(
string
$type, [string
$class = null])

Returns whether or not an element type is registered.

Return: true if the element type is registered.
Access: public

Parameters:

string	`$type`	—	The name of the element type.
string	`$class`	—	Optional class name to check.

[ Top ]

boolean isGroup(
object
$element)

Returns whether or not the element is a group.

Return: true if the element is an group.
Access: public

Parameters:

object $element — The element to check.

[ Top ]

boolean isIncludable(
string
$path)

Returns whether or not a path is in the include path.

Return: true if the path is in the include path.
Access: public

Parameters:

string $path —

[ Top ]

boolean isRequired(
string
$element)

Returns whether or not an element is required.

Return: true if the required rule is applied to the element.
Access: public

Parameters:

string $element — The name of the element.

[ Top ]

boolean isRuleApplied(
string
$name)

Returns whether or not the give rule is currently associated with any form elements.

Return: true if the rule is currently associated with an element
Access: public

Parameters:

string $name — The name of the form rule to check.

[ Top ]

boolean isRuleAppliedToElement(
string
$element, string
$rule)

Returns whether or not the given rule is applied to the given element.

This method returns true if the rule is applied to the element and false in all other cases including if the rule or element is not defined.

Return: true if the rule is applied to the element.
Access: public

Parameters:

string	`$element`	—	The name of the element.
string	`$rule`	—	The name of the rule.

[ Top ]

boolean isRuleRegistered(
string
$rule, [string
$class = null])

Returns whether or not a rule is registered.

Return: true if the rule is registered.
Access: public

Parameters:

string	`$rule`	—	The name of the rule type.
string	`$class`	—	Optional class name to check.

[ Top ]

object The moveElement(
object
$element, integer
$position)

Moves an element object from its current position to the given position.

If the position is greater than the number of elements, the element will be added to the end of the form.

Return: object that was moved.
Access: public

Parameters:

object	`$element`	—	The element to move.
integer	`$position`	—	The new position.

[ Top ]

void registerDefaultRules(
)

Registers the default rule types.

Rule objects are used to validate the values of the form elements before they are submitted to the callback. If an elements value violates a rule a rule callback will be called which allows the user to handle errors in their own way. All violations are collected on each submit and then passed off to the rule callback.

Only registered rules may be applied to a form element.

All registered rules must implement the Structures_Form_RuleInterface.

To avoid overhead, a rule is not checked until it is applied to a form element.

Access: protected

[ Top ]

boolean registerElement(
string
$name, string
$class, string
$path)

Registers an element type with this form.

Before an element type can be used in a form, it must be registered. Registering an element type helps to make sure that type names are unique and that element classes implement the needed interface.

To avoid overhead, registered classes are not checked until the type is instantiated.

Return: true if the class was registered
Throws: Structures_Form_Exception
Access: public

Parameters:

string	`$name`	—	The name to identify the element type.
string	`$class`	—	The name of the element class.
string	`$path`	—	The path to the class definition.

[ Top ]

boolean registerElementSet(
string
$elementSet)

Registers a set of elements.

Only elements types that are registered with Structures_Form may be added to the form. This helps to ensure that the elements implement the proper interface.

Element sets must also define a default renderer.

To avoid overhead, type registration is not checked until the type is added to the form.

registerElement may throw an exception that will be passed along to the calling code.

Return: true if the element set was registered.
Throws: Structures_Form_Exception
Access: public

Parameters:

string $elementSet — The name of an element set.

[ Top ]

boolean registerRule(
string
$name, string
$class, string
$path)

Registers a rule class with the form.

Rule objects are used to validate the values of the form elements before they are submitted to the callback. If an elements value violates a rule a rule callback will be called which allows the user to handle errors in their own way. All violations are collected on each submit and then passed off to the rule callback.

Only registered rules may be applied to a form element.

All registered rules must implement the Structures_Form_RuleInterface.

To avoid overhead, a rule is not checked until it is applied to a form element.

Return: true if the rule was registered.
Throws: Structures_Form_Exception
Access: public

Parameters:

string	`$name`	—	A name to identify the rule.
string	`$class`	—	The name of the rule class.
string	`$path`	—	The path to the class definition.

[ Top ]

void removeElement(
string
$name)

Removes an element from the form by name.

Access: public

Parameters:

string $name —

[ Top ]

object The removeElementFromGroup(
string
$element, string
$group)

Removes an element from a group.

A group is just a way to logically and visually group form elements. Elements can be added to or removed from a group without removing them from the form all together. However, obviously if the element is removed from the form, it will be removed from the group. If you readd the same element object, it will NOT be readded to the group.

Return: object that was removed or false
Access: public

Parameters:

string	`$element`	—	The name of the element.
string	`$group`	—	The name of the group.

[ Top ]

void removeElementObject(
object
$element)

Removes an element object from the form.

This method is useful if an element has been added with the wrong name. Trying to remove it by the name returned by getName() will not work so you must remove it by the object.

Access: public

Parameters:

object $element —

[ Top ]

object The removeElementObjectFromGroup(
string
$element, string
$group)

Removes an element object from a group.

A group is just a way to logically and visually group form elements. Elements can be added to or removed from a group without removing them from the form all together. However, obviously if the element is removed from the form, it will be removed from the group. If you readd the same element object, it will NOT be readded to the group.

This method returns true if the element has been removed from the group and false in all other cases including when the element is not part of the form or the group does not exist.

Return: object that was removed or false.
Access: public

Parameters:

string	`$element`	—	The element.
string	`$group`	—	The name of the group.

[ Top ]

boolean removeRule(
string
$element, string
$rule)

Removes a rule from an element.

When a form is submitted, the values will be checked against any rules that have been associated with the elements. A rule of a give type can only be added to an individual element once. Attempting to add a rule to the same element twice will have no extra effect. Therefore, it only makes sense to try to remove a rule once.

This method will return true if the rule is not associated with the element. This means that it will also return true even if the rule was never associated with the element in the first place.

Return: true if the rule is no longer associated with the element
Access: public

Parameters:

string	`$element`	—	The name of the element to remove the rule from
string	`$rule`	—	The name of the rule to remove

[ Top ]

boolean removeRuleFromObject(
object
$element, string
$rule)

Removes a rule from a form element object.

When a form is submitted, the values will be checked against any rules that have been associated with the elements. A rule of a give type can only be added to an individual element once. Attempting to add a rule to the same element twice will have no extra effect. Therefore, it only makes sense to try to remove a rule once.

This method will return true if the rule is not associated with the element. This means that it will also return true even if the rule was never associated with the element in the first place.

Return: true if the rule is no longer associated with the element
Access: public

Parameters:

object	`$element`	—	The form element to remove the rule from.
string	`$rule`	—	The rule to remove from the object.

[ Top ]

object A render(
)

Returns a container widget holding the form elements.

Passes the elements, required note and required symbol to the renderer and then calls renderer().

Pulling elements out of a renderer is a pain in the ass. Trying to find the correct widget (or parent widget) can be nearly impossible. Therefore, even if you remove a widget from the form, it will still appear if the widget was removed after the form was rendered.

Return: container widget holding the form.
Throws: Structures_Form_Exception
Access: public

[ Top ]

array restoreDefaults(
)

Restores the elements to their default values.

This method over writes any values currently set!

If no defaults were set, this method will return an empty array.

Return: An array containing names of elements whose value has changed.
Access: public

[ Top ]

boolean ruleExists(
string
$rule)

Returns whether or not a rule with the given name already exists.

Return: true if the name is in use.
Access: public

Parameters:

string $rule — The name fo the rule.

[ Top ]

void setDefaultRenderer(
)

Creates a default renderer and sets it as the current renderer.

An exception may be thrown by setRenderer. It will pass through to the calling function.

Access: protected

[ Top ]

array setDefaults(
array
$defaults)

Sets the values of the elements and make the given values the defautls.

This method over writes any values currently set!

Return: An array containing names of elements whose value has changed.
Access: public

Parameters:

array $defaults — An array of default values.

[ Top ]

void setErrorCallback(
mixed
$callback)

Sets the error callback.

Access: public

Parameters:

mixed $callback — A string or array.

[ Top ]

void setRenderer(
object
$renderer)

Sets a renderer object.

Renderers must implement Structures_Form_RendererInterface. This helps to ensure consistency among the API and avoid any fatal errors. A renderer is used to position and display the form elements within a container widget.

Unlike rules and elements, renderers are created on their own (not through a form method). This is because they do not need to know thing about the form at construction time and the form does not need to know anything about the renderer until the form is to be displayed.

A form may only have one renderer at a time. Setting a second renderer will overwrite the first. If no renderer is set, the default renderer will be used.

Throws: Structures_Form_Exception
Access: public

Parameters:

object $renderer — An object that implements Structures_Form::RENDERER_INTERFACE

[ Top ]

void setRequiredNote(
string
$note)

Sets the require note.

Access: public

Parameters:

string $note — The text to use.

[ Top ]

void setRequiredSymbol(
string
$symbol)

Sets the require symbol.

Access: public

Parameters:

string $symbol — The text to use.

[ Top ]

boolean setValue(
string
$name, mixed
$value)

Sets the value for the given element.

This method returns true if the value appears to have been changed. If false is returned, it may indicated that the element does not exist, that the new value was the same as the old value, or that it was frozen.

Return: true if the element's value was set.
Access: public
Usedby: Structures_Form::setValues()

Parameters:

string	`$name`	—	The name of the element
mixed	`$value`	—	The element value.

[ Top ]

array setValues(
array
$values)

Sets the values for the form elements.

The array passed in should be of the form: array(<name> => <value>)

Return: An array containing names of elements whose value has chagned
Access: public
Uses: Structures_Form::setValue()

Parameters:

array $values — An array of values.

[ Top ]

boolean submit(
)

Collects submitted values and calls the callback or error callback.

Return: false to continue processing callbacks.
Access: public

[ Top ]

boolean swapElementSet(
Structures_Form_ElementSet
$elementSet)

Changes the UI of the form from the current set of elements to the given element set.

This method allows you to quickly and easily change from one element set to another. In most cases it is only necessary to change renderers but some renderers may have additional requirements for the elements that necessitate changing the classes that represent the elements.

Return: true if the element set was changed successfully.
Access: public

Parameters:

object $elementSet — A Structures_Form_Element set.

[ Top ]

boolean unRegisterElement(
string
$type)

Unregisters an element type with a form.

An element type may not be unregistered if the form contains elements of the given type.

You may want to unregister a type to prevent a certain type from being used in the form. For example if your app creates forms on the fly from user supplied data, you can unregister the text type to prevent users from creating a form with free form text entries.

Return: true if the type was unregistered
Throws: Structures_Form_Exception
Access: public

Parameters:

string $type — The element type name.

[ Top ]

boolean unRegisterRule(
string
$name)

Unregisters a rule with the form.

Only registered rules may be applied to a form element.

A rule may not be unregistered if it is currently being applied to one or more form elements.

You may want to unregister a rule to prevent it from being applied to a form. For example, if your app creates forms on the fly, you may want to unregister a rule to prevent the user from applying a rule that their PHP installation cannot support (regular expressions may not be available).

Return: true if the rule was unregistered.
Throws: Structures_Form_Exception
Access: public

Parameters:

string $name — The name of the rule class.

[ Top ]

array validate(
)

Validates the values of the form against the applied rules.

This method returns an array even if there are no errors. If the array is empty, then no errors occurred or no rules were applied.

Return: An array of error messages
Access: public

[ Top ]

Class: Structures_Form

Class Overview

Author(s):

Version:

Copyright:

Variables

Methods

Inherited Variables

Inherited Methods

Class Details

Class Variables

$defaultRenderer =

$defaultRendererPath =

$defaults = array()

$elements = array()

$errorCallback =

$registeredElements = array()

$registeredRules = array()

$renderedForm =

$renderer =

$requiredNote = ' denotes required field'

$requiredSymbol = '*'

$rules = array()

$submitCallback =

$submitObjects =

Method Detail

__construct (Constructor) [line 294]

Parameters:

addElement [line 523]

Parameters:

addElementObject [line 739]

Parameters:

addElementObjectToGroup [line 1210]

Parameters:

addElementToGroup [line 1131]

Parameters:

addRule [line 1705]

Parameters:

addRuleToObject [line 1879]

Parameters:

clearValues [line 1417]

createElement [line 658]

Parameters:

createRule [line 1760]

Parameters:

defaultErrorCallback [line 1529]

Parameters:

disbandGroup [line 1016]

Parameters:

elementExists [line 957]

Parameters:

elementObjectExists [line 971]

Parameters:

getAllElements [line 945]

getDefaultRenderer [line 2094]

getDefaults [line 1472]

getElement [line 923]

Parameters:

getElementsByType [line 903]

Parameters:

getErrorCallback [line 352]

getErrorMessage [line 489]

Parameters:

getGroup [line 1086]

Parameters:

getGroupElements [line 1280]

Parameters:

getGroups [line 1101]

getPosition [line 991]

Parameters:

getRenderedForm [line 2188]

getRequiredNote [line 1978]

getRequiredSymbol [line 2001]

getSubmitCallback [line 341]

getValue [line 1330]

Parameters:

getValues [line 1304]

groupExists [line 1051]

Parameters:

insertElement [line 555]