public final class FormField
extends java.lang.Object
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:
The methods available for this purpose are:
List getValues()
void clearValues()
void setValues(Collection)
boolean setValue(String)
boolean addValue(String)
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.
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.
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 static
Config.CurrentCompatibilityMode
.
FormFieldNameCaseInsensitive
property.
FormFields
,
FormControl
,
FormControlType
Modifier and Type | Method and Description |
---|---|
boolean |
addValue(java.lang.String value)
Adds the specified value to the field submission values of this field.
|
boolean |
allowsMultipleValues()
Indicates whether the field allows multiple values.
|
void |
clearValues()
Clears the submission values of all the constituent form controls in this field.
|
java.lang.String |
getDebugInfo()
Returns a string representation of this object useful for debugging purposes.
|
FormControl |
getFormControl()
Returns the first
FormControl from this field. |
FormControl |
getFormControl(java.lang.String predefinedValue)
Returns the constituent
FormControl with the specified predefined value. |
java.util.Collection<FormControl> |
getFormControls()
Returns a collection of all the constituent form controls in this field.
|
java.lang.String |
getName()
Returns the control name shared by all of this field's constituent controls.
|
java.util.Collection<java.lang.String> |
getPredefinedValues()
Returns a collection of the predefined values of all constituent controls in this field.
|
int |
getUserValueCount()
Returns the number of constituent user value controls in this field.
|
java.util.List<java.lang.String> |
getValues()
Returns a list of the field submission values in order of appearance.
|
boolean |
setValue(java.lang.String value)
Sets the field submission values of this field to the single specified value.
|
void |
setValues(java.util.Collection<java.lang.String> values)
Sets the field submission values of this field to the specified values.
|
java.lang.String |
toString()
Returns a string representation of this object useful for debugging purposes.
|
public java.lang.String getName()
If the static Config.CurrentCompatibilityMode
.
isFormFieldNameCaseInsensitive()
property is set to 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.
FormControl.getName()
public java.util.Collection<FormControl> getFormControls()
An iterator over this collection returns the controls in the order of appearance in the source.
getFormControl()
,
getFormControl(String predefinedValue)
public FormControl getFormControl(java.lang.String predefinedValue)
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.FormControl
with the specified predefined value, or null
if none exists.getFormControl()
,
getFormControls()
public FormControl getFormControl()
FormControl
from this field.FormControl
from this field, guaranteed not null
.getFormControl(String predefinedValue)
,
getFormControls()
public boolean allowsMultipleValues()
Returns false
in any one of the following circumstances:
true
.true
if the field allows multiple values, otherwise false
.public int getUserValueCount()
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.
public java.util.Collection<java.lang.String> getPredefinedValues()
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.
null
if none.FormControl.getPredefinedValues()
public java.util.List<java.lang.String> getValues()
The term field submission values is used in this library to refer to the aggregate of all the submission values of a field's constituent form controls.
All objects in the returned list are of type String
, with no null
entries.
The list may contain duplicates if the this field has multiple controls with the same value.
null
.public void clearValues()
FormControl.clearValues()
public void setValues(java.util.Collection<java.lang.String> values)
This is equivalent to calling clearValues()
followed by addValue(value)
for each
value in the specified collection.
The specified collection must not contain any null
values.
values
- the new field submission values of this field.addValue(String value)
public boolean setValue(java.lang.String 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(String value)
method for more information.
value
- the new field submission value of this field, or null
to clear the field of all submission values.true
if one of the constituent form controls accepts the value, otherwise false
.FormFields.setValue(String fieldName, String value)
public boolean addValue(java.lang.String value)
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.
value
- the new field submission value to add to this field, must not be null
.true
if one of the constituent form controls accepts the value, otherwise false
.public java.lang.String getDebugInfo()
public java.lang.String toString()
This is equivalent to getDebugInfo()
.
toString
in class java.lang.Object