Class FormControl
- java.lang.Object
-
- Segment
-
- 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()
returnstrue
. It has a control type ofCHECKBOX
,RADIO
,BUTTON
,SUBMIT
,IMAGE
,SELECT_SINGLE
orSELECT_MULTIPLE
.A user value control is a form control for which
getFormControlType()
.hasPredefinedValue()
returnsfalse
. It has a control type ofFILE
,HIDDEN
,PASSWORD
,TEXT
orTEXTAREA
.The functionality of most significance to users of this class relates to the display characteristics of the output element, manipulated using the
setDisabled(boolean)
andsetOutputStyle(FormControlOutputStyle)
methods.As a general rule, the operations dealing with the control's submission values are better performed on a
FormFields
orFormField
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 oneRADIO
control with a given name ischecked
at a time.A
FormFields
object can be directly constructed from a collection ofFormControl
objects.FormControl
instances are obtained using theElement.getFormControl()
method or are created automatically with the creation of aFormFields
object via theSegment.getFormFields()
method.- See Also:
FormControlType
,FormFields
,FormField
-
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method 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()
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
-
-
-
-
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 staticConfig.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 theOPTION
elements contained within this control, in order of appearance.This method is only relevant to form controls with a type of
SELECT_SINGLE
orSELECT_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 notSELECT_SINGLE
orSELECT_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 theFormControlOutputStyle
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 correspondingString
attribute values, with anull
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, otherwisefalse
.
-
setDisabled
public final void setDisabled(boolean disabled)
Sets whether this form control is disabled.If the argument supplied to this method is
true
and thedisabled
attribute is not already present in the output element, the full XHTML compatible attributedisabled="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
orFormControlType.RADIO
, and throws anUnsupportedOperationException
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 callingclearValues()
.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 callingsetValue(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 callingclearValues()
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, otherwisefalse
.- Throws:
java.lang.UnsupportedOperationException
- if the type of this control is notFormControlType.CHECKBOX
orFormControlType.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 returnnull
.CHECKBOX
andRADIO
controls have a guaranteed predefined value determined by the value of its compulsoryvalue
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
andIMAGE
controls have an optional predefined value determined by the value of itsvalue
attribute. This value is successful only in the control used to submit the form.FormControlType.SELECT_SINGLE
andFormControlType.SELECT_MULTIPLE
controls are special cases because they usually contain multipleOPTION
elements, each with its own predefined value. In this case thegetPredefinedValues()
method should be used instead, which returns a collection of all the control's predefined values. Attempting to call this method on aSELECT
control results in ajava.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 nonull
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 thegetPredefinedValue()
method, so for efficiency it is recommended to use thegetPredefinedValue()
method instead.The multiple predefined values of a
SELECT
control are defined by theOPTION
elements within it. EachOPTION
element has an initial value determined by the value of itsvalue
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 nonull
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
andRADIO
controls have a submission value specified by its predefined value if it ischecked
, otherwise it has no submission value.SELECT_SINGLE
andSELECT_MULTIPLE
controls have submission values specified by the values of the control's selectedOPTION
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. ASELECT_SINGLE
control only returns multiple submission values if it illegally contains multiple selected options in the source document.SUBMIT
,BUTTON
, andIMAGE
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
andAttribute
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
andFormField
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
andFormField
classes provide a more appropriate abstraction level for the modification of form control submission values. Consider using theFormFields.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
orselected
as detailed below:CHECKBOX
andRADIO
controls becomechecked
and the method returnstrue
if the specified value matches the control's predefined value (case sensitive), otherwise the control becomes unchecked and the method returnsfalse
. Note that any other controls with the same name are not unchecked if this control becomes checked, possibly resulting in an invalid state where multipleRADIO
controls are checked at the same time. TheFormField.setValue(String)
method avoids such problems and its use is recommended over this method.SELECT_SINGLE
andSELECT_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
, andIMAGE
controls never have a submission value, so calling this method has no effect and always returnsfalse
.- Parameters:
value
- the new submission value of this control, ornull
to clear the control of all submission values.- Returns:
true
if the control accepts the value, otherwisefalse
.- 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
andFormField
classes provide a more appropriate abstraction level for the modification of form control submission values. Consider using theFormFields.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'sOPTION
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 benull
.- Returns:
true
if the control accepts the value, otherwisefalse
.- 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 classSegment
- Returns:
- a string representation of this object useful for debugging purposes.
-
-