au.id.jericho.lib.html
Class FormField

java.lang.Object
  au.id.jericho.lib.html.FormField

public final class FormField

extends java.lang.Object

Represents a field in an HTML form, a field being defined as the combination of all form controls having the same name.

In addition to the getFormControls() method, which returns a Collection of all the FormControl objects that make up this field, the properties of a FormField object describe how the values associated with the the field's name in a submitted form data set should be interpreted. These properties include whether multiple values can be expected, the number of values which would typically be set by the user, and a list of values which are predefined in the HTML. This information allows the server to store and format the data in an appropriate way.

A form field which allows user values will normally consist of a single control whose FormControlType.isPredefinedValue() method returns false, such as a TEXT control.

When a form field consists of more than one control, these controls will normally be all be of the same type which has predefined values, such as the CHECKBOX control.

Form fields consisting of more than one control do not necessarily return multiple values. A form field consisting of CHECKBOX controls can return multiple values, whereas a form field consisting of RADIO controls will return at most one value.

Note that a select element containing multiple option elements is counted as a single control. See the FormControl class for more details.

The HTML author can disregard convention and mix all types of controls with the same name in the same form, or include multiple controls of the same name which do not have predefined values. The evidence that such an unusual combination is present is a user value count greater than one, so your application can either log a warning that a poorly designed form has been encountered, or take special action to try to interpret the multiple user values that might be submitted.

FormField objects are created automatically with the creation of a FormFields object.

The case sensitivity of form field names is determined by the static FormFields.FieldNameCaseSensitive property.

See Also:

FormFields, FormControl

Method Summary

boolean	addValue(java.lang.CharSequence value) **** returns true if value was taken
boolean	allowsMultipleValues() Indicates whether the field allows multiple values.
void	clearValues() ****
java.lang.String	getDebugInfo() Returns a string representation of this object useful for debugging purposes.
java.util.Collection	getFormControls() Returns a collection of all the form controls that make up this field.
java.lang.String	getName() Returns the name of the field.
java.util.Collection	getPredefinedValues() Returns a collection of the predefined values of all controls that make up this field.
int	getUserValueCount() Returns the number of values which would typically be set by the user, and are not included in the list of predefined values.
java.util.Collection	getValues() **** does not contain nulls
boolean	setValue(java.lang.CharSequence value)
void	setValues(java.util.Collection values)
java.lang.String	toString() Returns a string representation of this object useful for debugging purposes.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getName

public java.lang.String getName()

Returns the name of the field.

If FormFields.FieldNameCaseSensitive is true, the name will be returned in lower case.

Returns:

the name of the field.

getUserValueCount

public int getUserValueCount()

Returns the number of values which would typically be set by the user, and are not included in the list of predefined values. This should in most cases be either 0 or 1.

The word "typically" is used because the use of scripts can cause control types which normally have predefined values to be set by the user, which is a condition which is beyond the scope of this library to test for.

A value of 0 indicates the field values will consist only of predefined values. This is the case when the field consists of only CHECKBOX, RADIO, BUTTON, SUBMIT, IMAGE, SELECT_SINGLE and SELECT_MULTIPLE form control types.

A value of 1 indicates the field values will consist of at most one value set by the user. It is still possible to receive multiple values in the unlikely event that the HTML author mixed controls of different types with the same name, but any others should consist only of predefined values.

A value greater than 1 indicates that the HTML author has included multiple controls of the same name which do not have predefined values. This would nearly always indicate an unintentional error in the HTML source document.

Returns:

the number of values which would typically be set by the user.

allowsMultipleValues

public boolean allowsMultipleValues()

Indicates whether the field allows multiple values.

Returns false in any one of the following circumstances:

• The field consists of only one control (unless it is a multiple select with more than one option)
• The field consists entirely of radio buttons
• The field consists entirely of submit buttons

If none of these three conditions are met, the method returns true.

Returns:

true if the field allows multiple values, otherwise false.

getPredefinedValues

public java.util.Collection getPredefinedValues()

Returns a collection of the predefined values of all controls that make up this field.

An interator over this collection will return the values in the order of appearance in the source.

Returns:

a collection of the predefined values of all controls that make up this field, or null if none.

getFormControls

public java.util.Collection getFormControls()

Returns a collection of all the form controls that make up this field.

An iterator over this collection will return the controls in the order of appearance in the source.

Returns:

a collection containing all the form controls that make up this field.

clearValues

public void clearValues()

****

getValues

public java.util.Collection getValues()

**** does not contain nulls

setValues

public void setValues(java.util.Collection values)

setValue

public boolean setValue(java.lang.CharSequence value)

addValue

public boolean addValue(java.lang.CharSequence value)

**** returns true if value was taken

getDebugInfo

public java.lang.String getDebugInfo()

Returns a string representation of this object useful for debugging purposes.

Returns:

a string representation of this object useful for debugging purposes.

toString

public java.lang.String toString()

Returns a string representation of this object useful for debugging purposes.

This is equivalent to getDebugInfo().

Returns:

a string representation of this object useful for debugging purposes.