public abstract class FormControl extends Segment
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.
FormControlType,
FormFields,
FormField| 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()
|
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 *.
|
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, toStringpublic final FormControlType getFormControlType()
public final java.lang.String getName()
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.
null if the name attribute is missing.public final Element getElement()
The attributes of this source element should correspond with the output attributes if the display characteristics or submission values have not been modified.
public java.util.Iterator<Element> getOptionElementIterator()
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.
OPTION elements contained within this control, in order of appearance.java.lang.UnsupportedOperationException - if the type of this control is not SELECT_SINGLE or SELECT_MULTIPLE.public FormControlOutputStyle getOutputStyle()
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.
setOutputStyle(FormControlOutputStyle)public void setOutputStyle(FormControlOutputStyle outputStyle)
See the getOutputStyle() method for a full description of this property.
outputStyle - the new output style of this form control.public final java.util.Map<java.lang.String,java.lang.String> getAttributesMap()
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.
public final boolean isDisabled()
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.
true if this form control is disabled, otherwise false.public final void setDisabled(boolean 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.
disabled - the new value of this property.public boolean isChecked()
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.
true if this form control is checked, otherwise false.java.lang.UnsupportedOperationException - if the type of this control is not FormControlType.CHECKBOX or FormControlType.RADIO.public java.lang.String getPredefinedValue()
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.
null if none.public java.util.Collection<java.lang.String> getPredefinedValues()
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.
null.FormField.getPredefinedValues()public java.util.List<java.lang.String> getValues()
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.
null.getPredefinedValues()public final void clearValues()
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.
public abstract boolean setValue(java.lang.String 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.
value - the new submission value of this control, or null to clear the control of all submission values.true if the control accepts the value, otherwise false.FormFields.setValue(String fieldName, String value)public boolean addValue(java.lang.String 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.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.
value - the value to add to this control's submission values, must not be null.true if the control accepts the value, otherwise false.FormFields.addValue(String fieldName, String value)public java.lang.String getDebugInfo()
SegmentgetDebugInfo in class Segment