edu.utexas.its.eis.tools.qwicap.servlet
Class Form

java.lang.Object
  edu.utexas.its.eis.tools.qwicap.servlet.Form

public final class Form
extends Object

The Form class provides a set of high-level utility methods for operating on the controls within an XHTML "form" element.

If it looks like this class is implemented a lot like a large mass of procedural code, rather than as an elegant hierarchy of classes representing the various types of form controls, you're right. And it's not by accident. The elegant hierarchy of classes would be conceptually cleaner, probably easier to support, and more fun to write, but it would also introduce assumptions into the code that the Form class does not, because building a set of control objects to represent the contents of a "form" element creates a representation of the state of the form that is independent of the underlying markup. Which means that the representation can become out-of-synch with the markup, if, for instance, the programmer prefers to do some manipulation of form contents by directly using the templating engine, e.g. MyMarkup.get("select[name='foo'] option[name='bar']").delete(), or if the representation is retained across prompt invocations and Qwicap updates the form markup by embedding user-supplied values, etc.

In contrast, the Form class maintains no state information about the form (other than the assumption that the form still exists), so it can't become out-of-synch with the markup, programmers don't receive rude surprises (so, no need for extra documentation, notes and warnings), and they remain free to choose the method of manipulating the form markup that works best for them in any given situation (doing it directly, going through the Form class, or both). Put simply, the advantage of the Form class as it is presently constituted is that it is too dumb to die.

Finding, Examining, Transforming, and Deleting Controls:

• deleteControl(Match, Object) [static]
• deleteControl(String, Object)
• getControl(String, Object)
• getControlByIndex(String, int)
• getControlByIndexAndValue(String, int, Object)
• getControls(String, Object)
• getControlsByName(String)
• getControlName(Match) [static]
• getSubmitControls()
• convertSubmitButtonsToInputs()
• convertSubmitInputsToButtons()

Control Value Related Methods:

• addToControlValue(Match, Object) [static]
• addToControlValue(String, Object)
• clearControlValue(Match) [static]
• clearControlValue(String)
• clearControlValues(boolean)
• getControlValue(Match) [static]
• getControlValue(String)
• getControlValues(Match) [static]
• getControlValues(Match, boolean, boolean, boolean) [static]
• getControlValues(String)
• setControlValue(Match, Object) [static]
• setControlValue(String, Object)
• setControlValues(Object...)

Control State Related Methods:

• enableControl(Match) [static]
• enableControl(String)
• enableControl(Match, Object) [static]
• enableControl(String, Object)
• enableControls(String...)
• enableAllControls(boolean)
• disableControl(Match) [static]
• disableControl(String)
• disableControl(Match, Object) [static]
• disableControl(String, Object)
• disableControls(String...)
• disableAllControls(boolean)
• isControlEnabled(Match) [static]
• setControlEnable(Match, boolean) [static]
• setControlEnable(String, boolean)

Control Group (Checkbox, Radio, Select) Related Methods:

• addChoice(boolean, String, Object, boolean, String)
• addFirstChoice(String, Object, boolean, String)
• addLastChoice(String, Object, boolean, String)
• addToControlValue(Match, Object) [static]
• addToControlValue(String, Object)
• createChoice(String, String, Object, boolean, String) [static]
• deleteChoices(String)

Form Data Set Methods:

• getAction()
• getActionURL()
• getCharacterSet()
• setCharacterSet(java.lang.String)
• getCharacterSets()
• getDataSet()
• getDataSet(boolean)
• setDataSet(FormDataSet)
• getMethod()

Form Utility Methods:

• convertSubmitButtonsToInputs()
• convertSubmitInputsToButtons()
• get(String)
• get(CSSPatterns)
• getMatch()
• toResults()

Debugging Methods:

• getControlsTable()

Author:

Chris W. Johnson

Constructor Summary

Form(Match TheForm)
Creates a Form object for operating on the specified form.

Form(MutableMarkup ThePage, FormDataSet DataSet)
Creates a Form object for manipulating the form that produced the supplied FormDataSet.

Method Summary

Results	addChoice(boolean InsertBefore, String ControlName, Object ControlValue, boolean Selected, String Label) Adds a choice to a pre-existing "select" control, group of radio buttons, or checkboxes.
Results	addFirstChoice(String ControlName, Object ControlValue, boolean Selected, String Label) Adds a new first choice to a pre-existing "select" control, group of radio buttons, or checkboxes.
Results	addLastChoice(String ControlName, Object ControlValue, boolean Selected, String Label) Adds a new last choice to a pre-existing "select" control, group of radio buttons, or checkboxes.
static Match	addToControlValue(Match Control, Object ControlValue) Adds to the value of a form control.
Form	addToControlValue(String ControlName, Object ControlValue) Adds to the value of a form control.
static void	clearControlValue(Match Control) Clears the value of the supplied from control, even if it is of a type whose value cannot be altered by the user.
Form	clearControlValue(String ControlName) Removes the value of the specified form control.
Form	clearControlValues(boolean AlsoClearDisabledControls) Removes the values from the controls in this form whose values can be altered by the user.
int	convertSubmitButtonsToInputs() Converts all "button" controls of type "submit" to "input" controls of type "submit", in order to work around a hideous bug in Internet Explorer (Windows and Mac OS).
int	convertSubmitInputsToButtons() Converts all "input" controls of type "submit" that were "button" controls before convertSubmitButtonsToInputs() was invoked back into "button" controls of type "submit".
static ImmutableMarkup	createChoice(String Type, String ControlName, Object ControlValue, boolean Selected, String Label) Creates the markup for a new choice ("option", "radio", or "checkbox").
Form	deleteChoices(String ControlName) Deletes all choices associated with the control of the specified name.
static void	deleteControl(Match Control, Object ControlValue) Deletes the specified control, if its value matches the specified value, or the specified value is null.
Form	deleteControl(String ControlName, Object ControlValue) Deletes the specified control, if its value matches the specified value, or the specified value is null.
Form	disableAllControls(boolean IncludesSubmitButtons) Disables all controls in this form, optionally including even the "submit" button(s).
static Match	disableControl(Match Control) Disables the specified control.
static Match	disableControl(Match Control, Object ControlValue) Disables the specified control, if its value matches the specified value, or the specified value is null.
Form	disableControl(String ControlName) Disables the named control.
Form	disableControl(String ControlName, Object ControlValue) Disables the named control, if its value matches the specified value, or the specified value is null.
Form	disableControls(String... ControlNames) Disables multiple form controls as identified by their names.
Form	enableAllControls(boolean IncludesSubmitButtons) Enables all controls in this form, optionally including even the "submit" button(s).
static Match	enableControl(Match Control) Enables the specified control.
static Match	enableControl(Match Control, Object ControlValue) Enables the specified control, if its value matches the specified value, or the specified value is null.
Form	enableControl(String ControlName) Enables a form control identified by the name of the parameter that the control will submit in the form data set.
Form	enableControl(String ControlName, Object ControlValue) Enables the named control, if its value matches the specified value, or the specified value is null.
Form	enableControls(String... ControlNames) Enables multiple form controls as identified by their names.
Results	get(CSSPatterns CSSPatterns) Searches this "form" element, and its children, for matches with the specified CSS2 pattern(s).
Results	get(String CSSPatterns) Searches this "form" element, and its children, for matches with the specified CSS2 pattern(s).
String	getAction() Returns the value of the form's "action" attribute, or null if there is no such attribute.
URL	getActionURL() Attempts to construct a fully-qualified action URL from the value of the form's "action" attribute, the URL of the page in which this form occurs, and any "base" element that the page may contain.
String	getCharacterSet() Returns the first character set name from the list of character set names in the "form" element's "accept-charset" attribute.
String[]	getCharacterSets() Returns the name of the character sets in which this form's data set may be encoded, based on the list in the "form" element's "accept-charset" attribute.
FormControlInfo	getControl(String ControlName, Object ControlValue) Returns a FormControlInfo object describing the specific form control that supplied, or could have supplied, a particular name/value pair in a form data set.
FormControlInfo	getControlByIndex(String ControlName, int ControlIndex) Returns a FormControlInfo object describing the form control with the specified name (which is understood to be shared with other controls in the form), and index number.
FormControlInfo	getControlByIndexAndValue(String ControlName, int ControlIndex, Object ControlValue) Returns a FormControlInfo object describing the form control with the specified name (which is understood to be shared with other controls in the form), index number, and value.
static String	getControlName(Match Control) Returns the name of the specified control, or null if the control has no name.
FormControlInfo[]	getControls(String ControlName, Object ControlValue) Returns an array of FormControlValue objects describing the form controls that supplied, or could have supplied, a particular name/value pair in a form data set.
Results	getControlsByName(String ControlName) Finds the form controls having the specified name.
edu.utexas.its.eis.tools.table.MutableTable	getControlsTable() A debugging method that produces a table of all controls in this form, the labels associated with them, and the value(s) of each control.
static String	getControlValue(Match Control) Returns the value of the specified control as a String.
String	getControlValue(String ControlName) Returns the current value of the named control as a String.
static String[]	getControlValues(Match Control) Returns the value of the specified control as a String.
static String[]	getControlValues(Match Control, boolean SuccessfulControlsOnly, boolean IncludeSubmitControls, boolean IncludeMisnomerValues) Returns the value(s) of the specified control, optionally limiting the values to those supplied by the controls that will be successful by default.
String[]	getControlValues(String ControlName) Returns the current value(s) of the named control as a String array.
FormDataSet	getDataSet() Get the values of all of the enabled, successful controls in this form.
FormDataSet	getDataSet(boolean IncludeSolitarySubmitControl) Get the values of all of the enabled, successful controls in this form.
Match	getMatch() Returns the Match object that uniquely identifies the "form" element represented by this Form object.
String	getMethod() Returns the value of the form's "method" attribute ("get" or "post"), or null if there is no such attribute.
FormControlInfo[]	getSubmitControls() Returns an array of FormControlValue objects describing the "submit" controls in this form.
static boolean	isControlEnabled(Match Control) Returns true if the specified control is enabled, false otherwise.
Form	printAllLabels() Deprecated. Use getControlsTable() instead.
Form	setCharacterSet(String CharacterSet) Sets the character set in which the data set created by this form will be encoded.
static Match	setControlEnable(Match Control, boolean Enable) Enables or disables the specified control according to a boolean parameter.
Form	setControlEnable(String ControlName, boolean Enable) Enables or disables the named control according to a boolean parameter.
static Match	setControlValue(Match Control, Object ControlValue) Sets the value of a form control, identified by name.
Form	setControlValue(String ControlName, Object ControlValue) Sets the value of a form control, identified by name.
Form	setControlValues(Object... NameValuePairs) Sets the value of multiple form controls, as identified by the names of the parameters the controls will submit.
Form	setDataSet(FormDataSet DataSet) Takes the values of the supplied form data set, and writes them into this form, where applicable.
Results	toResults() Creates Results object containing a reference to this "form" element.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Form

public Form(MutableMarkup ThePage,
            FormDataSet DataSet)
     throws FormNotFoundException

Creates a Form object for manipulating the form that produced the supplied FormDataSet.

Parameters:

ThePage - The page of markup in which the form is to be found.

DataSet - The FormDataSet that was produced by one of the forms on this page.

Throws:

FormNotFoundException - If the markup of this page does not contain a form that could have produced the supplied FormDataSet.

Form

public Form(Match TheForm)
     throws FormNotFoundException

Creates a Form object for operating on the specified form.

Parameters:

TheForm - The relevant "form" tag within that markup.

Throws:

FormNotFoundException - If the TheForm does not refer to a "form" element.

Method Detail

toString

public String toString()

Overrides:

toString in class Object

getMatch

public Match getMatch()

Returns the Match object that uniquely identifies the "form" element represented by this Form object.

Returns:

The Match object that uniquely identifies the "form" element represented by this Form object.

getAction

public String getAction()

Returns the value of the form's "action" attribute, or null if there is no such attribute.

Returns:

The value of the form's "action" attribute, or null if there is no such attribute.

getActionURL

public URL getActionURL()
                 throws MalformedURLException

Attempts to construct a fully-qualified action URL from the value of the form's "action" attribute, the URL of the page in which this form occurs, and any "base" element that the page may contain.

Returns:

This "form" element's action URL.

Throws:

MalformedURLException - If a potentially valid action URL could not be constructed.

getMethod

public String getMethod()

Returns the value of the form's "method" attribute ("get" or "post"), or null if there is no such attribute.

Returns:

The value of the form's "method" attribute, or null if there is no such attribute.

setCharacterSet

public Form setCharacterSet(String CharacterSet)
                     throws TagException

Sets the character set in which the data set created by this form will be encoded.

Parameters:

CharacterSet - The official IANA name of the character set in which the form's data set will be encoded.

Returns:

This Form object.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

getCharacterSet

public String getCharacterSet()

Returns the first character set name from the list of character set names in the "form" element's "accept-charset" attribute. If that attribute is missing or empty, the character set of the enclosing document is returned.

Returns:

The official IANA name of the character set in which the form's data set will be encoded.

See Also:

getCharacterSets()

getCharacterSets

public String[] getCharacterSets()

Returns the name of the character sets in which this form's data set may be encoded, based on the list in the "form" element's "accept-charset" attribute. If that attribute is missing or empty, the character set of the enclosing document is returned.

Returns:

The official IANA name of the character set in which the form's data set will be encoded.

get

public Results get(String CSSPatterns)

Searches this "form" element, and its children, for matches with the specified CSS2 pattern(s). If there are no matches, the Results object returned is empty.

Parameters:

CSSPatterns - One or more CSS2 patterns to be applied to this element and its children.

Returns:

A Results object containing a list of elements that matched the specified pattern(s), if any.

get

public Results get(CSSPatterns CSSPatterns)

Searches this "form" element, and its children, for matches with the specified CSS2 pattern(s). If there are no matches, the Results object returned is empty.

Parameters:

CSSPatterns - One or more CSS2 patterns to be applied to this element and its children.

Returns:

A Results object containing a list of elements that matched the specified pattern(s), if any.

toResults

public Results toResults()

Creates Results object containing a reference to this "form" element.

Returns:

A Results object containing a reference to this "form" element.

deleteChoices

public Form deleteChoices(String ControlName)
                   throws TagException

Deletes all choices associated with the control of the specified name. Note that for "input" controls of type "radio" and "checkbox" this call is not reversible, i.e. you can't invoke addChoice to build-up a new list of choices to replace the ones you've deleted, because once an array of radio or checkbox buttons has been deleted, there's no trace of them left in the markup. That's because the way HTML forms were designed, radio and checkbox controls have no parent control to hold their place, unlike "select" controls which are parents to all of the "option" controls that represent the choices they offer. So, don't use deleteChoices on "input" controls of types "radio" or "checkbox" unless you want to be rid of them, but feel free to use it on "select" controls.

Parameters:

ControlName - The name of the control whose associated choices should be deleted.

Returns:

This Form object.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

addFirstChoice

public Results addFirstChoice(String ControlName,
                              Object ControlValue,
                              boolean Selected,
                              String Label)
                       throws TagException

Adds a new first choice to a pre-existing "select" control, group of radio buttons, or checkboxes. If there is more than one select in this form with the specified name, the choice is added to all of them. We would do the same for groups of radio buttons and checkboxes, except that those elements lack an enclosing element, so there's no dependable way to identify distinct groups of them.

Parameters:

ControlName - Name of the control.

ControlValue - Value of this choice.

Selected - true if the choice is selected by default.

Label - Human-interface label for the new choice.

Returns:

A new Results object that references the new choice control.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

See Also:

addChoice(boolean, String, Object, boolean, String), addLastChoice(String, Object, boolean, String)

addLastChoice

public Results addLastChoice(String ControlName,
                             Object ControlValue,
                             boolean Selected,
                             String Label)
                      throws TagException

Adds a new last choice to a pre-existing "select" control, group of radio buttons, or checkboxes. If there is more than one select in this form with the specified name, the choice is added to all of them. We would do the same for groups of radio buttons and checkboxes, except that those elements lack an enclosing element, so there's no dependable way to identify distinct groups of them.

Parameters:

ControlName - Name of the control.

ControlValue - Value of this choice.

Selected - true if the choice is selected by default.

Label - Human-interface label for the new choice.

Returns:

A new Results object that references the new choice control.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

See Also:

addFirstChoice(String, Object, boolean, String), addChoice(boolean, String, Object, boolean, String)

addChoice

public Results addChoice(boolean InsertBefore,
                         String ControlName,
                         Object ControlValue,
                         boolean Selected,
                         String Label)
                  throws TagException

Adds a choice to a pre-existing "select" control, group of radio buttons, or checkboxes. If there is more than one select in this form with the specified name, the choice is added to all of them. We would do the same for groups of radio buttons and checkboxes, except that those elements lack an enclosing element, so there's no dependable way to identify distinct groups of them.

Parameters:

InsertBefore - true if the new choice should be inserted before the existing choices, or false if the new choice should be inserted after the existing choices.

ControlName - Name of the control.

ControlValue - Value of this choice.

Selected - true if the choice is selected by default.

Label - Human-interface label for the new choice.

Returns:

A new Results object that references the new choice control.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

See Also:

addFirstChoice(String, Object, boolean, String), addLastChoice(String, Object, boolean, String)

createChoice

public static ImmutableMarkup createChoice(String Type,
                                           String ControlName,
                                           Object ControlValue,
                                           boolean Selected,
                                           String Label)
                                    throws TagException

Creates the markup for a new choice ("option", "radio", or "checkbox").

Parameters:

Type - The type of control to be created: "option", "radio", or "checkbox".

ControlName - Name of the control.

ControlValue - Value of this choice.

Selected - true if the choice is selected by default.

Label - Human-interface label for the new choice.

Returns:

An ImmutableMarkup object containing the markup for the new choice.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

printAllLabels

@Deprecated
public Form printAllLabels()

Deprecated. Use getControlsTable() instead.

A debugging function that prints out a list of all controls in this form, and the labels associated with them.

Returns:

This Form object.

getControlsTable

public edu.utexas.its.eis.tools.table.MutableTable getControlsTable()

A debugging method that produces a table of all controls in this form, the labels associated with them, and the value(s) of each control. The controls are listed in the same order in which they occur in the markup.

Returns:

A MutableTable object listing all of the controls in this form, and the labels associated with them.

getControlsByName

public Results getControlsByName(String ControlName)

Finds the form controls having the specified name. The returned controls may be of type "input", "select", "button", or "textarea". They will not be of type "option", because those are always subsumed by a "select" control.

Parameters:

ControlName - The name of the control to be searched-for.

Returns:

A list of zero or more form controls having the specified name.

getControlByIndex

public FormControlInfo getControlByIndex(String ControlName,
                                         int ControlIndex)

Returns a FormControlInfo object describing the form control with the specified name (which is understood to be shared with other controls in the form), and index number. In other words, it gets the Nth control of the specified name from the form. The controls are considered in the order in which they occur in the markup, with index 0 considered to be the first control.

Parameters:

ControlName - Name of the parameter whose originating form control should be found.

ControlIndex - Index number of the originating form control.

Returns:

A FormControlInfo instance describing the relevant form control, otherwise null.

getControlByIndexAndValue

public FormControlInfo getControlByIndexAndValue(String ControlName,
                                                 int ControlIndex,
                                                 Object ControlValue)

Returns a FormControlInfo object describing the form control with the specified name (which is understood to be shared with other controls in the form), index number, and value. In other words, it gets the Nth control of the specified name from the form, provided that the supplied value matches it, or some part of it. The controls are considered in the order in which they occur in the markup, with index 0 considered to be the first control.

Parameters:

ControlName - Name of the parameter whose originating form control should be found.

ControlIndex - The index number of the originating form control.

ControlValue - The value whose originating form control should be found.

Returns:

A FormControlInfo instance describing the relevant form control, otherwise null.

getControl

public FormControlInfo getControl(String ControlName,
                                  Object ControlValue)

Returns a FormControlInfo object describing the specific form control that supplied, or could have supplied, a particular name/value pair in a form data set. Since groups of radio buttons and checkboxes consist of sets of controls that all submit name/value pairs with the same name, this function has to match the value as well in order to ensure that it returns the control specifically responsible for the value.

Note that a specific form control can't necessarily be identified from a control name and value, because some controls (input for text and passwords, for example) have their values supplied client-side by the user, in other words, they can't be identified because the value is not in the document markup. In such cases, the first (and presumably the only) form control that supplies a parameter of the specified name is returned. This is also the behavior when, for whatever reason, the supplied control value is null.

Parameters:

ControlName - Name of the parameter whose originating form control should be found.

ControlValue - Value of the parameter whose originating form control should be found. Can be null; see method description.

Returns:

A FormControlInfo instance describing the relevant form control, otherwise null.

getControls

public FormControlInfo[] getControls(String ControlName,
                                     Object ControlValue)

Returns an array of FormControlValue objects describing the form controls that supplied, or could have supplied, a particular name/value pair in a form data set. Since groups of radio buttons and checkboxes consist of sets of controls that all submit values of the same name, this function has to match the value to ensure that it returns the control specifically responsible for the value.

Note that a specific form control can't necessarily be identified from a control name and value, because some controls (input for text and passwords, for example) have their values supplied client-side by the user, in other words, they can't be identified because the value is not in the document markup. In such cases, all the form controls of the specified name are returned. This is also the behavior when, for whatever reason, the supplied control value is null.

Parameters:

ControlName - Name of the control.

ControlValue - Value of the control. Can be null; see method description.

Returns:

An array of FormControlInfo instances describing the relevant form controls, or an empty array if no relevant form controls could be found.

getSubmitControls

public FormControlInfo[] getSubmitControls()

Returns an array of FormControlValue objects describing the "submit" controls in this form.

Returns:

Descriptions of the "submit" controls in this form.

addToControlValue

public Form addToControlValue(String ControlName,
                              Object ControlValue)
                       throws TagException

Adds to the value of a form control. In the case of most single-value controls, the new value is appended to the old value. In the case of a multi-value "select" control, an "option" tag with the specified value is located within it, and that option is selected. In the case of a single-value "select" control, the existing value (if any) is cleared, then an "option" tag with the specified value is located within it, and that option is selected (this is no different from calling setControlValue(String, Object), but it's a single-value control, so we have no choice). In the case of "input" controls of type "checkbox", the control with the specified value is located and selected ("checked"). In the case of "input" controls of type "radio", the control with the specified value is located and selected ("checked"), and all of the other controls are de-selected (their "checked" attributes are deleted). Where those radio buttons are concerned, this method is no different from calling setControlValue(String, Object), but a group of radio buttons can represent only one value, so we have no choice.

Parameters:

ControlName - The name of a form control of type "input", "select", "textarea" or "button".

ControlValue - Value of the form control.

Returns:

This Form object.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

addToControlValue

public static Match addToControlValue(Match Control,
                                      Object ControlValue)
                               throws TagException

Adds to the value of a form control. In the case of most single-value controls, the new value is appended to the old value. In the case of a multi-value "select" control, an "option" tag with the specified value is located within it, and that option is selected. In the case of a single-value "select" control, the existing value (if any) is cleared, then an "option" tag with the specified value is located within it, and that option is selected (this is no different from calling setControlValue(Match, Object), but it's a single-value control, so we have no choice). In the case of an "input" control of type "checkbox", the control is selected ("checked") if its value matches the specified value, and it is left untouched otherwise. In the case of an "input" control of type "radio", the control is selected ("checked") if its value matches the specified value, and it is unselected (its "checked" attribute is deleted) otherwise.

Parameters:

Control - A Match instance that refers to an "input", "select", "textarea" or "button" control.

ControlValue - Value of the form control.

Returns:

This Form object.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

setControlValue

public Form setControlValue(String ControlName,
                            Object ControlValue)
                     throws TagException

Sets the value of a form control, identified by name. In the case of checkboxes, radio buttons, and "select" controls, the value is used in addition to the name in order to identify the relevant form control; when a form control with a matching name and value is found, a "checked" or "selected" attribute is added, as appropriate. Note that you cannot repeatedly invoke this method in order to select more than one checkbox, or option, in a multiple selection control, because it removes the "checked" or "selected" attributes from all controls with the specified name before it checks/selects the control with the matching value. However, you may make multiple selections with a single setControlValue invocation by passing an array of values to be selected as the ControlValue parameter. The array elements may be of any type; the toString methods of the non-null elements will be invoked, and the controls whose values match the returned Strings (if any) will be checked/selected. Alternately, if you prefer to set the values of multi-value controls by using multiple method invocations, start by invoking clearControlValue(String) to remove all pre-existing checks/selects, then use invocations of addToControlValue(String, Object) to check/select as many items as necessary. For single-value controls, this setControlValue method is always appropriate.

Parameters:

ControlName - Name of the form control.

ControlValue - Value of the form control. If null, the value of the control is cleared with the clearControlValue(Match) method. If the value is an array, and the control supports multiple values, the control is given each of the values in the array. The array may be of any type; its elements are converted to strings using their toString methods.

Returns:

A reference to this Form object.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

See Also:

addToControlValue(String, Object), clearControlValue(String)

setControlValue

public static Match setControlValue(Match Control,
                                    Object ControlValue)
                             throws TagException

Sets the value of a form control, identified by name. In the case of checkboxes, radio buttons, and "select" controls, the value is used in addition to the name in order to identify the relevant form control; when a form control with a matching name and value is found, a "checked" or "selected" attribute is added, as appropriate. Note that you cannot repeatedly invoke this method in order to select more than one checkbox, or option, in a multiple selection control, because it removes the "checked" or "selected" attributes from all controls with the specified name before it checks/selects the control with the matching value. However, you may make multiple selections with a single setControlValue invocation by passing an array of values to be selected as the ControlValue parameter. The array elements may be of any type; the toString methods of the non-null elements will be invoked, and the controls whose values match the returned Strings (if any) will be checked/selected. Alternately, if you prefer to set the values of multi-value controls by using multiple method invocations, start by invoking clearControlValue(String) to remove all pre-existing checks/selects, then use invocations of addToControlValue(String, Object) to check/select as many items as necessary. For single-value controls, this setControlValue method is always appropriate.

Parameters:

Control - A Match object corresponding to a tag of type "input", "select", "textarea", or "button".

ControlValue - Value of the form control. If null, the value of the control is cleared with the clearControlValue(Match) method. If the value is an array, and the control supports multiple values, the control is given each of the values in the array. The array may be of any type; its elements are converted to strings using their toString methods.

Returns:

A reference to this Form object.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

See Also:

addToControlValue(String, Object), clearControlValue(String)

setControlValues

public Form setControlValues(Object... NameValuePairs)
                      throws TagException

Sets the value of multiple form controls, as identified by the names of the parameters the controls will submit. In the case of checkboxes, radio buttons, and "select" controls, the parameter value is used in addition to the name to identify the relevant form control; when a form control with a matching name and value is found, a "checked" or "selected" attribute is added, as appropriate. Note that this method does not support selecting more than one checkbox, or option, in a multiple selection control, because it removes the "checked" or "selected" attributes from all controls of the specified name before it checks/selects the control with the matching value. Instead, use clearControlValue(String) to remove all pre-existing checks/selects, then use invocations of addToControlValue(String, Object) to check/select as many items as necessary. This setControlValues method is appropriate for all other form controls, including radio buttons and single-selection lists.

Parameters:

NameValuePairs - An array composed of control name/value pairs such that the even-numbered elements are the names of controls, and the odd-numbered elements are the values, e.g. "name1", "value1", "name2", "value2", "name3", "value3". The values may be of any type (they will ultimately be converted to Strings using their toString methods). If a value is null, the value of the control is cleared with the clearControlValue(Match) method. If a value is an array, the control is given all the values specified by the array. (The array may be of any type; it's elements are converted to strings using their toString methods.) The control names in the even-numbered elements of this parameter will ordinarily be Strings, but can actually be of any type (as with values, their toString methods are invoked).

Returns:

This Form object.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

enableAllControls

public Form enableAllControls(boolean IncludesSubmitButtons)
                       throws TagException

Enables all controls in this form, optionally including even the "submit" button(s).

Parameters:

IncludesSubmitButtons - true if all submit buttons in this form should also be enabled, false otherwise.

Returns:

This Form object.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

disableAllControls

public Form disableAllControls(boolean IncludesSubmitButtons)
                        throws TagException

Disables all controls in this form, optionally including even the "submit" button(s).

Parameters:

IncludesSubmitButtons - true if all submit buttons in this form should also be disabled, false otherwise.

Returns:

This Form object.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

setControlEnable

public Form setControlEnable(String ControlName,
                             boolean Enable)
                      throws TagException

Enables or disables the named control according to a boolean parameter.

Parameters:

ControlName - Name of the form control.

Enable - true if the control should be enabled, false if it should be disabled.

Returns:

This Form object.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

See Also:

enableControl(String), disableControl(String)

setControlEnable

public static Match setControlEnable(Match Control,
                                     boolean Enable)
                              throws TagException

Enables or disables the specified control according to a boolean parameter.

Parameters:

Control - A Match object corresponding to a tag of type "input", "select", "textarea", or "button".

Enable - true if the control should be enabled, false if it should be disabled.

Returns:

The specified control.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

enableControl

public Form enableControl(String ControlName)
                   throws TagException

Enables a form control identified by the name of the parameter that the control will submit in the form data set. In the case of multiple selection controls (checkboxes, radio buttons, and "select" controls) all controls are enabled. (To enable individual selections use the enableControl(String, Object) method.) Note that "enabling" means nothing more than deleting the "disabled" attribute from applicable form controls.

Parameters:

ControlName - Name of the form control.

Returns:

This Form object.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

See Also:

enableControl(String, Object), Forms in HTML Documents, sec. 17.12.1, Disabled controls

enableControls

public Form enableControls(String... ControlNames)
                    throws TagException

Enables multiple form controls as identified by their names. In the case of multiple selection controls (checkboxes, radio buttons, and "select" controls) all selections in the controls are ensabled. (To ensable individual selections use the enableControl(String, Object) method.) Note that "enabling" means nothing more than deleting the "disabled" attribute from applicable form controls.

Parameters:

ControlNames - The names of the form controls to enable.

Returns:

This Form object.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

See Also:

enableControl(String), Forms in HTML Documents, sec. 17.12.1, Disabled controls

enableControl

public Form enableControl(String ControlName,
                          Object ControlValue)
                   throws TagException

Enables the named control, if its value matches the specified value, or the specified value is null. In the case of checkboxes, radio buttons, and "select" controls, the parameter value is used in addition to the name to identify the relevant form control. In all other cases the value may be omitted. (Note that "enabling" means nothing more than removing the "disabled" attribute from applicable form controls, if present.)

Parameters:

ControlName - Name of the form control.

ControlValue - Value of the form control, or null. The value is only needed when enabling specific items in multiple selection controls (checkboxes, radio buttons, and "select" controls). When dealing with those controls, passing null in this parameter causes all selections in the group to be enabled.

Returns:

This Form object.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

See Also:

Forms in HTML Documents, sec. 17.12.1, Disabled controls

enableControl

public static Match enableControl(Match Control,
                                  Object ControlValue)
                           throws TagException

Enables the specified control, if its value matches the specified value, or the specified value is null.

Parameters:

Control - A Match object corresponding to a tag of type "input", "select", "textarea", or "button".

ControlValue - The value the control must have in order to be enabled, or null if it should be enabled regardless of its value.

Returns:

The specified control.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

See Also:

Forms in HTML Documents, sec. 17.12.1, Disabled controls

disableControl

public Form disableControl(String ControlName)
                    throws TagException

Disables the named control. In the case of multiple selection controls (checkboxes, radio buttons, and "select" controls) all selections in the controls are disabled. (To disable individual selections use the disableControl(String, Object) method.) Note that "disabling" means nothing more than adding the "disabled" attribute to applicable form controls.

Parameters:

ControlName - Name of the form control to disable.

Returns:

This Form object.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

See Also:

disableControl(String, Object), Forms in HTML Documents, sec. 17.12.1, Disabled controls

disableControls

public Form disableControls(String... ControlNames)
                     throws TagException

Disables multiple form controls as identified by their names. In the case of multiple selection controls (checkboxes, radio buttons, and "select" controls) all selections in the controls are disabled. (To disable individual selections use the disableControl(String, Object) method.) Note that "disabling" means nothing more than adding the "disabled" attribute to applicable form controls.

Parameters:

ControlNames - The names of the form controls to disable.

Returns:

This Form object.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

See Also:

disableControl(String), Forms in HTML Documents, sec. 17.12.1, Disabled controls

disableControl

public Form disableControl(String ControlName,
                           Object ControlValue)
                    throws TagException

Disables the named control, if its value matches the specified value, or the specified value is null. In the case of checkboxes, radio buttons, and "select" controls, the control value is used in addition to the name to identify the relevant form control. In all other cases the value may be omitted. (Note that "disabling" means nothing more than adding the "disabled" attribute to applicable form controls.)

Parameters:

ControlName - Name of the form control.

ControlValue - Value of the form control, or null. The value is only needed when disabling specific items in multiple selection controls (checkboxes, radio buttons, and "select" controls). When dealing with those controls, passing null in this parameter causes all selections in the group to be disabled.

Returns:

This Form object.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

See Also:

Forms in HTML Documents, sec. 17.12.1, Disabled controls

disableControl

public static Match disableControl(Match Control,
                                   Object ControlValue)
                            throws TagException

Disables the specified control, if its value matches the specified value, or the specified value is null.

Parameters:

Control - A Match object corresponding to a tag of type "input", "select", "textarea", or "button".

ControlValue - The value the control must have in order to be disabled, or null if it should be disabled regardless of its value.

Returns:

The specified control.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

See Also:

Forms in HTML Documents, sec. 17.12.1, Disabled controls

deleteControl

public Form deleteControl(String ControlName,
                          Object ControlValue)
                   throws TagException

Deletes the specified control, if its value matches the specified value, or the specified value is null.

Parameters:

ControlName - Name of the form control.

ControlValue - Value of the form control, or null. The value is only needed when deleting specific items in multiple selection controls (checkboxes, radio buttons, and "select" controls). When dealing with those controls, passing null in this parameter causes all selections in the group to be deleted.

Returns:

This Form object.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

deleteControl

public static void deleteControl(Match Control,
                                 Object ControlValue)
                          throws TagException

Deletes the specified control, if its value matches the specified value, or the specified value is null.

Parameters:

Control - A Match object corresponding to a tag of type "input", "select", "textarea", or "button".

ControlValue - The value the control must have in order to be deleted, or null if it should be deleted regardless of its value.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

getDataSet

public FormDataSet getDataSet()

Get the values of all of the enabled, successful controls in this form. In other words, if we sent this form to a user, and they clicked "submit" without doing anything else to the form, what control values would we receive? That's the form data set that this method should return. Well, almost. There are special cases: (1) If there's more than one "submit" control in a form, none of their values are included, because we can't know which one the user would have picked. (2) If the only "submit" control in a form is an image map (an "input" control of type "image"), the "x" and "y" values supplied by it are both assumed to be zero. (3) File upload controls supply no values, because we can't know what file the user would have chosen.

Returns:

A form data set made up of name/value(s) pairs supplied by all of the enabled, successful controls in this form, except those noted in the method description.

getDataSet

public FormDataSet getDataSet(boolean IncludeSolitarySubmitControl)

Get the values of all of the enabled, successful controls in this form. In other words, if we sent this form to a user, and they clicked "submit" without doing anything else to the form, what control values would we receive? That's the form data set that this method should return. Well, almost. File upload controls supply no values, because we can't know what file the user would have chosen. Also, if the IncludeSolitarySubmitControl parameter is false the values of all submit control(s) are omitted. If the IncludeSolitarySubmitControl parameter is true, and there's only one submit control, its value is included, but if there are multiple "submit" controls, all of their values are omitted, because we cannot know which one the user would have picked.

Parameters:

IncludeSolitarySubmitControl - If true and the form includes only one "submit" control, the value of that control is included in the data set. If false, all "submit" contorls are ignored.

Returns:

A form data set made up of name/value(s) pairs supplied by all of the enabled, successful controls in this form, except those noted in the method description.

setDataSet

public Form setDataSet(FormDataSet DataSet)
                throws TagException

Takes the values of the supplied form data set, and writes them into this form, where applicable. Having done so, the user will not have to retype all the values as he/she does further work with this form, like correcting fields with invalid values.

Parameters:

DataSet - The form data set to be written into this form.

Returns:

This Form object.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

clearControlValues

public Form clearControlValues(boolean AlsoClearDisabledControls)
                        throws TagException

Removes the values from the controls in this form whose values can be altered by the user. The values of buttons, and hidden input controls are not affected, and the values of disabled controls of all types may be spared, if you wish.

Parameters:

AlsoClearDisabledControls - If true, the values of disabled controls of any type are also cleared. Otherwise, the values of disabled controls are left as they are.

Returns:

This Form object.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

clearControlValue

public Form clearControlValue(String ControlName)
                       throws TagException

Removes the value of the specified form control.

Parameters:

ControlName - Name of the form control.

Returns:

This Form object.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

clearControlValue

public static void clearControlValue(Match Control)
                              throws TagException

Clears the value of the supplied from control, even if it is of a type whose value cannot be altered by the user.

Parameters:

Control - A Match object corresponding to a tag of type "input", "select", "textarea", or "button".

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

getControlName

public static String getControlName(Match Control)

Returns the name of the specified control, or null if the control has no name.

Parameters:

Control - A Match object corresponding to a tag of type "input", "select", "textarea", or "button".

Returns:

The name of the specified control, or null if the control has no name.

getControlValue

public String getControlValue(String ControlName)

Returns the current value of the named control as a String. If the control has more than one value, this method will only return the first; use getControlValues(String) for multi-value controls. If the control has no value, or would not be successful, null is returned.

Parameters:

ControlName - The name of the control whose value should be retrieved.

Returns:

The value of the control, or null if the control does not exist, has no value, or would be unsuccessful.

getControlValues

public String[] getControlValues(String ControlName)

Returns the current value(s) of the named control as a String array. If the control has no values (maybe it is a group of radio buttons and none are selected), a zero-length array is returned. The exceptions to that rule are "input" controls of type "text" and "password", because without a value they will submit an empty string, so this method returns an empty string in their case. In other words, this method differentiates between successful and unsuccessful controls; returning null for a control that would be unsuccessful as it stands; returning an empty array for a control that would be successful, but has no value; and returning an array of one or more values for a control that would be successful and has one or more values.

Parameters:

ControlName - The name of the control whose value(s) should be retrieved.

Returns:

The value(s) of the control, or null if the control does not exist, or would be unsuccessful.

getControlValue

public static String getControlValue(Match Control)

Returns the value of the specified control as a String. If the control has more than one value, this method will only return the first; use getControlValues(Match) for multi-value controls. (In the context of this method, which can only operate on an individual control element, only a "select" control can have multiple values. To avoid that limitation, use getControlValue(String).) If the control has no value (maybe it is a "select" control with none of its "option" elements selected), null is returned. The exceptions to that rule are "input" controls of type "text" and "password", because without a value they will submit an empty string, so this method returns an empty string in their case. In other words, this method differentiates between successful and unsuccessful controls; returning null for a control that would be unsuccessful as it stands; returning an empty array for a control that would be successful, but has no value; and returning an array of one or more values for a control that would be successful and has one or more values.

Parameters:

Control - A Match object corresponding to a tag of type "input", "select", "option", "textarea", or "button".

Returns:

The value of the control, or null if the control does not exist, or has no value.

getControlValues

public static String[] getControlValues(Match Control)

Returns the value of the specified control as a String. If the control has more than one value, this method will only return the first; use getControlValues(Match) for multi-value controls. (In the context of this method, which can only operate on an individual control element, only a "select" control can have multiple values. To avoid that limitation, use getControlValue(String).) If the control has no value (maybe it is a "select" control with none of its "option" elements selected), null is returned. The exceptions to that rule are "input" controls of type "text" and "password", because without a value they will submit an empty string, so this method returns an empty string in their case. In other words, this method differentiates between successful and unsuccessful controls; returning null for a control that would be unsuccessful as it stands; returning an empty array for a control that would be successful, but has no value; and returning an array of one or more values for a control that would be successful and has one or more values.

Parameters:

Control - A Match object corresponding to a tag of type "input", "select", "option", "textarea", or "button".

Returns:

The value(s) of the control, or null if the control would be unsuccessful.

getControlValues

public static String[] getControlValues(Match Control,
                                        boolean SuccessfulControlsOnly,
                                        boolean IncludeSubmitControls,
                                        boolean IncludeMisnomerValues)

Returns the value(s) of the specified control, optionally limiting the values to those supplied by the controls that will be successful by default. If the specified control is an "input" control of type "checkbox" or "radio", or an "option" control, only the value of the specified control is considered; other controls in the same group (of the same name) are not considered. However, if the specified control is a "select" control, all of the "option" controls it contains are considered. Which means that, if you want to build-up a complete picture of the values that will be supplied by a form, you get all controls of type "input", "select", "textarea" and "button" and feed them to this method. Ordinarily, your would not bother to ask this method about controls of type "option", since they are dealt with when this method is called for their enclosing "select" controls.

Parameters:

Control - A Match object corresponding to a tag of type "input", "select", "option", "textarea", or "button".

SuccessfulControlsOnly - If true, only controls that would supply values (be successful) if a user were to submit the form as-is are allowed to contribute values to the list of values that is returned. If false, all controls supply their values.

IncludeSubmitControls - If true, the value(s) of submit button(s) (either "input" or "button" controls of type "submit"), are included in the list of values that is returned. If false they are omitted.

IncludeMisnomerValues - If true, the values of "input" controls of type "file" are returned. The real value of such controls can't be determined server-side, because the real value of the control is the content of the file, if any, that the user selects. However, such controls do have a "value" attribute which specifies the default name of the file on the client machine that is to be uploaded. For lack of a better name, I call that default file name in the "value" attribute a "misnomer value".

Returns:

An array of Strings, containing zero or more elements, representing the value(s) of the specified control. If the control has no value, the array is empty.

isControlEnabled

public static boolean isControlEnabled(Match Control)

Returns true if the specified control is enabled, false otherwise.

Parameters:

Control - A Match instance that refers to an "input", "select", "textarea" or "button" control.

Returns:

true if the specified control is enabled, false otherwise.

disableControl

public static Match disableControl(Match Control)
                            throws TagException

Disables the specified control.

Parameters:

Control - A Match instance that refers to an "input", "select", "textarea", "button", "option", or "optgroup" tag.

Returns:

The specified control.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

enableControl

public static Match enableControl(Match Control)
                           throws TagException

Enables the specified control.

Parameters:

Control - A Match instance that refers to an "input", "select", "textarea", "button", "option", or "optgroup" tag.

Returns:

The specified control.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

convertSubmitButtonsToInputs

public int convertSubmitButtonsToInputs()
                                 throws TagException

Converts all "button" controls of type "submit" to "input" controls of type "submit", in order to work around a hideous bug in Internet Explorer (Windows and Mac OS).

Returns:

The number of controls converted.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.

convertSubmitInputsToButtons

public int convertSubmitInputsToButtons()
                                 throws TagException

Converts all "input" controls of type "submit" that were "button" controls before convertSubmitButtonsToInputs() was invoked back into "button" controls of type "submit". In other words, this method undoes what convertSubmitButtonsToInputs() does.

Returns:

The number of controls converted.

Throws:

TagException - If a problem is encountered with the manipulation of the markup.