* A FormControl consists of a single {@linkplain #getElement() element}
* that matches one of the {@linkplain FormControlType form control types}.
*
* The term output element is used to describe the element that is * {@linkplain OutputSegment#writeTo(Writer) output} if this form control is {@linkplain OutputDocument#replace(FormControl) replaced} * in an {@link OutputDocument}. *
* A predefined value control is a form control for which
* {@link #getFormControlType()}.{@link FormControlType#hasPredefinedValue() hasPredefinedValue()}
* returns true. It has a {@linkplain #getFormControlType() control type} of
* {@link FormControlType#CHECKBOX CHECKBOX}, {@link FormControlType#RADIO RADIO}, {@link FormControlType#BUTTON BUTTON},
* {@link FormControlType#SUBMIT SUBMIT}, {@link FormControlType#IMAGE IMAGE}, {@link FormControlType#SELECT_SINGLE SELECT_SINGLE}
* or {@link FormControlType#SELECT_MULTIPLE SELECT_MULTIPLE}.
*
* A user value control is a form control for which
* {@link #getFormControlType()}.{@link FormControlType#hasPredefinedValue() hasPredefinedValue()}
* returns false. It has a {@linkplain #getFormControlType() control type} of
* {@link FormControlType#FILE FILE}, {@link FormControlType#HIDDEN HIDDEN}, {@link FormControlType#PASSWORD PASSWORD},
* {@link FormControlType#TEXT TEXT} or {@link 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 {@link #setDisabled(boolean)} and {@link #setOutputStyle(FormControlOutputStyle)} methods. *
* As a general rule, the operations dealing with the control's submission values * are better performed on a {@link FormFields} or {@link FormField} object, which provide a more * intuitive interface by grouping form controls of the same {@linkplain #getName() 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 {@link FormControlType#RADIO RADIO} control with a given name is * {@link #isChecked() checked} at a time. *
* A {@link FormFields} object can be directly {@linkplain FormFields#FormFields(Collection) constructed} from
* a collection of FormControl objects.
*
*
* The name comes from the value of the
* Since a {@link 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 {@link 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
* {@link Config#CurrentCompatibilityMode}
* The {@linkplain Element#getAttributes() attributes} of this source element should correspond with the
* output attributes if the
* display characteristics or submission values
* have not been modified.
*
* @return the {@linkplain Element element} representing this form control in the source document.
*/
public final Element getElement() {
return elementContainer.element;
}
/**
* Returns an iterator over the {@link HTMLElementName#OPTION OPTION} {@linkplain Element elements} contained within this control, in order of appearance.
*
* This method is only relevant to form controls with a {@linkplain #getFormControlType() type} of
* {@link FormControlType#SELECT_SINGLE SELECT_SINGLE} or {@link FormControlType#SELECT_MULTIPLE SELECT_MULTIPLE}.
*
* @return an iterator over the {@link HTMLElementName#OPTION OPTION} {@linkplain Element elements} contained within this control, in order of appearance.
* @throws UnsupportedOperationException if the {@linkplain #getFormControlType() type} of this control is not {@link FormControlType#SELECT_SINGLE SELECT_SINGLE} or {@link FormControlType#SELECT_MULTIPLE SELECT_MULTIPLE}.
*/
public Iterator
* This property affects how this form control is displayed if it has been {@linkplain OutputDocument#replace(FormControl) replaced}
* in an {@link OutputDocument}.
* See the documentation of the {@link FormControlOutputStyle} class for information on the available output styles.
*
* The default output style for every form control is {@link FormControlOutputStyle#NORMAL}.
*
* @return the current {@linkplain FormControlOutputStyle output style} of this form control.
* @see #setOutputStyle(FormControlOutputStyle)
*/
public FormControlOutputStyle getOutputStyle() {
return outputStyle;
}
/**
* Sets the {@linkplain FormControlOutputStyle output style} of this form control.
*
* See the {@link #getOutputStyle()} method for a full description of this property.
*
* @param outputStyle the new {@linkplain FormControlOutputStyle output style} of this form control.
*/
public void setOutputStyle(final FormControlOutputStyle outputStyle) {
this.outputStyle=outputStyle;
}
/**
* 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
* 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 {@linkplain #getElement() source element} if the control's
* display characteristics and submission values
* have not been modified.
*
* @return a map of the names and values of this form control's output attributes.
*/
public final Map
* The form control is disabled if the attribute
* "
* The return value is is logically equivalent to {@link #getAttributesMap()}
* If the argument supplied to this method is
* If the argument supplied to this method is
* See the {@link #isDisabled()} method for more information.
*
* @param disabled the new value of this property.
*/
public final void setDisabled(final boolean disabled) {
elementContainer.setBooleanAttribute(Attribute.DISABLED,disabled);
}
/**
* 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
* "
* This property is only relevant to form controls with a {@linkplain #getFormControlType() type} of
* {@link FormControlType#CHECKBOX} or {@link FormControlType#RADIO}, and throws an
* 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
* {@link #setValue(String) setValue}
* If this control is a radio button, you should use the {@link FormField#setValue(String)} method or one of the other
* higher level submission value modification methods
* to set the control to checked, as calling {@link #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 {@link #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 {@link #getAttributesMap()}
* Only predefined value controls can return a non-
* {@link FormControlType#CHECKBOX CHECKBOX} and {@link FormControlType#RADIO RADIO} controls have a guaranteed
* predefined value determined by the value of its compulsory
*
* {@link FormControlType#SUBMIT SUBMIT}, {@link FormControlType#BUTTON BUTTON} and {@link FormControlType#IMAGE IMAGE}
* controls have an optional predefined value determined by the value of its
*
* {@link FormControlType#SELECT_SINGLE} and {@link FormControlType#SELECT_MULTIPLE} controls are special cases
* because they usually contain multiple
*
* The predefined value of a control is not affected by changes to the
* submission value of the control.
*
* @return the initial value of this control if it has a {@linkplain FormControlType#hasPredefinedValue() predefined value}, or
* All objects in the returned collection are of type
* This method is most useful for
*
* The multiple predefined values of a
*
* The predefined values of a control are not affected by changes to the
* submission values of the control.
*
* @return a collection of all {@linkplain #getPredefinedValue() predefined values} in this control in order of appearance, guaranteed not
* All objects in the returned list are of type
* 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:
*
* {@link FormControlType#CHECKBOX CHECKBOX} and {@link FormControlType#RADIO RADIO} controls
* have a submission value specified by its {@linkplain #getPredefinedValue() predefined value}
* if it is {@link #isChecked() checked}, otherwise it has no submission value.
*
* {@link FormControlType#SELECT_SINGLE SELECT_SINGLE} and {@link FormControlType#SELECT_MULTIPLE SELECT_MULTIPLE} controls
* have submission values specified by the
* values of the control's
* selected
*
* Only a {@link FormControlType#SELECT_MULTIPLE SELECT_MULTIPLE} control can have more than one submission value,
* all other {@linkplain FormControlType control types} return a list containing either one value or no values.
* A {@link FormControlType#SELECT_SINGLE SELECT_SINGLE} control only returns multiple submission values
* if it illegally contains multiple selected options in the source document.
*
* {@link FormControlType#SUBMIT SUBMIT}, {@link FormControlType#BUTTON BUTTON}, and {@link 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
* {@linkplain FormControlType#isSubmit() 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 {@link OutputDocument} using the various
* submission value modification methods, namely:
* The values returned by this method reflect any changes made using the submission value modification methods,
* in contrast to methods found in the {@link Attributes} and {@link Attribute} classes, which always reflect the source document.
*
* @return a list of the control's submission values in order of appearance, guaranteed not
* This is equivalent to {@link #setValue(String) setValue(null)}.
*
* NOTE: The {@link FormFields} and {@link FormField} classes provide a more appropriate abstraction level for the modification of form control submission values.
*
* @see FormFields#clearValues()
* @see FormField#clearValues()
*/
public final void clearValues() {
setValue(null);
}
/**
* Sets the control's submission value *.
*
* * NOTE: The {@link FormFields} and {@link FormField} classes provide a more appropriate abstraction level for the modification of form control submission values.
* Consider using the {@link 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
* For predefined value controls,
* calling this method does not affect the control's
* {@linkplain #getPredefinedValues() predefined values}, but instead determines whether the control (or its options) become
*
* {@link FormControlType#CHECKBOX CHECKBOX} and {@link FormControlType#RADIO RADIO} controls become {@link #isChecked() checked}
* and the method returns
* {@link FormControlType#SELECT_SINGLE SELECT_SINGLE} and {@link 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.
*
* {@link FormControlType#SUBMIT SUBMIT}, {@link FormControlType#BUTTON BUTTON}, and {@link FormControlType#IMAGE IMAGE}
* controls never have a submission value, so calling this method has no effect and
* always returns
* * NOTE: The {@link FormFields} and {@link FormField} classes provide a more appropriate abstraction level for the modification of form control submission values.
* Consider using the {@link FormFields#addValue(String fieldName, String value)} method instead.
*
* This is almost equivalent to {@link #setValue(String)}, with only the following differences:
*
* {@link FormControlType#CHECKBOX CHECKBOX} controls retain their existing submission value
* instead of becoming unchecked if the specified value does not match the control's {@linkplain #getPredefinedValue() predefined value}.
*
* {@link FormControlType#SELECT_MULTIPLE SELECT_MULTIPLE} controls retain their existing
* submission values, meaning that the control's
* FormControl instances are obtained using the {@link Element#getFormControl()} method or are created automatically
* with the creation of a {@link FormFields} object via the {@link Segment#getFormFields()} method.
*
* @see FormControlType
* @see FormFields
* @see FormField
*/
public abstract class FormControl extends Segment {
FormControlType formControlType;
String name;
ElementContainer elementContainer;
FormControlOutputStyle outputStyle=FormControlOutputStyle.NORMAL;
private static final String CHECKBOX_NULL_DEFAULT_VALUE="on";
private static Comparatorname {@linkplain Attribute attribute} of the
* {@linkplain #getElement() form control's element}, not the {@linkplain Element#getName() name of the element} itself.
* .{@link Config.CompatibilityMode#isFormFieldNameCaseInsensitive() FormFieldNameCaseInsensitive} property.
*
* @return the name of the control.
*/
public final String getName() {
return name;
}
/**
* Returns the {@linkplain Element element} representing this form control in the source document.
* 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 {@linkplain Attribute#hasValue() has no value}.
* disabled"
* is present in its output element.
* .containsKey("disabled"),
* but using this property may be more efficient in some circumstances.
*
* @return true if this form control is disabled, otherwise false.
*/
public final boolean isDisabled() {
return elementContainer.getBooleanAttribute(Attribute.DISABLED);
}
/**
* Sets whether this form control is disabled.
* 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.
* false, the attribute is removed from the output element.
* checked"
* is present in its output element.
* UnsupportedOperationException
* for other control types.
* ({@link #getName()}), and set it to unchecked by calling
* {@link #clearValues()}.
* .containsKey("checked"),
* but using this property may be more efficient in some circumstances.
*
* @return true if this form control is checked, otherwise false.
* @throws UnsupportedOperationException if the {@linkplain #getFormControlType() type} of this control is not {@link FormControlType#CHECKBOX} or {@link FormControlType#RADIO}.
*/
public boolean isChecked() {
throw new UnsupportedOperationException("This property is only relevant for CHECKBOX and RADIO controls");
}
/**
* Returns the initial value of this control if it has a {@linkplain FormControlType#hasPredefinedValue() predefined value}.
* null result.
* All other control types return null.
* 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.
* value
* attribute. This value is
* successful
* only in the control used to submit the form.
* OPTION
* elements, each with its own predefined value.
* In this case the {@link #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.
* null if none.
*/
public String getPredefinedValue() {
return elementContainer.predefinedValue;
}
/**
* Returns a collection of all {@linkplain #getPredefinedValue() predefined values} in this control in order of appearance.
* String, with no null entries.
* 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
* {@link #getPredefinedValue()} method, so for efficiency it is recommended to use the
* {@link #getPredefinedValue()} method instead.
* 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
* {@linkplain CharacterReference#decode(CharSequence) decoded} {@linkplain Element#getContent() content}
* text with {@linkplain CharacterReference#decodeCollapseWhiteSpace(CharSequence) collapsed white space}.
* null.
* @see FormField#getPredefinedValues()
*/
public CollectionString, with no null entries.
* OPTION elements.
*
* {@link FormField#setValue(String)}
* {@link FormField#addValue(String)}
* {@link FormField#setValues(Collection)}
* {@link FormField#clearValues()}
* {@link FormFields#setValue(String fieldName, String value)}
* {@link FormFields#addValue(String fieldName, String value)}
* {@link FormFields#setDataSet(Map)}
* {@link FormFields#clearValues()}
* {@link #setValue(String) FormControl.setValue(String)}
* {@link #addValue(String) FormControl.addValue(String)}
* {@link #clearValues() FormControl.clearValues()}
* null.
* @see #getPredefinedValues()
*/
public Listtrue.
* checked or
* selected
* as detailed below:
* 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 {@linkplain #getName() 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 {@link FormField#setValue(String)} method avoids such problems and its use is recommended over this method.
* false.
*
* @param value the new submission value of this control, or null to clear the control of all submission values.
* @return true if the control accepts the value, otherwise false.
* @see FormFields#setValue(String fieldName, String value)
*/
public abstract boolean setValue(String value);
/**
* Adds the specified value to this control's submission values *.
* OPTION
* elements whose {@linkplain #getPredefinedValues() 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.
*
* @param value the value to add to this control's submission values, must not be null.
* @return true if the control accepts the value, otherwise false.
* @see FormFields#addValue(String fieldName, String value)
*/
public boolean addValue(final String value) {
return setValue(value);
}
abstract void addValuesTo(Collection