au.id.jericho.lib.html

Class FormControlType


public final class FormControlType
extends java.lang.Object

Represents the control type of a FormControl.

Use the FormControl.getFormControlType() method to determine the type of a form control.

The following table shows the relationship between the HTML 4.01 specification control type descriptions, their associated Element names and attributes, and the FormControlType constants defined in this class:

Description Element Name Distinguishing Attribute FormControlType
buttons - submit button BUTTON type="submit" BUTTON
INPUT type="submit" SUBMIT
type="image" IMAGE
buttons - reset button BUTTON, INPUT type="reset" -
buttons - push button BUTTON, INPUT type="button" -
checkboxes INPUT type="checkbox" CHECKBOX
radio buttons INPUT type="radio" RADIO
menus SELECT multiple SELECT_MULTIPLE
absence of multiple SELECT_SINGLE
text input INPUT type="text" TEXT
type="password" PASSWORD
TEXTAREA - TEXTAREA
file select INPUT type="file" FILE
hidden controls INPUT type="hidden" HIDDEN
object controls OBJECT - -
Reset buttons and push buttons have no associated FormControlType because they do not contribute to the form data set of a submitted form, and so have no relevance to the methods provided in the FormControl and associated classes. If required they can be found and manipulated as normal elements.

Object controls have no associated FormControlType because any data they might contribute to the form data set is entirely dependent on the class of object, the interpretation of which is is beyond the scope of this library.

This library does not consider the OPTION elements found within SELECT elements to be controls themselves, despite them being referred to as such in some parts of the HTML 4.01 specification. Hence the absence of an OPTION control type.

See Also:
FormControl, FormField

Field Summary

static FormControlType
BUTTON
The form control type given to a submit button control implemented using a BUTTON element.
static FormControlType
CHECKBOX
The form control type given to a checkbox control.
static FormControlType
FILE
The form control type given to a file select control.
static FormControlType
HIDDEN
The form control type given to a hidden control.
static FormControlType
IMAGE
The form control type given to a submit button control implemented using an INPUT element with attribute type="image".
static FormControlType
PASSWORD
The form control type given to a text input control implemented using an INPUT element with attribute type="password".
static FormControlType
RADIO
The form control type given to a radio button control.
static FormControlType
SELECT_MULTIPLE
The form control type given to a menu control implemented using a SELECT element containing the attribute "multiple".
static FormControlType
SELECT_SINGLE
The form control type given to a menu control implemented using a SELECT element that does not contain the attribute "multiple".
static FormControlType
SUBMIT
The form control type given to a submit button control implemented using an INPUT element with attribute type="submit".
static FormControlType
TEXT
The form control type given to a text input control implemented using an INPUT element with attribute type="text".
static FormControlType
TEXTAREA
The form control type given to a text input control implemented using a TEXTAREA element.

Method Summary

boolean
allowsMultipleValues()
Deprecated. Use the more useful FormField.allowsMultipleValues() method instead.
static FormControlType
get(String formControlTypeId)
Deprecated. no replacement
String[]
getAdditionalSubmitNames(String name)
Deprecated. no replacement
String
getElementName()
Returns the name of the Element that constitues this form control type.
String
getFormControlTypeId()
Deprecated. Use toString() instead.
String
getTagName()
Deprecated. Use getElementName() instead.
boolean
hasPredefinedValue()
Indicates whether any value submitted by this type of control is predefined in the HTML and typically not modified by the user or server/client scripts.
static boolean
isPotentialControl(String tagName)
Deprecated. no replacement
boolean
isPredefinedValue()
Deprecated. Use hasPredefinedValue() instead.
boolean
isSubmit()
Indicates whether this control type causes the form to be submitted.
String
toString()
Returns a string representation of this object useful for debugging purposes.

Field Details

BUTTON

public static final FormControlType BUTTON
The form control type given to a submit button control implemented using a BUTTON element.

<button type="submit" name="FieldName" value="PredefinedValue">Send</button>
getElementName() = HTMLElementName.BUTTON
hasPredefinedValue() = true
isSubmit() = true

CHECKBOX

public static final FormControlType CHECKBOX
The form control type given to a checkbox control.

<input type="checkbox" name="FieldName" value="PredefinedValue" />
getElementName() = HTMLElementName.INPUT
hasPredefinedValue() = true
isSubmit() = false

FILE

public static final FormControlType FILE
The form control type given to a file select control.

This library considers the submission value of this type of control to be consist of only the selected file name, regardless of whether the file content would normally be included in the form data set.

To determine manually whether the file content is included in the form data set, the enctype attribute of the control's associated FORM element can be examined. Although the exact behaviour is not defined in the HTML 4.01 specification, the convention is that the content is not included unless an enctype value of "multipart/form-data" is specified.

For more information see the HTML 4.01 specification section 17.13.4 - Form content types.

<input type="file" name="FieldName" value="DefaultFileName" />
getElementName() = HTMLElementName.INPUT
hasPredefinedValue() = false
isSubmit() = false

HIDDEN

public static final FormControlType HIDDEN
The form control type given to a hidden control.

<input type="hidden" name="FieldName" value="DefaultValue" />
getElementName() = HTMLElementName.INPUT
hasPredefinedValue() = false
isSubmit() = false
Note that hasPredefinedValue() returns false for this control type because the value of hidden fields is usually set via server or client side scripting.

IMAGE

public static final FormControlType IMAGE
The form control type given to a submit button control implemented using an INPUT element with attribute type="image".

See the description under the heading "image" in the HTML 4.01 specification section 17.4.1 - Form control types created with INPUT.

When a form control of type IMAGE is present in the form used to construct a FormFields instance, three separate FormField objects are created for the one control. One has the name specified in the name attribute of the INPUT element, and the other two have this name with the suffixes ".x" and ".y" appended to them to represent the additional click coordinates submitted by this control when activated using a pointing device.

This type of control is also mentioned in the HTML 4.01 specification section 13.6.2 - Server-side image maps.

<input type="image" name="FieldName" src="ImageURL" value="PredefinedValue" />
getElementName() = HTMLElementName.INPUT
hasPredefinedValue() = true
isSubmit() = true

PASSWORD

public static final FormControlType PASSWORD
The form control type given to a text input control implemented using an INPUT element with attribute type="password".

<input type="password" name="FieldName" value="DefaultValue" />
getElementName() = HTMLElementName.INPUT
hasPredefinedValue() = false
isSubmit() = false

RADIO

public static final FormControlType RADIO
The form control type given to a radio button control.

<input type="radio" name="FieldName" value="PredefinedValue" />
getElementName() = HTMLElementName.INPUT
hasPredefinedValue() = true
isSubmit() = false

SELECT_MULTIPLE

public static final FormControlType SELECT_MULTIPLE
The form control type given to a menu control implemented using a SELECT element containing the attribute "multiple".

SELECT elements that do not contain the attribute "multiple" are represented by the SELECT_SINGLE form control type.

This is the only control type that can have multiple submission values within the one control. Contrast this with CHECKBOX controls, which require multiple separate controls with the same name in order to contribute multiple submission values.

The individual OPTION elements contained within a form control of this type can be obtained using the FormControl.getOptionElementIterator() method.

The most efficient way to test whether a form control type is either SELECT_MULTIPLE or SELECT_SINGLE is to test for getElementName()==HTMLElementName.SELECT.

<select name="FieldName" multiple>
  <option value="PredefinedValue1" selected>Display Text1</option>
  <option value="PredefinedValue2">Display Text2</option>
</select>
getElementName() = HTMLElementName.SELECT
hasPredefinedValue() = true
isSubmit() = false

SELECT_SINGLE

public static final FormControlType SELECT_SINGLE
The form control type given to a menu control implemented using a SELECT element that does not contain the attribute "multiple".

SELECT elements that do contain the attribute "multiple" are represented by the SELECT_MULTIPLE form control type.

The individual OPTION elements contained within a form control of this type can be obtained using the FormControl.getOptionElementIterator() method.

The most efficient way to test whether a form control type is either SELECT_MULTIPLE or SELECT_SINGLE is to test for getElementName()==HTMLElementName.SELECT.

<select name="FieldName">
  <option value="PredefinedValue1" selected>Display Text1</option>
  <option value="PredefinedValue2">Display Text2</option>
</select>
getElementName() = HTMLElementName.SELECT
hasPredefinedValue() = true
isSubmit() = false

SUBMIT

public static final FormControlType SUBMIT
The form control type given to a submit button control implemented using an INPUT element with attribute type="submit".

<input type="submit" name="FieldName" value="PredefinedValue" />
getElementName() = HTMLElementName.INPUT
hasPredefinedValue() = true
isSubmit() = true

TEXT

public static final FormControlType TEXT
The form control type given to a text input control implemented using an INPUT element with attribute type="text".

<input type="text" name="FieldName" value="DefaultValue" />
getElementName() = HTMLElementName.INPUT
hasPredefinedValue() = false
isSubmit() = false

TEXTAREA

public static final FormControlType TEXTAREA
The form control type given to a text input control implemented using a TEXTAREA element.

<textarea name="FieldName">Default Value</textarea>
getElementName() = HTMLElementName.TEXTAREA
hasPredefinedValue() = false
isSubmit() = false

Method Details

allowsMultipleValues

public boolean allowsMultipleValues()

Deprecated. Use the more useful FormField.allowsMultipleValues() method instead.

Indicates whether more than one control of this type with the same name can be successful.

Returns false only for the RADIO, SUBMIT, BUTTON, and IMAGE instances.

Note that before version 1.4.1 this method also returned false for the SELECT_SINGLE instance. This was a bug resulting from confusion as to whether each OPTION element in a SELECT element constituted a control (since it is possible for multiple options to be successful) or only the SELECT element as a whole. Now that the control is clearly defined as the entire SELECT element, it is clear that multiple SELECT_SINGLE controls with the same name result in multiple values.

Because this may not be immediately intuitive, and the method is no longer used internally, this method has been deprecated as of version 2.0 to avoid any further confusion.

Returns:
true if more than one control of this type with the same name can be successful, otherwise false.

get

public static FormControlType get(String formControlTypeId)

Deprecated. no replacement

Returns the FormControlType with the specified ID.

This method has been deprecated as of version 2.0 as it has no practical use.

Parameters:
formControlTypeId - the ID of a form control type.
Returns:
the FormControlType with the specified ID, or null if no such control exists.

getAdditionalSubmitNames

public String[] getAdditionalSubmitNames(String name)

Deprecated. no replacement

Returns an array containing the additional field names submitted if a control of this type with the specified name is successful.

Returns null for all control types except IMAGE. It relates to the extra name.x and name.y data submitted when a pointing device is used to activate an IMAGE control.

This method has been deprecated as of version 2.0 as it is no longer used internally and has no practical use as a public method.

Parameters:
name - the name of a form control.
Returns:
an array containing the additional field names submitted if a control of this type with the specified name is successful, or null if none.

getElementName

public String getElementName()
Returns the name of the Element that constitues this form control type.
Returns:
the name of the Element that constitues this form control type.

getFormControlTypeId

public String getFormControlTypeId()

Deprecated. Use toString() instead.

Returns a string which identifies this form control type.

This is the same as the control type's static field name in lower case, which is one of
button, checkbox, file, hidden, image, password, radio, select_multiple, select_single, submit, text, or textarea.

This method has been deprecated as of version 2.0 as it has no practical use.

Returns:
a string which identifies this form control type.

getTagName

public String getTagName()

Deprecated. Use getElementName() instead.

Returns the name of the Element that constitues this form control type.

This method has been deprecated as of version 2.0 and replaced with the exactly equivalent getElementName() method for aesthetical reasons.

Returns:
the name of the Element that constitues this form control type.

hasPredefinedValue

public boolean hasPredefinedValue()
Indicates whether any value submitted by this type of control is predefined in the HTML and typically not modified by the user or server/client scripts.

The word "typically" is used because the use of client side scripts can cause control types which normally have predefined values to be set by the user, which is a condition which is beyond the scope of this library to test for.

The predefined value is defined by the control's initial value.

A return value of true signifies that a form control of this type is a predefined value control.

A return value of false signifies that a form control of this type is a user value control.

Note that the HIDDEN type returns false for this method because the value of hidden fields is usually set via server or client side scripting.

Returns:
true if any value submitted by this type of control is predefined in the HTML and typically not modified by the user or server/client scripts, otherwise false.

isPotentialControl

public static boolean isPotentialControl(String tagName)

Deprecated. no replacement

Indicates whether an HTML tag with the specified name is potentially a form control.

Returns true if the specified tag name is one of "input", "textarea", "button" or "select" (ignoring case).

This method has been deprecated as of version 2.0 as it is no longer used internally and has no practical use as a public method.

Parameters:
tagName - the name of an HTML tag.
Returns:
true if an HTML tag with the specified name is potentially a form control, otherwise false.

isPredefinedValue

public boolean isPredefinedValue()

Deprecated. Use hasPredefinedValue() instead.

Indicates whether any value submitted by this type of control is predefined in the HTML and typically not modified by the user or server/client scripts.

This method has been deprecated as of version 2.0 and replaced with the exactly equivalent hasPredefinedValue() method for aesthetical reasons.

Returns:
true if any value submitted by this type of control is predefined in the HTML and typically not modified by the user or server/client scripts, otherwise false.

isSubmit

public boolean isSubmit()
Returns:
true if this control type causes the form to be submitted, otherwise false.

toString

public String toString()
Returns a string representation of this object useful for debugging purposes.
Returns:
a string representation of this object useful for debugging purposes.