spunQ_FieldIterator Class Reference

A field allowing a recurring occurance of another field. More...

Inheritance diagram for spunQ_FieldIterator:

List of all members.

Public Member Functions
	__construct (spunQ_IField $field)
	Constructor.
	getField ($index=NULL)
	Returns the field for given index.
	__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.
	getTypeString ()
	Returns a type string for the container.
	getFieldHtmlId ($field, $postfix)
	Provides the html id of a field.
	getFieldHtmlName ($field)
	Provides the html name of the field.
	getTypePathPart ()
	The last part of the type path of this field.
	show ($value=NULL, $template=NULL, $templateParameters=array(), $htmlIdPostFix= '')
	Will generate and display html for this form field.
	showValidatorsJs ()
	Prints javascript for validating this field.
	submittedValueValid ()
	Returns whether the value submitted by the browser is valid This will only check whether the values received are acceptable to this field type.
	getFieldByPath ($path)
	Returns a field by its field path.
	setUseSubmittedValue ($useSubmittedValue=true)
	_processSubmission (&$rawValue)
	Initializes this field's submitted values.
	getDisplayValue ($originalValue)
	Returns the value to use for show().
	getForm ()
	Provides the form this field resides in.
	getContainer ()
	setContainer (spunQ_IFieldContainer $container)
	getName ()
	getTypePath ()
	addConverter (spunQ_IFieldValueConverter $converter)
	addValidator (spunQ_IFieldValidator $validator)
	getConverters ()
	getValidators ()
	getHtmlId ($postfix= '')
	getHtmlName ()
	getUseSubmittedValue ()
	getSubmittedRawValue ()
	getSubmittedValue ()
	getValue ()
	getValidationMessages ()
Static Public Member Functions
static	normalizeTemplateCssParameter ($class)
	Normalizes the $class parameter passed to a field template.
Protected Member Functions
	rawToSpunQ (&$value)
	spunQToRaw ($value)
	Will convert a spunQ value to a raw value using registered converters.
	getDefaultTemplate ()
	Provides a template to be used if the parameter was not passed to show().
Protected Attributes
	$field
	The field to iterate on.
	$fieldClones = array()
	Clones of the field that will be returned by getField().
	$name
	Name of this field.
	$container
	The container this field is residing in.
	$useSubmittedValue = true
	Whether the submitted value should override the default value.
	$converters = array()
	The converters that have been registered with this field.
	$validators = array()
	Registered field validators.
	$validationMessages = NULL
	Messages generated by validators and converters.
	$submittedValue = NULL
	Value that was submitted for this field.
	$submittedRawValue = NULL
	Raw value that was submitted for this field.

---

Detailed Description

A field allowing a recurring occurance of another field.

Essentially this makes an array out of another field.

Definition at line 7 of file FieldIterator.class.php.

---

Constructor & Destructor Documentation

spunQ_FieldIterator::__construct

(

spunQ_IField $

field

)

Constructor.

Will remove the given field from its container and add it to this. Will add itself to the former container of the field, effectively putting itself in between.

Parameters:

$field

The field to iterate on.

Definition at line 29 of file FieldIterator.class.php.

---

Member Function Documentation

spunQ_FieldIterator::__clone

(

)

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

Will clone its field and reset its container.

Returns:

void

Definition at line 64 of file FieldIterator.class.php.

spunQ_FieldIterator::_processSubmission

(

&$

value

)

Initializes this field's submitted values.

Intended to be called by this field's container.

Parameters:

$value

The raw value that was submitted for this field. The field is expected to return the processed value via this in/out parameter.

Returns:

boolean Whether the submitted value was valid.

Implements spunQ_IField.

Definition at line 198 of file FieldIterator.class.php.

spunQ_FieldIterator::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 83 of file FieldIterator.class.php.

spunQ_Field::getDefaultTemplate

(

)

[protected, inherited]

Provides a template to be used if the parameter was not passed to show().

The show() implementation in spunQ_IField uses this value.

Returns:

string

Definition at line 391 of file Field.class.php.

spunQ_FieldIterator::getDisplayValue

(

$

originalValue

)

Returns the value to use for show().

This is either the value given as parameter or the submitted value, depending on form submission and the value of getUseSubmittedValue().

Parameters:

$originalValue

The original value to be displayed if the form was not submitted.

Returns:

any

Implements spunQ_IField.

Definition at line 209 of file FieldIterator.class.php.

spunQ_FieldIterator::getField

(

$

index = NULL

)

Returns the field for given index.

Will generate a new field by cloning the original field and return the cached result. Will return the original field if the parameter is omitted.

Parameters:

$index

The index to get the field for. Will return the original field if this parameter is omitted.

Returns:

spunQ_IField

Definition at line 47 of file FieldIterator.class.php.

spunQ_FieldIterator::getFieldByPath

(

$

path

)

Returns a field by its field path.

Parameters:

$path

Either a string or an array. The string should contain only the difference between this fields path and the searched field's path.

Returns:

spunQ_IField

Exceptions:

spunQ_HtmlException

If the field is not found.

Implements spunQ_IField.

Definition at line 169 of file FieldIterator.class.php.

spunQ_FieldIterator::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 107 of file FieldIterator.class.php.

spunQ_FieldIterator::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 115 of file FieldIterator.class.php.

spunQ_Field::getForm

(

)

[inherited]

Provides the form this field resides in.

Returns:

spunQ_Form

Definition at line 120 of file Field.class.php.

spunQ_FieldIterator::getTypePathPart

(

)

The last part of the type path of this field.

Returns:

string

Implements spunQ_IField.

Definition at line 124 of file FieldIterator.class.php.

spunQ_FieldIterator::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 100 of file FieldIterator.class.php.

static spunQ_Field::normalizeTemplateCssParameter

(

$

class

)

[static, inherited]

Normalizes the $class parameter passed to a field template.

Many field templates have an optional parameter called $class that can be passed either of the following:

• a string containing css classes
• an array containing strings as css classes
• NULL indicating, that no class declaration is to be added.

Parameters:

$class

The value that was passed to the template. Either of the types mentioned in the function description.

Returns:

A css string that can be safely inserted into the class attribute of an html node.

Exceptions:

spunQ_HtmlException

If the parameter has an unexpected type or an invalid css declaration.

Definition at line 20 of file Field.class.php.

spunQ_FieldIterator::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 93 of file FieldIterator.class.php.

spunQ_FieldIterator::show	(	$	value = NULL,
		$	template = NULL,
		$	templateParameters = array(),
		$	htmlIdPostfix = ''
	)

Will generate and display html for this form field.

Parameters:

	$value	The default value this field shall display. This is expected to be the actual value required in the application. It will be run through all converters before it is passed to the template. This value might be replaced by the value the user submitted if getUseSubmittedValue() yields true.
	$template	The template to use for converting this field into html. The template will receive the following parameters: field: this field value: the value passed to this function, processed by all available parameters. htmlIdPostfix: postfix to html ids, the last parameter to this function. any other parameters provided to the according parameter to this function.
	$templateParameters	Additional parameters to be passed to the template.
	$htmlIdPostfix	A postfix to be added to id attributes of the html form elements that are generated. A unique parameter must be provided each time the form is displayed.

Returns:

spunQ_IField $this

Implements spunQ_IField.

Definition at line 131 of file FieldIterator.class.php.

spunQ_FieldIterator::showValidatorsJs

(

)

Prints javascript for validating this field.

Returns:

spunQ_IField $this

Implements spunQ_IField.

Definition at line 146 of file FieldIterator.class.php.

spunQ_Field::spunQToRaw

(

$

value

)

[protected, inherited]

Will convert a spunQ value to a raw value using registered converters.

See also:

spunQ_IFieldValueConverter

Parameters:

$value

The value to convert

Returns:

any The converted value.

Definition at line 353 of file Field.class.php.

spunQ_FieldIterator::submittedValueValid

(

)

Returns whether the value submitted by the browser is valid This will only check whether the values received are acceptable to this field type.

It will not check the results of validators.

Returns:

boolean

Exceptions:

spunQ_HtmlException

If the form was not submitted.

Implements spunQ_IField.

Definition at line 154 of file FieldIterator.class.php.

spunQ_FieldIterator::wasSubmitted

(

)

Whether the form the field is in was submitted.

Returns:

boolean

Implements spunQ_IFieldContainer.

Definition at line 76 of file FieldIterator.class.php.

---

Member Data Documentation

spunQ_Field::$container [protected, inherited]

The container this field is residing in.

Type:

spunQ_IFieldContainer

Definition at line 48 of file Field.class.php.

spunQ_Field::$converters = array() [protected, inherited]

The converters that have been registered with this field.

Type:

array<spunQ_IFieldValueConverter>

Definition at line 63 of file Field.class.php.

spunQ_FieldIterator::$field [protected]

The field to iterate on.

Type:

spunQ_IField

Definition at line 13 of file FieldIterator.class.php.

spunQ_FieldIterator::$fieldClones = array() [protected]

Clones of the field that will be returned by getField().

The first entry is always $field itself.

Type:

array<spunQ_IField>

Definition at line 20 of file FieldIterator.class.php.

spunQ_Field::$name [protected, inherited]

Name of this field.

Type:

string

Definition at line 42 of file Field.class.php.

spunQ_Field::$submittedRawValue = NULL [protected, inherited]

Raw value that was submitted for this field.

Type:

any

Definition at line 89 of file Field.class.php.

spunQ_Field::$submittedValue = NULL [protected, inherited]

Value that was submitted for this field.

Initialized in _processSubmission().

Type:

any

Definition at line 83 of file Field.class.php.

spunQ_Field::$useSubmittedValue = true [protected, inherited]

Whether the submitted value should override the default value.

In other words: If this is set to true, the field will display the value that was submitted previously instead of the default value.

See also:

spunQ_IField::getUseSubmittedValue()

Type:

boolean

Definition at line 57 of file Field.class.php.

spunQ_Field::$validationMessages = NULL [protected, inherited]

Messages generated by validators and converters.

Initialized in _processSubmission().

Type:

array<string>

Definition at line 76 of file Field.class.php.

spunQ_Field::$validators = array() [protected, inherited]

Registered field validators.

Type:

array<spunQ_IFieldValidator>

Definition at line 69 of file Field.class.php.

---

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

• FieldIterator.class.php