spunQ_IField Interface Reference

A field in a form. More...

Inheritance diagram for spunQ_IField:

List of all members.

Public Member Functions
	getContainer ()
	Provides the container this field is in.
	setContainer (spunQ_IFieldContainer $container)
	Sets the container this field is in.
	getName ()
	Provides the name of this field.
	getTypePath ()
	A unique string identifying this field within the form.
	getTypePathPart ()
	The last part of the type path of this field.
	addConverter (spunQ_IFieldValueConverter $converter)
	Adds another converter to this field.
	addValidator (spunQ_IFieldValidator $validator)
	Adds a field validator to this field.
	getConverters ()
	Returns all converters registered via addConverter().
	getValidators ()
	Returns all validators registered via addValidator().
	getHtmlId ($postfix= '')
	A unique string that is valid for the html id attribute.
	getHtmlName ()
	Provides the value of the html name attribute this field needs.
	getUseSubmittedValue ()
	Whether the user-submitted value should replace the default value.
	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.
	getSubmittedRawValue ()
	Provides the raw value that was submitted with the request.
	getSubmittedValue ()
	Provides the value that was submitted with the request.
	getValue ()
	Alias for getSubmittedValue().
	getDisplayValue ($originalValue)
	Returns the value to use for show().
	getValidationMessages ()
	Provides validation messages of this field.
	getFieldByPath ($path)
	Returns a field by its field path.
	_processSubmission (&$value)
	Initializes this field's submitted values.

---

Detailed Description

A field in a form.

Responsible for providing enough info to be rendered by a template and providing the values entered by the user. Is expected to use spunQ_IFieldValueConverters for converting fields between values suitable for templates and actual values to be further processed by the application.

Definition at line 10 of file IField.interface.php.

---

Member Function Documentation

spunQ_IField::_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.

Implemented in spunQ_MultipleChoiceField, spunQ_SingleChoiceField, and spunQ_FieldIterator.

spunQ_IField::addConverter

(

spunQ_IFieldValueConverter $

converter

)

Adds another converter to this field.

All converters will be used in the order in which they have been registered when converting from spunQ to raw values and in reverse order when converting back.

Parameters:

A

new converter that will be used to convert application values to raw values (values as provided by php) and vice versa.

Returns:

spunQ_IField $this

spunQ_IField::addValidator

(

spunQ_IFieldValidator $

validator

)

Adds a field validator to this field.

The field validator will be used to verify the validity of a submitted value by performing additional checks, such as range checks.

Parameters:

$validator

The validator to use for submitted values.

Returns:

spunQ_IField $this

spunQ_IField::getContainer

(

)

Provides the container this field is in.

Returns:

spunQ_IFieldContainer

spunQ_IField::getConverters

(

)

Returns all converters registered via addConverter().

Returns:

array<spunQ_IFieldValueConverter>

spunQ_IField::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

Implemented in spunQ_FieldGroup, and spunQ_FieldIterator.

spunQ_IField::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.

Implemented in spunQ_FieldGroup, and spunQ_FieldIterator.

spunQ_IField::getHtmlId

(

$

postfix = ''

)

A unique string that is valid for the html id attribute.

Note that the generated id is only guaranteed to be unique within the form. 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 field needs to be shown in a new form.

Returns:

string

spunQ_IField::getHtmlName

(

)

Provides the value of the html name attribute this field needs.

Returns:

string

Implemented in spunQ_MultipleChoiceField.

spunQ_IField::getName

(

)

Provides the name of this field.

Does not serve any real purpose except helping developers retain their sanity when working with forms.

Returns:

string

spunQ_IField::getSubmittedRawValue

(

)

Provides the raw value that was submitted with the request.

See also:

spunQ_IFieldValueConverter for the definition of 'raw value'.

Returns:

any Either a string or an array<string>.

Exceptions:

spunQ_HtmlException

If the form was not submitted.

spunQ_IField::getSubmittedValue

(

)

Provides the value that was submitted with the request.

The value provided here has been processed by all converters registered with addConverter() and verified by all validators registered via addValidator().

Returns:

any May return an arbitrary value if not submittedValueValid().

Exceptions:

spunQ_HtmlException

If the form was not submitted.

spunQ_IField::getTypePath

(

)

A unique string identifying this field within the form.

The string is hierarchical, where fields containing other fields are present in the sub-fields, separated by periods (i.e. formTypeString.container.fieldTypePathPart).

See also:

spunQ_IField::getTypePathPart()

spunQ_IFieldContainer::getTypeString()

Returns:

string

spunQ_IField::getTypePathPart

(

)

The last part of the type path of this field.

Returns:

string

Implemented in spunQ_FieldIterator.

spunQ_IField::getUseSubmittedValue

(

)

Whether the user-submitted value should replace the default value.

If this returns true, the show function will ignore its $value parameter and use getSubmittedValue() if it was valid. This function will only take effect when the user has submitted the form.

Returns:

boolean

spunQ_IField::getValidationMessages

(

)

Provides validation messages of this field.

Messages are either created by converters or validators.

Returns:

array<string> Will return an empty array if the form was not submitted.

spunQ_IField::getValidators

(

)

Returns all validators registered via addValidator().

Returns:

array<spunQ_IFieldValidator>

spunQ_IField::getValue

(

)

Alias for getSubmittedValue().

Returns:

any

spunQ_IField::setContainer

(

spunQ_IFieldContainer $

container

)

Sets the container this field is in.

Returns:

spunQ_IField $this

spunQ_IField::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

Implemented in spunQ_FieldGroup, and spunQ_FieldIterator.

spunQ_IField::showValidatorsJs

(

)

Prints javascript for validating this field.

Returns:

spunQ_IField $this

Implemented in spunQ_FieldGroup, and spunQ_FieldIterator.

spunQ_IField::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.

Implemented in spunQ_FieldGroup, and spunQ_FieldIterator.

---

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

• IField.interface.php