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 group of all
form controls
having the same
name.
The
getFormControls()
method can be used to obtain the collection of this field's constituent
FormControl
objects.
The
FormFields
class, which represents a collection of
FormField
objects, provides the highest level
interface for dealing with form fields and controls. For the most common tasks it can be used directly without
the need to work with its constituent
FormField
or
FormControl
objects.
The
FormField
class serves two main purposes:
-
Provide methods for the modification and retrieval of form control submission values
while ensuring that the states of all the field's constituent form controls remain consistent with each other.
The methods available for this purpose are:
Collection getValues()
void clearValues()
void setValues(Collection)
boolean setValue(CharSequence)
boolean addValue(CharSequence)
Although the FormControl
class provides methods for directly modifying the submission values
of individual form controls, it is generally recommended to use the interface provided by the FormFields
class
unless there is a specific requirement for the lower level functionality.
The FormFields
class contains convenience methods providing most of the functionality of the above methods,
as well as some higher level functionality such as the ability to set the form
submission values as a complete field data set
using the FormFields.setDataSet(Map)
method.
-
Provide a means of determining the data structure of the field, allowing a server receiving a
submitted
form data set
to interpret and store the data in an appropriate way.
The properties available for this purpose are:
boolean allowsMultipleValues()
int getUserValueCount()
Collection getPredefinedValues()
The FormFields.getColumnLabels()
and FormFields.getColumnValues(Map)
methods utilise these properties
to convert data from a form data set
(represented as a field data set) into a simple array format,
suitable for storage in a tabular format such as a database table or .CSV
file.
The properties need only be utilised directly in the event that a
form data set is to be converted
from its normal format into some other type of data structure.
A form field which allows user values normally consists of a single
user value control,
such as a
TEXT
control.
When a form field consists of more than one control, these controls are normally all
predefined value controls of the same
type, such as
CHECKBOX
controls.
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 returns at most one value.
The HTML author can disregard convention and mix all types of controls with the same name in the same form,
or include multiple
user value controls of the same name.
The evidence that such an unusual combination is present is when
getUserValueCount()
>1
.
FormField
instances are created automatically with the creation of a
FormFields
collection.
The case sensitivity of form field names is determined by the
Config.CurrentCompatibilityMode
.
FormFieldNameCaseInsensitive
property.
addValue
public boolean addValue(CharSequence value)
Adds the specified value to the
field submission values of this field.
This is achieved internally by attempting to
add the value to every constituent
form control until one "accepts" it.
The return value indicates whether any of the constituent form controls accepted the value.
A return value of
false
implies an error condition as the specified value is not compatible with this field.
In the unusual case that this field consists of multiple form controls, but not all of them are
predefined value controls, priority is given to the predefined value controls
before attempting to add the value to the
user value controls.
true
if one of the constituent form controls accepts the value, otherwise false
.
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
.
true
if the field allows multiple values, otherwise false
.
clearValues
public void clearValues()
getDebugInfo
public String getDebugInfo()
Returns a string representation of this object useful for debugging purposes.
- a string representation of this object useful for debugging purposes.
getFormControl
public FormControl getFormControl(String predefinedValue)
Returns the constituent
FormControl
with the specified
predefined value.
Specifying a predefined value of
null
returns the first control without a predefined value.
predefinedValue
- the predefined value of the control to be returned, or null
to return the first control without a predefined value.
getFormControls
public Collection getFormControls()
Returns a collection of all the constituent
form controls in this field.
An iterator over this collection returns the controls in the order of appearance in the source.
getName
public String getName()
Returns the
control name shared by all of this field's constituent
controls.
If
Config.CurrentCompatibilityMode
.
isFormFieldNameCaseInsensitive()
is
true
, the grouping of the controls by name is case insensitive
and this method always returns the name in lower case.
Since a form field is simply a group of controls with the same name, the terms
control name and
field name are for the most part synonymous, with only a possible difference in case differentiating them.
getPredefinedValues
public Collection getPredefinedValues()
Returns a collection of the
predefined values of all constituent
controls in this field.
All objects in the returned collection are of type
String
, with no
null
entries.
An interator over this collection returns the values in the order of appearance in the source document.
getUserValueCount
public int getUserValueCount()
Returns the number of constituent
user value controls in this field.
This should in most cases be either
0
or
1
.
A value of
0
indicates the field values consist only of
predefined values, which is the case when the field consists only of
predefined value controls.
A value of
1
indicates the field values consist of at most one value set by the user.
It is still possible in this case to receive multiple values in the unlikely event that the HTML author mixed
controls of different types with the same name, but any other values would consist only of
predefined values.
A value greater than
1
indicates that the HTML author has included more than one
user value control with the same name.
This would nearly always indicate an unintentional error in the HTML source document,
in which case 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.
getValues
public Collection getValues()
setValue
public boolean setValue(CharSequence value)
Sets the
field submission values of this field to the single specified value.
This is equivalent to calling
clearValues()
followed by
addValue(value)
.
The return value indicates whether any of the constituent form controls "accepted" the value.
A return value of
false
implies an error condition as the specified value is not compatible with this field.
Specifying a
null
value is equivalent to calling
clearValues()
alone, and always returns
true
.
See the
addValue(CharSequence value)
method for more information.
true
if one of the constituent form controls accepts the value, otherwise false
.
FormFields.setValue(String fieldName, CharSequence value)
setValues
public void setValues(Collection values)
addValue(CharSequence value)
toString
public String toString()
Returns a string representation of this object useful for debugging purposes.
This is equivalent to
getDebugInfo()
.
- a string representation of this object useful for debugging purposes.