net.htmlparser.jericho
Class FormControl

java.lang.Object
  extended by Segment
      extended by 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
 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 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, getNodeIterator, getRenderer, getSource, getTextExtractor, 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.