Java Doc for FormFields.java in  » HTML-Parser » jericho-html » au » id » jericho » lib » html » Java Source Code / Java DocumentationJava Source Code and Java Documentation

This class provides the main interface for the analysis and manipulation of . A FormFields object is a collection of FormField objects, with each form field consisting of a group of having the same .

The functionality provided by this class can be used to accomplish two main tasks:

1. Modify the submission values of the constituent form controls for subsequent output in an OutputDocument .

   The methods available for this purpose are:
   FormFields.getValues(String) Collection getValues(String fieldName)
   FormFields.getDataSet() Map getDataSet()
   FormFields.clearValues() void clearValues()
   FormFields.setDataSet(Map) void setDataSet(Map)
   FormFields.setValue(String,CharSequence) boolean setValue(String fieldName, CharSequence value)
   FormFields.addValue(String,CharSequence) 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 , replaced with a simple , or altogether, can only be set on the individual FormControl objects. See below for information about retrieving a specific FormControl object from the FormFields object.

2. 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:
   FormFields.getColumnLabels() String[] getColumnLabels()
   FormFields.getColumnValues(Map) String[] getColumnValues(Map)
   FormFields.getColumnValues() String[] getColumnValues()
   

   The Util class contains a method called Util.outputCSVLine(WriterString[]) 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. FormFields.get(String) get(fieldName) . FormField.getFormControl getFormControl() if the control is the only one with the specified , or
• formFields. FormFields.get(String) get(fieldName) . FormField.getFormControl(String) getFormControl(predefinedValue) to retrieve the control having the speficied if it is part of a 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 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.FormFields(Collection formControls) constructor or by calling the Segment.findFormFields method.

The case sensitivity of form field names is determined by the Config.CurrentCompatibilityMode . Config.CompatibilityMode.isFormFieldNameCaseInsensitive FormFieldNameCaseInsensitive property.

Examples:

1. 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.
   
   

2. 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("FavouriteFare","honey");
    OutputDocument outputDocument=new OutputDocument(source);
    outputDocument.replace(formFields);
    String newHtmlText=outputDocument.toString();

   See also the sample program FormFieldSetValues.
   
   

3. 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("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.
   
   

This is equivalent to FormFields.get(String) get(fieldName) . FormField.addValue(CharSequence) 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 of the form field.
Parameters:
  value - the new field submission value to add to the specified field, must not be null.

The case sensitivity of the fieldName argument is determined by the Config.CurrentCompatibilityMode . Config.CompatibilityMode.isFormFieldNameCaseInsensitive FormFieldNameCaseInsensitive property.
Parameters:
  fieldName - the name of the FormField to get.

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 .

The column labels and values are determined as follows:

• For each in this collection (taken in order):
  • If the form field has no , such as a single , then:
    • Add a single column:

      :	the of the form field in original case
      Value:	the single value mapped to this field in the specified field data set.

      In the unlikely event that this field contains more than one value, all values are included in this one column and separated by the text defined in the Config.ColumnMultipleValueSeparator property.
  • Otherwise, if the form field does have , but does not , then:
    • If the form field has only one , such as a single , then:
      • Add a single boolean column:

        :	the of the form field in original case
        Value:	the currently configured string representation for if a value mapped to this field in the specified field data set matches the , otherwise

    • Otherwise, if the form field has more than one , such as a set of , then:
      • Add a single column:

        :	the 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 of the radio button.

  • Otherwise, if the form field has and , such as a set of , then:
    • For each in the form field:
      • Add a boolean column:

        :	"FieldName.PredefinedValue", where FieldName is the of the form field in original case, and PredefinedValue is the .
        Value:	the currently configured string representation for if a value mapped to this field in the specified field data set matches the , otherwise

    • In addition, if the form field can also contain user values ( FormField.getUserValueCount >0), then:
      • Add another column:

        :	the 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 , separated by the text defined in the Config.ColumnMultipleValueSeparator property.

The sample program FormFieldCSVOutput demonstrates the use of this method and its output.
Parameters:
  dataSet - a field data set containing the data to convert.

All objects in the returned collection are of type CharSequence, with no null entries.

This is equivalent to FormFields.get(String) get(fieldName) . FormField.getValues getValues() , assuming that a field with the specified name exists in this collection.
Parameters:
  fieldName - the of the form field.

This is equivalent to FormFields.get(String) get(fieldName) . FormField.setValue(CharSequence) 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 of the form field.
Parameters:
  value - the new field submission value of the specified field, or null to the field of all submission values.

This is equivalent to FormFields.get(String) get(fieldName) . FormField.addValue(CharSequence) 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 of the form field.
Parameters:
  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.

The case sensitivity of the fieldName argument is determined by the Config.CurrentCompatibilityMode . Config.CompatibilityMode.isFormFieldNameCaseInsensitive FormFieldNameCaseInsensitive property.
Parameters:
  fieldName - the name of the FormField to get. the FormField with the specified , or null if no FormField with the specified name exists.

Instead of using the of each constituent form field to construct the labels, the of the first 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 FormFields.getColumnValues(Map) method for more details. a string array containing the column labels corresponding to the values from the FormFields.getColumnValues(Map) method.
See Also:   Util.outputCSVLine(WriterString[])

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 .

The column labels and values are determined as follows:

• For each in this collection (taken in order):
  • If the form field has no , such as a single , then:
    • Add a single column:

      :	the of the form field in original case
      Value:	the single value mapped to this field in the specified field data set.

      In the unlikely event that this field contains more than one value, all values are included in this one column and separated by the text defined in the Config.ColumnMultipleValueSeparator property.
  • Otherwise, if the form field does have , but does not , then:
    • If the form field has only one , such as a single , then:
      • Add a single boolean column:

        :	the of the form field in original case
        Value:	the currently configured string representation for if a value mapped to this field in the specified field data set matches the , otherwise

    • Otherwise, if the form field has more than one , such as a set of , then:
      • Add a single column:

        :	the 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 of the radio button.

  • Otherwise, if the form field has and , such as a set of , then:
    • For each in the form field:
      • Add a boolean column:

        :	"FieldName.PredefinedValue", where FieldName is the of the form field in original case, and PredefinedValue is the .
        Value:	the currently configured string representation for if a value mapped to this field in the specified field data set matches the , otherwise

    • In addition, if the form field can also contain user values ( FormField.getUserValueCount >0), then:
      • Add another column:

        :	the 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 , separated by the text defined in the Config.ColumnMultipleValueSeparator property.

The sample program FormFieldCSVOutput demonstrates the use of this method and its output.
Parameters:
  dataSet - a field data set containing the data to convert. the data values in the specified field data set in the form of a simple string array.
See Also:   Util.outputCSVLine(WriterString[])
See Also:   FormFields.getColumnLabels()
See Also:   FormFields.getColumnValues()

This is equivalent to FormFields.getColumnValues(Map) getColumnValues ( FormFields.getDataSet() ). all the of the constituent form fields in the form of a simple string array.

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 of form fields with at least one are included in the map, meaning every String[] is guaranteed to have at least one entry. the entire field data set represented by the of the constituent form fields.
See Also:   FormFields.setDataSet(Map)

All objects in the returned collection are of type CharSequence, with no null entries.

This is equivalent to FormFields.get(String) get(fieldName) . FormField.getValues getValues() , assuming that a field with the specified name exists in this collection.
Parameters:
  fieldName - the of the form field. a collection of the field submission values of all the specified constituent with the specified , or null if no form field with this name exists.
See Also:   FormField.getValues

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 with another, the ordering is no longer defined. an iterator over the FormField objects in the collection.

If both collections contain a FormField with the same , the resulting FormField has the following properties:

• FormField.getUserValueCount getUserValueCount() : the maximum user value count from both form fields
• FormField.allowsMultipleValues allowsMultipleValues() : true if either form field allows multiple values
• FormField.getPredefinedValues getPredefinedValues() : the union of predefined values in both form fields
• FormField.getFormControls getFormControls() : the union of from both form fields

NOTE: Some underlying data structures may end up being shared between the two merged FormFields collections.

The map keys must be String , with each map value either an array or Collection of CharSequence objects containing the field's new .

The map returned by the javax.servlet.ServletRequest.getParameterMap() method has a suitable format for use with this method.

All existing values are 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 of the constituent form fields.
See Also:   FormFields.getDataSet()

This is equivalent to FormFields.get(String) get(fieldName) . FormField.setValue(CharSequence) 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 of the form field.
Parameters:
  value - the new field submission value of the specified field, or null to 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.

This is equivalent to FormFields.getCount() , and is necessary to for the implementation of the java.util.Collection interface. the number of FormField objects.

This is equivalent to FormFields.getDebugInfo() . a string representation of this object useful for debugging purposes.