| java.lang.Object
 au.id.jericho.lib.html.Segment
au.id.jericho.lib.html.FormControl
| FormControl | | abstract public class FormControl extends Segment (Code) | | Represents an HTML form control.
A FormControl consists of a single
that matches one of the
.
The term output element is used to describe the element that is
if this form control is
in an
OutputDocument .
A predefined value control is a form control for which
FormControl.getFormControlType() .
FormControlType.hasPredefinedValue hasPredefinedValue() returns true. It has a
of
FormControlType.CHECKBOX CHECKBOX ,
FormControlType.RADIO RADIO ,
FormControlType.BUTTON BUTTON ,
FormControlType.SUBMIT SUBMIT ,
FormControlType.IMAGE IMAGE ,
FormControlType.SELECT_SINGLE SELECT_SINGLE or
FormControlType.SELECT_MULTIPLE SELECT_MULTIPLE .
A user value control is a form control for which
FormControl.getFormControlType() .
FormControlType.hasPredefinedValue hasPredefinedValue() returns false. It has a
of
FormControlType.FILE FILE ,
FormControlType.HIDDEN HIDDEN ,
FormControlType.PASSWORD PASSWORD ,
FormControlType.TEXT TEXT or
FormControlType.TEXTAREA TEXTAREA .
The functionality of most significance to users of this class relates to the
display characteristics of the output element,
manipulated using the
FormControl.setDisabled(boolean) and
FormControl.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
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
FormControlType.RADIO RADIO control with a given name is
FormControl.isChecked() checked at a time.
A
FormFields object can be directly
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.findFormFields method.
See Also: FormControlType
See Also: FormFields
See Also: FormField |
| Inner Class :final static class InputFormControl extends FormControl | |
| Inner Class :final static class TextAreaFormControl extends FormControl | |
| Inner Class :final static class RadioCheckboxFormControl extends FormControl | |
| Inner Class :static class SubmitFormControl extends FormControl | |
| Inner Class :final static class ImageSubmitFormControl extends SubmitFormControl | |
| Inner Class :final static class SelectFormControl extends FormControl | |
| Inner Class :final static class ElementContainer | |
| Method Summary | |
| abstract void | addToFormFields(FormFields formFields)
| | public boolean | addValue(CharSequence 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 fieldNameCharSequence value) method instead.
This is almost equivalent to
FormControl.setValue(CharSequence) , with only the following differences:
FormControlType.CHECKBOX CHECKBOX controls retain their existing submission value
instead of becoming unchecked if the specified value does not match the control's
.
FormControlType.SELECT_MULTIPLE SELECT_MULTIPLE controls retain their existing
submission values, meaning that the control's
OPTION
elements whose
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. | | abstract void | addValuesTo(Collection collection)
| | final public void | clearValues()
Clears the control's existing submission values. | | static FormControl | construct(Element element)
| | static List | findAll(Segment segment)
| | final public Map | getAttributesMap()
Returns a map of the names and values of this form control's output attributes. | | public String | getDebugInfo()
| | final String | getDisplayValueHTML(CharSequence text, boolean whiteSpaceFormatting)
| | final public Element | getElement()
Returns the
representing this form control in the source document. | | final public FormControlType | getFormControlType()
Returns the
of this form control. | | final public String | getName()
Returns the name of the control. | | public Iterator | getOptionElementIterator()
Returns an iterator over the
Tag.OPTION OPTION
contained within this control, in order of appearance. | | public FormControlOutputStyle | getOutputStyle()
Returns the current
of this form control. | | public String | getPredefinedValue()
Returns the initial value of this control if it has a
.
Only predefined value controls can return a non-null result.
All other control types return null.
FormControlType.CHECKBOX CHECKBOX and
FormControlType.RADIO RADIO controls have a guaranteed
predefined value determined by the value of its compulsory
value
attribute. | | public Collection | getPredefinedValues()
Returns a collection of all
in this control. | | public Collection | getValues()
Returns a collection of the control's submission values. | | public boolean | isChecked()
Indicates whether this form control is checked. | | final public boolean | isDisabled()
Indicates whether this form control is disabled. | | final void | replaceAttributesInOutputDocumentIfModified(OutputDocument outputDocument)
| | abstract void | replaceInOutputDocument(OutputDocument outputDocument)
| | final public 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. | | public void | setOutputStyle(FormControlOutputStyle outputStyle)
Sets the
of this form control. | | abstract public boolean | setValue(CharSequence 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 fieldNameCharSequence 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
, but instead determines whether the control (or its options) become
checked or
selected
as detailed below:
FormControlType.CHECKBOX CHECKBOX and
FormControlType.RADIO RADIO controls become
FormControl.isChecked() 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
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(CharSequence) method avoids such problems and its use is recommended over this method.
FormControlType.SELECT_SINGLE SELECT_SINGLE and
FormControlType.SELECT_MULTIPLE 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.
FormControlType.SUBMIT SUBMIT ,
FormControlType.BUTTON BUTTON , and
FormControlType.IMAGE 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. |
| elementContainer | | ElementContainer elementContainer(Code) | | |
| getAttributesMap | | final public Map getAttributesMap()(Code) | | 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 CharSequence attribute values, with a null value given
to an attribute that
.
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
if the control's
display characteristics and submission values
have not been modified.
a map of the names and values of this form control's output attributes. |
| getFormControlType | | final public FormControlType getFormControlType()(Code) | | Returns the
of this form control.
the of this form control. |
| getName | | final public String getName()(Code) | | Returns the name of the control.
The name comes from the value of the name
of the
, not the
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
Config.CurrentCompatibilityMode .
Config.CompatibilityMode.isFormFieldNameCaseInsensitive FormFieldNameCaseInsensitive property.
the name of the control. |
| getPredefinedValues | | public Collection getPredefinedValues()(Code) | | Returns a collection of all
in this control.
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
FormControl.getPredefinedValue() method, so for efficiency it is recommended to use the
FormControl.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
text with
.
The predefined values of a control are not affected by changes to the
submission values of the control.
a collection of all in this control, guaranteed not null.
See Also: FormField.getPredefinedValues |
| getValues | | public Collection getValues()(Code) | | Returns a collection of the control's submission values.
All objects in the returned collection are of type CharSequence, 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:
FormControlType.CHECKBOX CHECKBOX and
FormControlType.RADIO RADIO controls
have a submission value specified by its
if it is
FormControl.isChecked() checked , otherwise it has no submission value.
FormControlType.SELECT_SINGLE SELECT_SINGLE and
FormControlType.SELECT_MULTIPLE SELECT_MULTIPLE controls
have submission values specified by the
values of the control's
selected
OPTION elements.
Only a
FormControlType.SELECT_MULTIPLE SELECT_MULTIPLE control can have more than one submission value,
all other
return a collection containing either one value or no values.
A
FormControlType.SELECT_SINGLE SELECT_SINGLE control only returns multiple submission values
if it illegally contains multiple selected options in the source document.
FormControlType.SUBMIT SUBMIT ,
FormControlType.BUTTON BUTTON , and
FormControlType.IMAGE 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
buttons, so this method always returns an empty collection 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(CharSequence)
FormField.addValue(CharSequence)
FormField.setValues(Collection)
FormField.clearValues
FormFields.setValue(String fieldNameCharSequence value)
FormFields.addValue(String fieldNameCharSequence value)
FormFields.setDataSet(Map)
FormFields.clearValues
FormControl.setValue(CharSequence) FormControl.setValue(CharSequence)
FormControl.addValue(CharSequence) FormControl.addValue(CharSequence)
FormControl.clearValues() 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.
a collection of the control's submission values, guaranteed not null.
See Also: FormControl.getPredefinedValues() |
| isChecked | | public boolean isChecked()(Code) | | 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
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
FormControl.setValue(CharSequence) setValue (
FormControl.getName() ), and set it to unchecked by calling
FormControl.clearValues() .
If this control is a radio button, you should use the
FormField.setValue(CharSequence) method or one of the other
higher level submission value modification methods
to set the control to checked, as calling
FormControl.setValue(CharSequence) 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
FormControl.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
FormControl.getAttributesMap() .containsKey("checked"),
but using this property may be more efficient in some circumstances.
true if this form control is checked, otherwise false.
throws:
UnsupportedOperationException - if the of this control is not FormControlType.CHECKBOX or FormControlType.RADIO. |
| isDisabled | | final public boolean isDisabled()(Code) | | 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
FormControl.getAttributesMap() .containsKey("disabled"),
but using this property may be more efficient in some circumstances.
true if this form control is disabled, otherwise false. |
| replaceAttributesInOutputDocumentIfModified | | final void replaceAttributesInOutputDocumentIfModified(OutputDocument outputDocument)(Code) | | |
| setDisabled | | final public void setDisabled(boolean disabled)(Code) | | 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
FormControl.isDisabled() method for more information.
Parameters:
disabled - the new value of this property. |
| setValue | | abstract public boolean setValue(CharSequence value)(Code) | | 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 fieldNameCharSequence 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
, but instead determines whether the control (or its options) become
checked or
selected
as detailed below:
FormControlType.CHECKBOX CHECKBOX and
FormControlType.RADIO RADIO controls become
FormControl.isChecked() 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
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(CharSequence) method avoids such problems and its use is recommended over this method.
FormControlType.SELECT_SINGLE SELECT_SINGLE and
FormControlType.SELECT_MULTIPLE 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.
FormControlType.SUBMIT SUBMIT ,
FormControlType.BUTTON BUTTON , and
FormControlType.IMAGE 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. true if the control accepts the value, otherwise false.
See Also: FormFields.setValue(String fieldNameCharSequence value) |
|
|