au.id.jericho.lib.html
Class FormFields
AbstractCollection
au.id.jericho.lib.html.FormFields
public final class FormFields
extends AbstractCollection
Represents a collection of
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:
-
Modify the submission values of the constituent form controls
for subsequent output in an
OutputDocument
.
The methods available for this purpose are:
Collection getValues(String fieldName)
Map getDataSet()
void clearValues()
void setDataSet(Map)
boolean setValue(String fieldName, CharSequence value)
boolean addValue(String fieldName, CharSequence 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.
-
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 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:
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
java.util.Map
with the keys (names) being of type
String
and the
values represented by either an array or collection containing one or more items of type
CharSequence
.
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.findFormFields()
method.
The case sensitivity of form field names is determined by the
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.findFormFields();
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.findAllElements(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.findFormFields();
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("FavouriteFair","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.findFormFields();
// 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("FavouriteFair").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.
FormFields
public FormFields(Collection formControls)
Constructs a new
FormFields
object consisting of the specified
form controls.
addValue
public boolean addValue(String fieldName,
CharSequence 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.
true
if a field of the specified name exists in this collection and it accepts the specified value, otherwise false
.
clearValues
public void clearValues()
get
public FormField get(String fieldName)
fieldName
- the name of the FormField
to get.
- the
FormField
with the specified name, or null
if no FormField
with the specified name exists.
getColumnLabels
public String[] getColumnLabels()
Returns a string array containing the column labels corresponding to the values from the
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.
- a string array containing the column labels corresponding to the values from the
getColumnValues(Map)
method.
getColumnValues
public String[] getColumnValues()
getColumnValues
public String[] getColumnValues(Map 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:
Otherwise, if the form field does have predefined values,
but does not allow multiple values, then:
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.
|
Otherwise, if the form field has predefined values
and allows multiple values,
such as a set of checkboxes, then:
In addition, if the form field can also contain user values (FormField.getUserValueCount()
>0
), then:
The sample program FormFieldCSVOutput demonstrates the use of this method and its output.
- the data values in the specified field data set in the form of a simple string array.
getCount
public int getCount()
Returns the number of FormField
objects.
- the number of
FormField
objects.
getDataSet
public Map 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.
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.
getFormControls
public List getFormControls()
getValues
public Collection getValues(String fieldName)
Returns a collection of the
field submission values of all the specified constituent
form field with the specified
name.
All objects in the returned collection are of type
CharSequence
, 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.
iterator
public Iterator iterator()
Returns an iterator over the
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.
- an iterator over the
FormField
objects in the collection.
merge
public void merge(FormFields formFields)
Merges the specified
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:
NOTE: Some underlying data structures may end up being shared between the two merged
FormFields
collections.
setDataSet
public void setDataSet(Map dataSet)
setValue
public boolean setValue(String fieldName,
CharSequence 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.
true
if a field of the specified name exists in this collection and it accepts the specified value, otherwise false
.
size
public int size()
Returns the number of
FormField
objects.
This is equivalent to
getCount()
,
and is necessary to for the implementation of the
java.util.Collection
interface.
- the number of
FormField
objects.
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.