public final class FormFields extends java.util.AbstractCollection<FormField>
FormField
objects.
This class provides the main interface for the analysis and manipulation of form controls.
A FormFields
object is a collection of FormField
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:
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
and FormControl
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
(the FormFields
) 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 specific FormControl
object from the FormFields
object.
.CSV
file.
The methods available for this purpose are:
String[] getColumnLabels()
String[] getColumnValues(Map)
String[] getColumnValues()
The Util
class contains a method called outputCSVLine(Writer,String[])
which writes the String[]
output of these methods to the specified Writer
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 a FormFields
object, use:
formFields.
get(fieldName)
.
getFormControl()
if the control is the only one with the specified name, or
formFields.
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 type String
and the values represented by an array containing one or more items of type String
.
A field data set can be used to represent the data in an HTML
form data set.
FormFields
instances are obtained using the FormFields(Collection formControls)
constructor
or by calling the Segment.getFormFields()
method.
The case sensitivity of form field names is determined by the static
Config.CurrentCompatibilityMode
.
FormFieldNameCaseInsensitive
property.
Examples:
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.
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.
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.
FormField
,
FormControl
Constructor and Description |
---|
FormFields(java.util.Collection<FormControl> formControls)
Constructs a new
FormFields object consisting of the specified form controls. |
Modifier and Type | Method and 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 the
FormField with the specified name. |
java.lang.String[] |
getColumnLabels()
Returns a string array containing the column labels corresponding to the values from the
getColumnValues(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 of
FormField 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<FormControl> |
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 the
FormField objects in the collection. |
void |
merge(FormFields formFields)
Merges the specified
FormFields into this FormFields 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 of
FormField objects. |
java.lang.String |
toString()
Returns a string representation of this object useful for debugging purposes.
|
add, addAll, clear, contains, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray
public FormFields(java.util.Collection<FormControl> formControls)
FormFields
object consisting of the specified form controls.formControls
- a collection of FormControl
objects.Segment.getFormFields()
public int getCount()
FormField
objects.FormField
objects.public int size()
FormField
objects.
This is equivalent to getCount()
,
and is necessary to for the implementation of the java.util.Collection
interface.
public FormField get(java.lang.String fieldName)
FormField
with the specified name.
The case sensitivity of the fieldName
argument is determined by the static
Config.CurrentCompatibilityMode
.
FormFieldNameCaseInsensitive
property.
fieldName
- the name of the FormField
to get.FormField
with the specified name, or null
if no FormField
with the specified name exists.public java.util.Iterator<FormField> iterator()
FormField
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.
public java.util.List<java.lang.String> getValues(java.lang.String fieldName)
All objects in the returned list are of type String
, with no null
entries.
This is equivalent to get(fieldName)
.
getValues()
,
assuming that a field with the specified name exists in this collection.
fieldName
- the name of the form field.null
if no form field with this name exists.FormField.getValues()
public java.util.Map<java.lang.String,java.lang.String[]> getDataSet()
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.
setDataSet(Map)
public void clearValues()
FormControl.clearValues()
public void setDataSet(java.util.Map<java.lang.String,java.lang.String[]> dataSet)
The map keys must be String
field names,
with each map value an array of String
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.
dataSet
- the field data set containing the new values of the constituent form fields.getDataSet()
public boolean setValue(java.lang.String fieldName, java.lang.String 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.
fieldName
- the name of the form field.value
- the new field submission value of the specified field, or null
to clear the field of all submission values.true
if a field of the specified name exists in this collection and it accepts the specified value, otherwise false
.public boolean addValue(java.lang.String fieldName, java.lang.String value)
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.
fieldName
- the name of the form field.value
- the new field submission value to add to the specified field, must not be null
.true
if a field of the specified name exists in this collection and it accepts the specified value, otherwise false
.public java.lang.String[] getColumnLabels()
getColumnValues(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.
getColumnValues(Map)
method.Util.outputCSVLine(Writer,String[])
public java.lang.String[] getColumnValues(java.util.Map<java.lang.String,java.lang.String[]> dataSet)
.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:
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.
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 |
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. |
Label: | "FieldName.PredefinedValue ",
where FieldName is the name of the form field in original case,
and PredefinedValue 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 |
FormField.getUserValueCount()
>0
), then:
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.
|
The sample program FormFieldCSVOutput demonstrates the use of this method and its output.
dataSet
- a field data set containing the data to convert.Util.outputCSVLine(Writer,String[])
,
getColumnLabels()
,
getColumnValues()
public java.lang.String[] getColumnValues()
.CSV
file.
This is equivalent to getColumnValues
(
getDataSet()
)
.
public java.util.List<FormControl> getFormControls()
public void merge(FormFields formFields)
FormFields
into this FormFields
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 resulting FormField
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.
public java.lang.String getDebugInfo()
public java.lang.String toString()
This is equivalent to getDebugInfo()
.
toString
in class java.util.AbstractCollection<FormField>