spunQ_Form Class Reference

The top-most FieldContainer. More...

Inheritance diagram for spunQ_Form:

List of all members.

Public Member Functions
	__construct ($name)
	Constructor.
	getName ()
	Provides this forms name.
	getMethod ()
	Provides the submit method of this form.
	setMethod ($method)
	Sets the submit method of this form.
	getEncType ()
	Provides the encoding type of this form.
	setEncType ($encType)
	Sets the encoding type of this form.
	getHtmlId ($postfix= '')
	Provides a unique string that can be used for the html id attribute.
	getRawValues ()
	Returns all POST or GET variables depending on getMethod().
	getFields ()
	Returns all fields in this container, indexed by their names.
	getField ($name, $throwException=true)
	Returns the field with given name.
	getFieldByPath ($path)
	Returns a field by its path.
	show ($values=array(), $htmlIdPostfix= '')
	Convenience function for php developers (i.e.
	showFormHeader ($target=NULL, $htmlIdPostfix= '')
	Displays the required form header.
	showFormFooter ()
	Displays the required form footer.
	showFormAttributes ($target=NULL, $htmlIdPostfix= '')
	Displays required xml attributes for the form tag.
	showFormIdentifier ()
	Displays this form's identifier.
	wasSubmittedSuccessfully ()
	Checks whether this form was submitted successfully.
	showValidatorsJs ()
	Shows the javascript part of all validators.
	addValidator (spunQ_IFormValidator $validator)
	Adds a form validator.
	getValidationMessages ()
	Provides the messages produced by the form validators.
	__clone ()
	Called after this object was cloned (on the newly created object).
	wasSubmitted ()
	Whether the form the field is in was submitted.
	addField (spunQ_IField $field)
	Adds a field to this container.
	removeField (spunQ_IField $field)
	Removes a field from this container.
	getFieldHtmlId ($field, $postfix)
	Provides the html id of a field.
	getFieldHtmlName ($field)
	Provides the html name of the field.
	getTypeString ()
	Returns a type string for the container.
	setUseSubmittedValuesForAllFields ($useSubmittedValue=true)
	Sets the useSubmittedValue for all fields at once.
Public Attributes
const	ENCTYPE_URLENCODED = 1
	Form encoding type: urlencoded.
const	ENCTYPE_FORMDATA = 2
	Form encoding type: multipart/form-data.
Protected Member Functions
	processSubmission ()
	Ensures that this form and all its fields have processed submitted data.
Protected Attributes
	$name
	Unique name of this form.
	$method = spunQ_IHttpRequest::REQUEST_POST
	The method this form will be submitted with.
	$fields = array()
	Fields in this form.
	$encType = self::ENCTYPE_URLENCODED
	The encoding type this form shall be submitted with.
	$processedSubmission = false
	Whether processSubmission() was executed.
	$validators = array()
	Validators for this form.
	$validationMessages = array()
	Messages produced by the form validators.
	$typeName
	The type of this form.

---

Detailed Description

The top-most FieldContainer.

Responsible for sending form data to the user, receiving form data from the user, validating received values and converting them to usable application values. Several of these tasks are accomplished by other classes, so this class performs the orchestration of said tasks.

Definition at line 82 of file Form.class.php.

---

Constructor & Destructor Documentation

spunQ_Form::__construct

(

$

name

)

Constructor.

Parameters:

$name

Unique name of this form. This really must be unique since the form will decide whether it was submitted by looking up this name in PHPs global array of submitted values.

Definition at line 155 of file Form.class.php.

---

Member Function Documentation

spunQ_Form::__clone

(

)

Called after this object was cloned (on the newly created object).

Will clone all its fields and reset their container.

Returns:

void

Definition at line 413 of file Form.class.php.

spunQ_Form::addField

(

spunQ_IField $

field

)

Adds a field to this container.

$field The field to add to this container.

Returns:

spunQ_IFieldContainer this

Implements spunQ_IFieldContainer.

Definition at line 432 of file Form.class.php.

spunQ_Form::addValidator

(

spunQ_IFormValidator $

validator

)

Adds a form validator.

Parameters:

$validator

The new validator to use when the form is submitted.

Returns:

void

Definition at line 394 of file Form.class.php.

spunQ_Form::getEncType

(

)

Provides the encoding type of this form.

Returns:

integer Either of the ENCTYPE_* constants in this class.

Definition at line 193 of file Form.class.php.

spunQ_Form::getField	(	$	name,
		$	throwException = true
	)

Returns the field with given name.

Returns:

spunQ_IField

Exceptions:

spunQ_HtmlException

If no field with given name was added to this container.

Definition at line 242 of file Form.class.php.

spunQ_Form::getFieldByPath

(

$

path

)

Returns a field by its path.

Parameters:

$path

The return value of the field's getTypePath() function.

Returns:

spunQ_IField

Exceptions:

spunQ_HtmlException

If the field is not found.

Definition at line 258 of file Form.class.php.

spunQ_Form::getFieldHtmlId	(	$	field,
		$	postfix
	)

Provides the html id of a field.

The rationale of this function is the same as for getFieldHtmlName().

See also:

spunQ_IField::getHtmlId()

Parameters:

$field

The field to get the html id for.

Returns:

string

Implements spunQ_IFieldContainer.

Definition at line 449 of file Form.class.php.

spunQ_Form::getFieldHtmlName

(

$

field

)

Provides the html name of the field.

The container is respensible for all contained field's names. A form might just return the fields name, a FieldIterator will postfix the square brackets that PHP expects.

See also:

spunQ_IField::getHtmlName()

Parameters:

$field

The field to get the html name for.

Returns:

string

Implements spunQ_IFieldContainer.

Definition at line 456 of file Form.class.php.

spunQ_Form::getFields

(

)

Returns all fields in this container, indexed by their names.

Returns:

array<spunQ_IField>

Definition at line 232 of file Form.class.php.

spunQ_Form::getHtmlId

(

$

postfix = ''

)

Provides a unique string that can be used for the html id attribute.

If the same form needs to be shown more then once, the $postfix parameter needs to be provided.

Parameters:

$postfix

An additional string that may be used to generate the unique string. A new value must be provided each time this form needs to be shown.

Returns:

string

Definition at line 216 of file Form.class.php.

spunQ_Form::getMethod

(

)

Provides the submit method of this form.

Returns:

integer Either of the spunQ_IHttpRequest::REQUEST_* constants, default is post.

Definition at line 175 of file Form.class.php.

spunQ_Form::getName

(

)

Provides this forms name.

Returns:

string

Definition at line 166 of file Form.class.php.

spunQ_Form::getRawValues

(

)

Returns all POST or GET variables depending on getMethod().

Returns:

array

Definition at line 224 of file Form.class.php.

spunQ_Form::getTypeString

(

)

Returns a type string for the container.

The type string is - unlike the name - not unique. It is used for grouping forms and fields into types that have common functions. One example is error message translation. Although the forms with the names editUser<user:14> and editUser<user:15> are two completely distinct forms, they might have the exact same error messages for their fields.

Returns:

string

Implements spunQ_IFieldContainer.

Definition at line 463 of file Form.class.php.

spunQ_Form::getValidationMessages

(

)

Provides the messages produced by the form validators.

Returns:

array<string>

Definition at line 403 of file Form.class.php.

spunQ_Form::processSubmission

(

)

[protected]

Ensures that this form and all its fields have processed submitted data.

Returns:

spunQ_Form $this

Definition at line 471 of file Form.class.php.

spunQ_Form::removeField

(

spunQ_IField $

field

)

Removes a field from this container.

$field The field to remove.

Returns:

spunQ_IFieldContainer this

Implements spunQ_IFieldContainer.

Definition at line 441 of file Form.class.php.

spunQ_Form::setEncType

(

$

encType

)

Sets the encoding type of this form.

Parameters:

$encType

Either of the ENCTYPE_* constants in this class.

Returns:

spunQ_Form $this

Definition at line 202 of file Form.class.php.

spunQ_Form::setMethod

(

$

method

)

Sets the submit method of this form.

Parameters:

$method

Either of the spunQ_IHttpRequest::REQUEST_* constants.

Returns:

spunQ_Form $this

Definition at line 184 of file Form.class.php.

spunQ_Form::setUseSubmittedValuesForAllFields

(

$

useSubmittedValue = true

)

Sets the useSubmittedValue for all fields at once.

Parameters:

$useSubmittedValue

The new value for useSubmittedValue.

Returns:

spunQ_Field $this

Definition at line 510 of file Form.class.php.

spunQ_Form::show	(	$	values = array(),
		$	htmlIdPostfix = ''
	)

Convenience function for php developers (i.e.

non-designers). Will display this form in a functioning manner, using many many defaults.

Parameters:

	$values	The values to pass to the show functions of this forms fields, indexed by the fields name.
	$postfix	An additional string that may be used to generate the html id string. A new value must be provided each time this form is shown.

Returns:

spunQ_Form $this

Definition at line 286 of file Form.class.php.

spunQ_Form::showFormAttributes	(	$	target = NULL,
		$	htmlIdPostfix = ''
	)

Displays required xml attributes for the form tag.

Shows the id and method tag. enctype will be displayed only if it is set to ENCTYPE_FORMDATA.

Returns:

spunQ_Form $this

Definition at line 332 of file Form.class.php.

spunQ_Form::showFormFooter

(

)

Displays the required form footer.

Returns:

spunQ_Form $this

Definition at line 321 of file Form.class.php.

spunQ_Form::showFormHeader	(	$	target = NULL,
		$	htmlIdPostfix = ''
	)

Displays the required form header.

Returns:

spunQ_Form $this

Definition at line 309 of file Form.class.php.

spunQ_Form::showFormIdentifier

(

)

Displays this form's identifier.

The identifier is merely an invisible form field containing the name of this form. This helps spunQ identify which form was submitted.

Returns:

spunQ_Form $this

Definition at line 354 of file Form.class.php.

spunQ_Form::showValidatorsJs

(

)

Shows the javascript part of all validators.

Returns:

spunQ_Form $this

Definition at line 382 of file Form.class.php.

spunQ_Form::wasSubmitted

(

)

Whether the form the field is in was submitted.

Returns:

boolean

Implements spunQ_IFieldContainer.

Definition at line 424 of file Form.class.php.

spunQ_Form::wasSubmittedSuccessfully

(

)

Checks whether this form was submitted successfully.

The difference to wasSubmitted() is that this function will query each field if the value it received was valid.

Returns:

boolean

Definition at line 365 of file Form.class.php.

---

Member Data Documentation

spunQ_Form::$encType = self::ENCTYPE_URLENCODED [protected]

The encoding type this form shall be submitted with.

Either of the ENCTYPE_* constants in this class.

Type:

integer

Definition at line 121 of file Form.class.php.

spunQ_Form::$fields = array() [protected]

Fields in this form.

Type:

array<spunQ.html.form.Field>

Definition at line 114 of file Form.class.php.

spunQ_Form::$method = spunQ_IHttpRequest::REQUEST_POST [protected]

The method this form will be submitted with.

Either of the spunQ_IHttpRequest::REQUEST_* constants, default is post.

Type:

integer

Definition at line 108 of file Form.class.php.

spunQ_Form::$name [protected]

Unique name of this form.

This really must be unique since the form will decide whether it was submitted by looking up this name in PHPs global array of submitted values.

Type:

string

Definition at line 101 of file Form.class.php.

spunQ_Form::$processedSubmission = false [protected]

Whether processSubmission() was executed.

Type:

boolean

Definition at line 127 of file Form.class.php.

spunQ_Form::$typeName [protected]

The type of this form.

Required for getTypeString().

Type:

string

Definition at line 147 of file Form.class.php.

spunQ_Form::$validationMessages = array() [protected]

Messages produced by the form validators.

Populated during processSubmission().

Type:

array<string>

Definition at line 140 of file Form.class.php.

spunQ_Form::$validators = array() [protected]

Validators for this form.

Type:

array<spunQ_IFormValidator>

Definition at line 133 of file Form.class.php.

---

The documentation for this class was generated from the following file:

• Form.class.php