FormControl
Date: 2016-12-04

net.htmlparser.jericho

## Class FormControl

- java.lang.Object
- - net.htmlparser.jericho.Segment
  - - net.htmlparser.jericho.FormControl

- All Implemented Interfaces:
    java.lang.CharSequence, java.lang.Comparable<Segment>

      public abstract class FormControl
      extends Segment

  Represents an HTML form control.

  A `FormControl` consists of a single element that matches one of the form control types.

  The term output element is used to describe the element that is output if this form control is replaced in an `OutputDocument`.

  A predefined value control is a form control for which `getFormControlType()`.`hasPredefinedValue()` returns `true`. It has a control type of `CHECKBOX`, `RADIO`, `BUTTON`, `SUBMIT`, `IMAGE`, `SELECT_SINGLE` or `SELECT_MULTIPLE`.

  A user value control is a form control for which `getFormControlType()`.`hasPredefinedValue()` returns `false`. It has a control type of `FILE`, `HIDDEN`, `PASSWORD`, `TEXT` or `TEXTAREA`.

  The functionality of most significance to users of this class relates to the display characteristics of the output element, manipulated using the `setDisabled(boolean)` and `setOutputStyle(FormControlOutputStyle)` methods.

  As a general rule, the operations dealing with the control's submission values are better performed on a `FormFields` or `FormField` object, which provide a more intuitive interface by grouping form controls of the same name together. The higher abstraction level of these classes means they can automatically ensure that the submission values of their constituent controls are consistent with each other, for example by ensuring that only one `RADIO` control with a given name is `checked` at a time.

  A `FormFields` object can be directly constructed from a collection of `FormControl` objects.

  `FormControl` instances are obtained using the `Element.getFormControl()` method or are created automatically with the creation of a `FormFields` object via the `Segment.getFormFields()` method.

  See Also:
    `FormControlType`, `FormFields`, `FormField`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `addValue(java.lang.String value)` Adds the specified value to this control's submission values *.
    `void` | `clearValues()` Clears the control's existing submission values.
    `java.util.Map<java.lang.String,java.lang.String>` | `getAttributesMap()` Returns a map of the names and values of this form control's output attributes.
    `java.lang.String` | `getDebugInfo()` Returns a string representation of this object useful for debugging purposes.
    `Element` | `getElement()` Returns the element representing this form control in the source document.
    `FormControlType` | `getFormControlType()` Returns the type of this form control.
    `java.lang.String` | `getName()` Returns the name of the control.
    `java.util.Iterator<Element>` | `getOptionElementIterator()` Returns an iterator over the `OPTION` elements contained within this control, in order of appearance.
    `FormControlOutputStyle` | `getOutputStyle()` Returns the current output style of this form control.
    `java.lang.String` | `getPredefinedValue()` Returns the initial value of this control if it has a predefined value.
    `java.util.Collection<java.lang.String>` | `getPredefinedValues()` Returns a collection of all predefined values in this control in order of appearance.
    `java.util.List<java.lang.String>` | `getValues()` Returns a list of the control's submission values in order of appearance.
    `boolean` | `isChecked()` Indicates whether this form control is checked.
    `boolean` | `isDisabled()` Indicates whether this form control is disabled.
    `void` | `setDisabled(boolean disabled)` Sets whether this form control is disabled.
    `void` | `setOutputStyle(FormControlOutputStyle outputStyle)` Sets the output style of this form control.
    `abstract boolean` | `setValue(java.lang.String value)` Sets the control's submission value *.

    - ### Methods inherited from class net.htmlparser.jericho.Segment

      `charAt, compareTo, encloses, encloses, equals, getAllCharacterReferences, getAllElements, getAllElements, getAllElements, getAllElements, getAllElements, getAllElementsByClass, getAllStartTags, getAllStartTags, getAllStartTags, getAllStartTags, getAllStartTags, getAllStartTagsByClass, getAllTags, getAllTags, getBegin, getChildElements, getEnd, getFirstElement, getFirstElement, getFirstElement, getFirstElement, getFirstElementByClass, getFirstStartTag, getFirstStartTag, getFirstStartTag, getFirstStartTag, getFirstStartTag, getFirstStartTagByClass, getFormControls, getFormFields, getMaxDepthIndicator, getNodeIterator, getRenderer, getRowColumnVector, getSource, getStyleURISegments, getTextExtractor, getURIAttributes, hashCode, ignoreWhenParsing, isWhiteSpace, isWhiteSpace, length, parseAttributes, subSequence, toString`

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

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

- - ### Method Detail

    - #### getFormControlType

          public final FormControlType getFormControlType()

      Returns the type of this form control.
      Returns:
        the type of this form control.

    - #### getName

          public final java.lang.String getName()

      Returns the name of the control.

      The name comes from the value of the `name` attribute of the form control's element, not the name of the element itself.

      Since a `FormField` 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.

      In contrast to the `FormField.getName()` method, this method always returns the name using the original case from the source document, regardless of the current setting of the static `Config.CurrentCompatibilityMode``.``FormFieldNameCaseInsensitive` property.

      Returns:
        the name of the control.

    - #### getElement

          public final Element getElement()

      Returns the element representing this form control in the source document.

      The attributes of this source element should correspond with the output attributes if the display characteristics or submission values have not been modified.

      Returns:
        the element representing this form control in the source document.

    - #### getOptionElementIterator

          public java.util.Iterator<Element> getOptionElementIterator()

      Returns an iterator over the `OPTION` elements contained within this control, in order of appearance.

      This method is only relevant to form controls with a type of `SELECT_SINGLE` or `SELECT_MULTIPLE`.

      Returns:
        an iterator over the `OPTION` elements contained within this control, in order of appearance.
      Throws:
        `java.lang.UnsupportedOperationException` - if the type of this control is not `SELECT_SINGLE` or `SELECT_MULTIPLE`.

    - #### getOutputStyle

          public FormControlOutputStyle getOutputStyle()

      Returns the current output style of this form control.

      This property affects how this form control is displayed if it has been replaced in an `OutputDocument`. See the documentation of the `FormControlOutputStyle` class for information on the available output styles.

      The default output style for every form control is `FormControlOutputStyle.NORMAL`.

      Returns:
        the current output style of this form control.
      See Also:
        `setOutputStyle(FormControlOutputStyle)`

    - #### setOutputStyle

          public void setOutputStyle(FormControlOutputStyle outputStyle)

      Sets the output style of this form control.

      See the `getOutputStyle()` method for a full description of this property.

      Parameters:
        `outputStyle` - the new output style of this form control.

    - #### getAttributesMap

          public final java.util.Map<java.lang.String,java.lang.String> getAttributesMap()

      Returns a map of the names and values of this form control's output attributes.

      The term output attributes is used in this library to refer to the attributes of a form control's output element.

      The map keys are the `String` attribute names, which should all be in lower case. The map values are the corresponding `String` attribute values, with a `null` value given to an attribute that has no value.

      Direct manipulation of the returned map affects the attributes of this form control's output element. It is the responsibility of the user to ensure that all entries added to the map use the correct key and value types, and that all keys (attribute names) are in lower case.

      It is recommended that the submission value modification methods are used to modify attributes that affect the submission value of the control rather than manipulating the attributes map directly.

      An iteration over the map entries will return the attributes in the same order as they appeared in the source document, or at the end if the attribute was not present in the source document.

      The returned attributes only correspond with those of the source element if the control's display characteristics and submission values have not been modified.

      Returns:
        a map of the names and values of this form control's output attributes.

    - #### isDisabled

          public final boolean isDisabled()

      Indicates whether this form control is disabled.

      The form control is disabled if the attribute "`disabled`" is present in its output element.

      The return value is is logically equivalent to `getAttributesMap()``.containsKey("disabled")`, but using this property may be more efficient in some circumstances.

      Returns:
        `true` if this form control is disabled, otherwise `false`.

    - #### setDisabled

          public final void setDisabled(boolean disabled)

      Sets whether this form control is disabled.

      If the argument supplied to this method is `true` and the `disabled` attribute is not already present in the output element, the full XHTML compatible attribute `disabled="disabled"` is added. If the attribute is already present, it is left unchanged.

      If the argument supplied to this method is `false`, the attribute is removed from the output element.

      See the `isDisabled()` method for more information.

      Parameters:
        `disabled` - the new value of this property.

    - #### isChecked

          public boolean isChecked()

      Indicates whether this form control is checked.

      The term checked is used to describe a checkbox or radio button control that is selected, which is the case if the attribute "`checked`" is present in its output element.

      This property is only relevant to form controls with a type of `FormControlType.CHECKBOX` or `FormControlType.RADIO`, and throws an `UnsupportedOperationException` for other control types.

      Use one of the submission value modification methods to change the value of this property.

      If this control is a checkbox, you can set it to checked by calling `setValue``(``getName()``)`, and set it to unchecked by calling `clearValues()`.

      If this control is a radio button, you should use the `FormField.setValue(String)` method or one of the other higher level submission value modification methods to set the control to checked, as calling `setValue(String)` method on this object in the same way as for a checkbox does not automatically uncheck all other radio buttons with the same name. Even calling `clearValues()` on this object to ensure that this radio button is unchecked is not recommended, as it can lead to a situation where all the radio buttons with this name are unchecked. The HTML 4.01 specification of radio buttons recommends against this situation because it is not defined how user agents should handle it, and behaviour differs amongst browsers.

      The return value is logically equivalent to `getAttributesMap()``.containsKey("checked")`, but using this property may be more efficient in some circumstances.

      Returns:
        `true` if this form control is checked, otherwise `false`.
      Throws:
        `java.lang.UnsupportedOperationException` - if the type of this control is not `FormControlType.CHECKBOX` or `FormControlType.RADIO`.

    - #### getPredefinedValue

          public java.lang.String getPredefinedValue()

      Returns the initial value of this control if it has a predefined value.

      Only predefined value controls can return a non-`null` result. All other control types return `null`.

      `CHECKBOX` and `RADIO` controls have a guaranteed predefined value determined by the value of its compulsory `value` attribute. If the attribute is not present in the source document, this library assigns the control a default predefined value of "`on`", consistent with popular browsers.

      `SUBMIT`, `BUTTON` and `IMAGE` controls have an optional predefined value determined by the value of its `value` attribute. This value is successful only in the control used to submit the form.

      `FormControlType.SELECT_SINGLE` and `FormControlType.SELECT_MULTIPLE` controls are special cases because they usually contain multiple `OPTION` elements, each with its own predefined value. In this case the `getPredefinedValues()` method should be used instead, which returns a collection of all the control's predefined values. Attempting to call this method on a `SELECT` control results in a `java.lang.UnsupportedOperationException`.

      The predefined value of a control is not affected by changes to the submission value of the control.

      Returns:
        the initial value of this control if it has a predefined value, or `null` if none.

    - #### getPredefinedValues

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

      Returns a collection of all predefined values in this control in order of appearance.

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

      This method is most useful for `SELECT` controls since they typically contain multiple predefined values. In other controls it returns a collection with zero or one item based on the output of the `getPredefinedValue()` method, so for efficiency it is recommended to use the `getPredefinedValue()` method instead.

      The multiple predefined values of a `SELECT` control are defined by the `OPTION` elements within it. Each `OPTION` element has an initial value determined by the value of its `value` attribute, or if this attribute is not present, by its decoded content text with collapsed white space.

      The predefined values of a control are not affected by changes to the submission values of the control.

      Returns:
        a collection of all predefined values in this control in order of appearance, guaranteed not `null`.
      See Also:
        `FormField.getPredefinedValues()`

    - #### getValues

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

      Returns a list of the control's submission values in order of appearance.

      All objects in the returned list are of type `String`, with no `null` entries.

      The term submission value is used in this library to refer to the value the control would contribute to the form data set of a submitted form, assuming no modification of the control's current value by the user agent or by end user interaction.

      For user value controls, the submission value corresponds to the control's initial value.

      The definition of the submission value for each predefined value control type is as follows:

      `CHECKBOX` and `RADIO` controls have a submission value specified by its predefined value if it is `checked`, otherwise it has no submission value.

      `SELECT_SINGLE` and `SELECT_MULTIPLE` controls have submission values specified by the values of the control's selected `OPTION` elements.

      Only a `SELECT_MULTIPLE` control can have more than one submission value, all other control types return a list containing either one value or no values. A `SELECT_SINGLE` control only returns multiple submission values if it illegally contains multiple selected options in the source document.

      `SUBMIT`, `BUTTON`, and `IMAGE` controls are only ever successful when they are activated by the user to submit the form. Because the submission value is intended to be a static representation of a control's data without interaction by the user, this library never associates submission values with submit buttons, so this method always returns an empty list for these control types.

      The submission value(s) of a control can be modified for subsequent output in an `OutputDocument` using the various submission value modification methods, namely:
      `FormField.setValue(String)`
      `FormField.addValue(String)`
      `FormField.setValues(Collection)`
      `FormField.clearValues()`
      `FormFields.setValue(String fieldName, String value)`
      `FormFields.addValue(String fieldName, String value)`
      `FormFields.setDataSet(Map)`
      `FormFields.clearValues()`
      `FormControl.setValue(String)`
      `FormControl.addValue(String)`
      `FormControl.clearValues()`

      The values returned by this method reflect any changes made using the submission value modification methods, in contrast to methods found in the `Attributes` and `Attribute` classes, which always reflect the source document.

      Returns:
        a list of the control's submission values in order of appearance, guaranteed not `null`.
      See Also:
        `getPredefinedValues()`

    - #### clearValues

          public final void clearValues()

      Clears the control's existing submission values.

      This is equivalent to `setValue(null)`.

      NOTE: The `FormFields` and `FormField` classes provide a more appropriate abstraction level for the modification of form control submission values.

      See Also:
        `FormFields.clearValues()`, `FormField.clearValues()`

    - #### setValue

          public abstract boolean setValue(java.lang.String value)

      Sets the control's submission value *.

      * NOTE: The `FormFields` and `FormField` classes provide a more appropriate abstraction level for the modification of form control submission values. Consider using the `FormFields.setValue(String fieldName, String value)` method instead.

      The specified value replaces any existing submission values of the control.

      The return value indicates whether the control has "accepted" the value. For user value controls, the return value is always `true`.

      For predefined value controls, calling this method does not affect the control's predefined values, but instead determines whether the control (or its options) become `checked` or `selected` as detailed below:

      `CHECKBOX` and `RADIO` controls become `checked` and the method returns `true` if the specified value matches the control's predefined value (case sensitive), otherwise the control becomes unchecked and the method returns `false`. Note that any other controls with the same name are not unchecked if this control becomes checked, possibly resulting in an invalid state where multiple `RADIO` controls are checked at the same time. The `FormField.setValue(String)` method avoids such problems and its use is recommended over this method.

      `SELECT_SINGLE` and `SELECT_MULTIPLE` controls receive the specified value by selecting the option with the matching value and deselecting all others. If none of the options match, all are deselected. The return value of this method indicates whether one of the options matched.

      `SUBMIT`, `BUTTON`, and `IMAGE` controls never have a submission value, so calling this method has no effect and always returns `false`.

      Parameters:
        `value` - the new submission value of this control, or `null` to clear the control of all submission values.
      Returns:
        `true` if the control 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 this control's submission values *.

      * NOTE: The `FormFields` and `FormField` classes provide a more appropriate abstraction level for the modification of form control submission values. Consider using the `FormFields.addValue(String fieldName, String value)` method instead.

      This is almost equivalent to `setValue(String)`, with only the following differences:

      `CHECKBOX` controls retain their existing submission value instead of becoming unchecked if the specified value does not match the control's predefined value.

      `SELECT_MULTIPLE` controls retain their existing submission values, meaning that the control's `OPTION` elements whose predefined values do not match the specified value are not deselected. This is the only type of control that can have multiple submission values within the one control.

      Parameters:
        `value` - the value to add to this control's submission values, must not be `null`.
      Returns:
        `true` if the control accepts the value, otherwise `false`.
      See Also:
        `FormFields.addValue(String fieldName, String value)`

    - #### getDebugInfo

          public java.lang.String getDebugInfo()

      Description copied from class: `Segment`
      Returns a string representation of this object useful for debugging purposes.
      Overrides:
        `getDebugInfo` in class `Segment`
      Returns:
        a string representation of this object useful for debugging purposes.