Class FormFields
- java.lang.Object
-
- java.util.AbstractCollection<FormField>
-
- FormFields
-
public final class FormFields extends java.util.AbstractCollection<FormField>
Represents a collection ofFormField
objects.This class provides the main interface for the analysis and manipulation of form controls. A
FormFields
object is a collection ofFormField
objects, with each form field consisting of a group of form controls having the same name.The functionality provided by this class can be used to accomplish two main tasks:
-
Modify the submission values of the constituent form controls
for subsequent output in an
OutputDocument
.The methods available for this purpose are:
List<String> getValues(String fieldName)
Map<String,String[]> getDataSet()
void clearValues()
void setDataSet(Map<String,String[]>)
boolean setValue(String fieldName, String value)
boolean addValue(String fieldName, String value)
Although the
FormField
andFormControl
classes provide methods for directly modifying the submission values of individual form fields and controls, it is generally recommended to use the interface provided by this (theFormFields
) class unless there is a specific requirement for the lower level functionality.The display characteristics of individual controls, such as whether the control is disabled, replaced with a simple value, or removed altogether, can only be set on the individual
FormControl
objects. See below for information about retrieving a specificFormControl
object from theFormFields
object. -
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 methods available for this purpose are:
String[] getColumnLabels()
String[] getColumnValues(Map)
String[] getColumnValues()
The
Util
class contains a method calledoutputCSVLine(Writer,String[])
which writes theString[]
output of these methods to the specifiedWriter
in.CSV
format.The implementation of these methods makes use of certain properties in the
FormField
class that describe the structure of the data in each field. These properties can 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.
To access a specific
FormControl
from aFormFields
object, use:formFields.
get(fieldName)
.
getFormControl()
if the control is the only one with the specified name, orformFields.
get(fieldName)
.
getFormControl(predefinedValue)
to retrieve the control having the speficied predefined value if it is part of a field containing multiple controls.
The term field data set is used in this library to refer to a data structure consisting of a set of names (in lower case), each mapped to one or more values. Generally, this is represented by a data type of
java.util.Map<String,String[]>
, with the keys (names) being of typeString
and the values represented by an array containing one or more items of typeString
. A field data set can be used to represent the data in an HTML form data set.FormFields
instances are obtained using theFormFields(Collection formControls)
constructor or by calling theSegment.getFormFields()
method.The case sensitivity of form field names is determined by the static
Config.CurrentCompatibilityMode
.
FormFieldNameCaseInsensitive
property.Examples:
-
Write the data received from in the current
ServletRequest
to a.CSV
file, and then display the form populated with this data:Source source=new Source(htmlTextOfOriginatingForm); FormFields formFields=source.getFormFields(); File csvOutputFile=new File("FormData.csv"); boolean outputHeadings=!csvOutputFile.exists(); Writer writer=new FileWriter(csvOutputFile,true); if (outputHeadings) Util.outputCSVLine(writer,formFields.getColumnLabels()); Util.outputCSVLine(writer,formFields.getColumnValues(servletRequest.getParameterMap())); writer.close(); formFields.setDataSet(servletRequest.getParameterMap()); OutputDocument outputDocument=new OutputDocument(source); outputDocument.replace(formFields); outputDocument.writeTo(servletResponse.getWriter());
See also the sample program FormFieldCSVOutput.
- Replace the initial values of controls in the form named "MyForm" with new values:
Source source=new Source(htmlText); Element myForm=null; List formElements=source.getAllElements(Tag.FORM); for (Iterator i=formElements.iterator(); i.hasNext();) { Element formElement=(Element)i.next(); String formName=formElement.getAttributes().getValue("name"); if ("MyForm".equals(formName)) { myForm=form; break; } } FormFields formFields=myForm.getFormFields(); formFields.clearValues(); // clear any values that might be set in the source document formFields.addValue("Name","Humphrey Bear"); formFields.addValue("MailingList","A"); formFields.addValue("MailingList","B"); formFields.addValue("FavouriteFare","honey"); OutputDocument outputDocument=new OutputDocument(source); outputDocument.replace(formFields); String newHtmlText=outputDocument.toString();
See also the sample program FormFieldSetValues.
- Change the display characteristics of individual controls:
Source source=new Source(htmlText); FormFields formFields=source.getFormFields(); // disable some controls: formFields.get("Password").getFormControl().setDisabled(true); FormField mailingListFormField=formFields.get("MailingList"); mailingListFormField.setValue("C"); mailingListFormField.getFormControl("C").setDisabled(true); mailingListFormField.getFormControl("D").setDisabled(true); // remove some controls: formFields.get("button1").getFormControl().setOutputStyle(FormControlOutputStyle.REMOVE); FormControl rhubarbFormControl=formFields.get("FavouriteFare").getFormControl("rhubarb"); rhubarbFormControl.setOutputStyle(FormControlOutputStyle.REMOVE); // set some controls to display value: formFields.setValue("Address","The Lodge\nDeakin ACT 2600\nAustralia"); formFields.get("Address").getFormControl().setOutputStyle(FormControlOutputStyle.DISPLAY_VALUE); FormField favouriteSportsFormField=formFields.get("FavouriteSports"); favouriteSportsFormField.setValue("BB"); favouriteSportsFormField.addValue("AFL"); favouriteSportsFormField.getFormControl().setOutputStyle(FormControlOutputStyle.DISPLAY_VALUE); OutputDocument outputDocument=new OutputDocument(source); outputDocument.replace(formFields); // adds all segments necessary to effect changes String newHtmlText=outputDocument.toString();
See also the sample program FormControlDisplayCharacteristics.
- See Also:
FormField
,FormControl
-
Modify the submission values of the constituent form controls
for subsequent output in an
-
-
Constructor Summary
Constructors Constructor Description FormFields(java.util.Collection<FormControl> formControls)
Constructs a newFormFields
object consisting of the specified form controls.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
addValue(java.lang.String fieldName, java.lang.String value)
Adds the specified value to the field submission values of the constituent form field with the specified name.void
clearValues()
Clears the submission values of all the constituent form controls.FormField
get(java.lang.String fieldName)
Returns theFormField
with the specified name.java.lang.String[]
getColumnLabels()
Returns a string array containing the column labels corresponding to the values from thegetColumnValues(Map)
method.java.lang.String[]
getColumnValues()
Converts all the form submission values of the constituent form fields into a simple string array, suitable for storage in a tabular format such as a database table or.CSV
file.java.lang.String[]
getColumnValues(java.util.Map<java.lang.String,java.lang.String[]> dataSet)
Converts the data values in the specified field data set into a simple string array, suitable for storage in a tabular format such as a database table or.CSV
file.int
getCount()
Returns the number ofFormField
objects.java.util.Map<java.lang.String,java.lang.String[]>
getDataSet()
Returns the entire field data set represented by the values of the constituent form fields.java.lang.String
getDebugInfo()
Returns a string representation of this object useful for debugging purposes.java.util.List
getFormControls()
Returns a list of all the constituent form controls from all the form fields in this collection.java.util.List<java.lang.String>
getValues(java.lang.String fieldName)
Returns a list of the field submission values of all the specified constituent form fields with the specified name.java.util.Iterator<FormField>
iterator()
Returns an iterator over theFormField
objects in the collection.void
merge(FormFields formFields)
Merges the specifiedFormFields
into thisFormFields
collection.void
setDataSet(java.util.Map<java.lang.String,java.lang.String[]> dataSet)
Sets the submission values of all the constituent form controls to match the data in the specified field data set.boolean
setValue(java.lang.String fieldName, java.lang.String value)
Sets the field submission values of the constituent form field with the specified name to the single specified value.int
size()
Returns the number ofFormField
objects.java.lang.String
toString()
Returns a string representation of this object useful for debugging purposes.-
Methods inherited from class java.util.AbstractCollection
add, addAll, clear, contains, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray
-
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
-
-
-
-
Constructor Detail
-
FormFields
public FormFields(java.util.Collection<FormControl> formControls)
Constructs a newFormFields
object consisting of the specified form controls.- Parameters:
formControls
- a collection ofFormControl
objects.- See Also:
Segment.getFormFields()
-
-
Method Detail
-
getCount
public int getCount()
Returns the number ofFormField
objects.- Returns:
- the number of
FormField
objects.
-
size
public int size()
Returns the number ofFormField
objects.This is equivalent to
getCount()
, and is necessary to for the implementation of thejava.util.Collection
interface.
-
get
public FormField get(java.lang.String fieldName)
Returns theFormField
with the specified name.The case sensitivity of the
fieldName
argument is determined by the staticConfig.CurrentCompatibilityMode
.
FormFieldNameCaseInsensitive
property.- Parameters:
fieldName
- the name of theFormField
to get.- Returns:
- the
FormField
with the specified name, ornull
if noFormField
with the specified name exists.
-
iterator
public java.util.Iterator<FormField> iterator()
Returns an iterator over theFormField
objects in the collection.The order in which the form fields are iterated corresponds to the order of appearance of each form field's first
FormControl
in the source document.If this
FormFields
object has been merged with another, the ordering is no longer defined.
-
getValues
public java.util.List<java.lang.String> getValues(java.lang.String fieldName)
Returns a list of the field submission values of all the specified constituent form fields with the specified name.All objects in the returned list are of type
String
, with nonull
entries.This is equivalent to
get(fieldName)
.
getValues()
, assuming that a field with the specified name exists in this collection.- Parameters:
fieldName
- the name of the form field.- Returns:
- a list of the field submission values of all the specified constituent form field with the specified name, or
null
if no form field with this name exists. - See Also:
FormField.getValues()
-
getDataSet
public java.util.Map<java.lang.String,java.lang.String[]> getDataSet()
Returns the entire field data set represented by the values of the constituent form fields.The values in the map returned by this method are represented as a string array, giving the map a format consistent with the
javax.servlet.ServletRequest.getParameterMap()
method.Only the names of form fields with at least one value are included in the map, meaning every
String[]
is guaranteed to have at least one entry.Iterating over the map keys returns them in the order of appearance in the source document.
- Returns:
- the entire field data set represented by the values of the constituent form fields.
- See Also:
setDataSet(Map)
-
clearValues
public void clearValues()
Clears the submission values of all the constituent form controls.- See Also:
FormControl.clearValues()
-
setDataSet
public void setDataSet(java.util.Map<java.lang.String,java.lang.String[]> dataSet)
Sets the submission values of all the constituent form controls to match the data in the specified field data set.The map keys must be
String
field names, with each map value an array ofString
objects containing the field's new values.The map returned by the
javax.servlet.ServletRequest.getParameterMap()
method has a suitable format for use with this method.All existing values are cleared before the values from the field data set are added.
Any map entries with a
null
value are ignored.- Parameters:
dataSet
- the field data set containing the new values of the constituent form fields.- See Also:
getDataSet()
-
setValue
public boolean setValue(java.lang.String fieldName, java.lang.String value)
Sets the field submission values of the constituent form field with the specified name to the single specified value.This is equivalent to
get(fieldName)
.
setValue(value)
, assuming that a field with the specified name exists in this collection.The return value indicates whether the specified form field "accepted" the value. A return value of
false
implies an error condition as either no field with the specified name exists, or the specified value is not compatible with the specified field.- Parameters:
fieldName
- the name of the form field.value
- the new field submission value of the specified field, ornull
to clear the field of all submission values.- Returns:
true
if a field of the specified name exists in this collection and it accepts the specified value, otherwisefalse
.
-
addValue
public boolean addValue(java.lang.String fieldName, java.lang.String value)
Adds the specified value to the field submission values of the constituent form field with the specified name.This is equivalent to
get(fieldName)
.
addValue(value)
, assuming that a field with the specified name exists in this collection.The return value indicates whether the specified form field "accepted" the value. A return value of
false
implies an error condition as either no field with the specified name exists, or the specified value is not compatible with the specified field.- Parameters:
fieldName
- the name of the form field.value
- the new field submission value to add to the specified field, must not benull
.- Returns:
true
if a field of the specified name exists in this collection and it accepts the specified value, otherwisefalse
.
-
getColumnLabels
public java.lang.String[] getColumnLabels()
Returns a string array containing the column labels corresponding to the values from thegetColumnValues(Map)
method.Instead of using the name of each constituent form field to construct the labels, the name of the first form control from each form field is used. This allows the labels to be constructed using the names with the original case from the source document rather than unsing the all lower case names of the form fields.
See the documentation of the
getColumnValues(Map)
method for more details.- Returns:
- a string array containing the column labels corresponding to the values from the
getColumnValues(Map)
method. - See Also:
Util.outputCSVLine(Writer,String[])
-
getColumnValues
public java.lang.String[] getColumnValues(java.util.Map<java.lang.String,java.lang.String[]> dataSet)
Converts the data values in the specified field data set into a simple string array, suitable for storage in a tabular format such as a database table or.CSV
file.The conversion is performed in a way that allows the multiple values of certain fields to be stored in separate columns, by analysing the possible form data sets that can be generated from the constituent form controls.
The column labels and values are determined as follows:
-
For each form field in this collection (taken in iterator order):
-
If the form field has no predefined values,
such as a single text control, then:
-
Add a single column:
Label: the name of the form field in original case Value: the single value mapped to this field in the specified field data set. Config.ColumnMultipleValueSeparator
property.
-
Add a single column:
-
Otherwise, if the form field does have predefined values,
but does not allow multiple values, then:
-
If the form field has only one predefined value,
such as a single checkbox, then:
-
Add a single boolean column:
Label: the name of the form field in original case Value: the currently configured string representation for true if a value mapped to this field in the specified field data set matches the predefined value, otherwise false
-
Add a single boolean column:
-
Otherwise, if the form field has more than one predefined value,
such as a set of radio buttons, then:
-
Add a single column:
Label: the name of the form field in original case Value: the single value mapped to this field in the specified field data set, which in the case of a set of radio buttons should be the predefined value of the checked radio button.
-
Add a single column:
-
If the form field has only one predefined value,
such as a single checkbox, then:
-
Otherwise, if the form field has predefined values
and allows multiple values,
such as a set of checkboxes, then:
-
For each predefined value in the form field:
-
Add a boolean column:
Label: " FieldName.PredefinedValue
", whereFieldName
is the name of the form field in original case, andPredefinedValue
is the predefined value.Value: the currently configured string representation for true if a value mapped to this field in the specified field data set matches the predefined value, otherwise false
-
Add a boolean column:
-
In addition, if the form field can also contain user values (
FormField.getUserValueCount()
>0
), then:-
Add another column:
Label: the name of the form field in original case Value: all values mapped to this field in the specified field data set that do not match any of the predefined values, separated by the text defined in the static Config.ColumnMultipleValueSeparator
property.
-
Add another column:
-
For each predefined value in the form field:
-
If the form field has no predefined values,
such as a single text control, then:
The sample program FormFieldCSVOutput demonstrates the use of this method and its output.
- Parameters:
dataSet
- a field data set containing the data to convert.- Returns:
- the data values in the specified field data set in the form of a simple string array.
- See Also:
Util.outputCSVLine(Writer,String[])
,getColumnLabels()
,getColumnValues()
-
For each form field in this collection (taken in iterator order):
-
getColumnValues
public java.lang.String[] getColumnValues()
Converts all the form submission values of the constituent form fields into a simple string array, suitable for storage in a tabular format such as a database table or.CSV
file.This is equivalent to
getColumnValues
(
getDataSet()
)
.- Returns:
- all the form submission values of the constituent form fields in the form of a simple string array.
-
getFormControls
public java.util.List getFormControls()
Returns a list of all the constituent form controls from all the form fields in this collection.- Returns:
- a list of all the constituent form controls from all the form fields in this collection.
-
merge
public void merge(FormFields formFields)
Merges the specifiedFormFields
into thisFormFields
collection. This is useful if a full collection of possible form fields is required from multiple source documents.If both collections contain a
FormField
with the same name, the resultingFormField
has the following properties:getUserValueCount()
: the maximum user value count from both form fieldsallowsMultipleValues()
:true
if either form field allows multiple valuesgetPredefinedValues()
: the union of predefined values in both form fieldsgetFormControls()
: the union of form controls from both form fields
NOTE: Some underlying data structures may end up being shared between the two merged
FormFields
collections.
-
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()
.- Overrides:
toString
in classjava.util.AbstractCollection<FormField>
- Returns:
- a string representation of this object useful for debugging purposes.
-
-