FormField
Date: 2016-12-04

net.htmlparser.jericho

## Class FormField

- java.lang.Object
- - net.htmlparser.jericho.FormField

-     public final class FormField
      extends java.lang.Object

  Represents a field in an HTML form, a field being defined as the group of all form controls having the same name.

  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:

  1. Provide methods for the modification and retrieval of form control submission values while ensuring that the states of all the field's constituent form controls remain consistent with each other.

     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.

  2. Provide a means of determining the data structure of the field, allowing a server receiving a submitted form data set to interpret and store the data in an appropriate way.

     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.

  A form field which allows user values normally consists of a single user value control, such as a `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.

  See Also:
    `FormFields`, `FormControl`, `FormControlType`

- - ### Method Summary

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

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Method Detail

    - #### getName

          public java.lang.String getName()

      Returns the control name shared by all of this field's constituent controls.

      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.

      Returns:
        the control name shared by all of this field's constituent controls.
      See Also:
        `FormControl.getName()`

    - #### getFormControls

          public java.util.Collection<FormControl> getFormControls()

      Returns a collection of all the constituent form controls in this field.

      An iterator over this collection returns the controls in the order of appearance in the source.

      Returns:
        a collection of all the constituent form controls in this field.
      See Also:
        `getFormControl()`, `getFormControl(String predefinedValue)`

    - #### getFormControl

          public FormControl getFormControl(java.lang.String predefinedValue)

      Returns the constituent `FormControl` with the specified predefined value.

      Specifying a predefined value of `null` returns the first control without a predefined value.

      Parameters:
        `predefinedValue` - the predefined value of the control to be returned, or `null` to return the first control without a predefined value.
      Returns:
        the constituent `FormControl` with the specified predefined value, or `null` if none exists.
      See Also:
        `getFormControl()`, `getFormControls()`

    - #### getFormControl

          public FormControl getFormControl()

      Returns the first `FormControl` from this field.
      Returns:
        the first `FormControl` from this field, guaranteed not `null`.
      See Also:
        `getFormControl(String predefinedValue)`, `getFormControls()`

    - #### allowsMultipleValues

          public boolean allowsMultipleValues()

      Indicates whether the field allows multiple values.

      Returns `false` in any one of the following circumstances:

      - The field consists of only one control (unless it is a multiple select with more than one option)
      - The field consists entirely of radio buttons
      - The field consists entirely of submit buttons
      If none of these three conditions are met, the method returns `true`.
      Returns:
        `true` if the field allows multiple values, otherwise `false`.

    - #### getUserValueCount

          public int getUserValueCount()

      Returns the number of constituent user value controls in this field. This should in most cases be either `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.

      Returns:
        the number of constituent user value controls in this field.

    - #### getPredefinedValues

          public java.util.Collection<java.lang.String> getPredefinedValues()

      Returns a collection of the predefined values of all constituent controls in this field.

      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.

      Returns:
        a collection of the predefined values of all constituent controls in this field, or `null` if none.
      See Also:
        `FormControl.getPredefinedValues()`

    - #### getValues

          public java.util.List<java.lang.String> getValues()

      Returns a list of the field submission values in order of appearance.

      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.

      Returns:
        a list of the field submission values in order of appearance, guaranteed not `null`.

    - #### clearValues

          public void clearValues()

      Clears the submission values of all the constituent form controls in this field.
      See Also:
        `FormControl.clearValues()`

    - #### setValues

          public void setValues(java.util.Collection<java.lang.String> values)

      Sets the field submission values of this field to the specified 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.

      Parameters:
        `values` - the new field submission values of this field.
      See Also:
        `addValue(String value)`

    - #### setValue

          public boolean setValue(java.lang.String value)

      Sets the field submission values of this field to the single specified 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.

      Parameters:
        `value` - the new field submission value of this field, or `null` to clear the field of all submission values.
      Returns:
        `true` if one of the constituent form controls accepts the value, otherwise `false`.
      See Also:
        `FormFields.setValue(String fieldName, String value)`

    - #### addValue

          public boolean addValue(java.lang.String value)

      Adds the specified value to the field submission values of this field.

      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.

      Parameters:
        `value` - the new field submission value to add to this field, must not be `null`.
      Returns:
        `true` if one of the constituent form controls accepts the value, otherwise `false`.

    - #### 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 class `java.lang.Object`
      Returns:
        a string representation of this object useful for debugging purposes.