com.gargoylesoftware.htmlunit.html
Class HtmlForm

java.lang.Object
  extended by com.gargoylesoftware.htmlunit.html.DomNode
      extended by com.gargoylesoftware.htmlunit.html.DomNamespaceNode
          extended by com.gargoylesoftware.htmlunit.html.DomElement
              extended by com.gargoylesoftware.htmlunit.html.HtmlElement
                  extended by com.gargoylesoftware.htmlunit.html.StyledElement
                      extended by com.gargoylesoftware.htmlunit.html.ClickableElement
                          extended by com.gargoylesoftware.htmlunit.html.HtmlForm
All Implemented Interfaces:
Serializable, Cloneable

public class HtmlForm
extends ClickableElement

Wrapper for the html element "form"

Version:
$Revision: 2141 $
Author:
Mike Bowler, David K. Taylor, Brad Clarke, Christian Sell, Marc Guillemot, George Murnock, Kent Tong, Ahmed Ashour, Philip Graf
See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class com.gargoylesoftware.htmlunit.html.HtmlElement
HtmlElement.ChildElementsIterator, HtmlElement.MapEntryWrappingIterator
 
Nested classes/interfaces inherited from class com.gargoylesoftware.htmlunit.html.DomNode
DomNode.ChildIterator, DomNode.DescendantElementsIterator
 
Field Summary
static String TAG_NAME
          the HTML tag represented by this element
 
Fields inherited from class com.gargoylesoftware.htmlunit.html.HtmlElement
ATTRIBUTE_NOT_DEFINED, ATTRIBUTE_VALUE_EMPTY, TAB_INDEX_OUT_OF_BOUNDS
 
Fields inherited from class com.gargoylesoftware.htmlunit.html.DomNode
ATTRIBUTE_NODE, COMMENT_NODE, DOCUMENT_NODE, ELEMENT_NODE, PROPERTY_ELEMENT, READY_STATE_COMPLETE, READY_STATE_INTERACTIVE, READY_STATE_LOADED, READY_STATE_LOADING, READY_STATE_UNINITIALIZED, TEXT_NODE
 
Constructor Summary
HtmlForm(HtmlPage htmlPage, Map attributes)
          Deprecated. You should not directly construct HtmlForm.
 
Method Summary
 void fakeCheckedRadioButton(String name, String value)
          Deprecated. after 1.11
 String getAcceptAttribute()
          Return the value of the attribute "accept".
 String getAcceptCharsetAttribute()
          Return the value of the attribute "accept-charset".
 String getActionAttribute()
          Return the value of the attribute "action".
 HtmlButton getButtonByName(String name)
          Find the first button element with the specified name.
 List getButtonsByName(String name)
          Return all the HtmlButtons that match the specified name
 HtmlRadioButtonInput getCheckedRadioButton(String name)
          Return the first checked radio button with the specified name.
 String getEnctypeAttribute()
          Return the value of the attribute "enctype".
 HtmlInput getInputByName(String name)
          Return the first input with the specified name
 HtmlInput getInputByValue(String value)
          Return the first input with the specified value.
 List getInputsByName(String name)
          Return the input tags that have the specified name
 List getInputsByValue(String value)
          Return all the inputs with the specified value.
 String getMethodAttribute()
          Return the value of the attribute "method".
 String getNameAttribute()
          Return the value of the attribute "name".
 String getOnResetAttribute()
          Return the value of the attribute "onreset".
 String getOnSubmitAttribute()
          Return the value of the attribute "onsubmit".
 List getParameterListForSubmit(SubmittableElement submitElement)
          Return a list of KeyValuePairs that represent the data that will be sent to the server on a form submit.
 HtmlRadioButtonInput getRadioButtonInput(String name, String value)
          Deprecated. Deprecated because 'name' and 'value' are sometimes not unique to select a single HtmlRadioButtonInput, it should not be called, you can use DomNode.getByXPath(String) instead.
 List getRadioButtonsByName(String name)
          Return a list of HtmlInputs that are of type radio and match the specified name
 HtmlSelect getSelectByName(String name)
          Find the first select element with the specified name
 List getSelectsByName(String name)
          Return all the HtmlSelect that match the specified name
 Collection getSubmittableElements(SubmittableElement submitElement)
          Return a collection of elements that represent all the "submittable" elements in this form
 String getTargetAttribute()
          Return the value of the attribute "target".
 HtmlTextArea getTextAreaByName(String name)
          Find the first textarea element with the specified name.
 List getTextAreasByName(String name)
          Return all the HtmlTextAreas that match the specified name
 Page reset()
          Reset this form to its initial values.
 void setActionAttribute(String action)
          Set the value of the attribute "action".
 void setCheckedRadioButton(String name, String value)
          Deprecated. Deprecated because 'name' and 'value' are sometimes not unique to select a single HtmlRadioButtonInput, it should not be called, you can use DomNode.getByXPath(String) instead.
 void setEnctypeAttribute(String encoding)
          Set the value of the attribute "enctype".
 void setMethodAttribute(String method)
          Set the value of the attribute "method".
 void setNameAttribute(String name)
          Set the value of the attribute "name".
 void setTargetAttribute(String target)
          Set the value of the attribute "target".
 Page submit()
          Deprecated. after 1.11, click on a specific SubmittableElement instead.
 Page submit(String buttonName)
          Deprecated. after 1.11, click on the specific SubmittableElement instead.
 Page submit(SubmittableElement submitElement)
          INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
Submit this form to the appropriate server.
 
Methods inherited from class com.gargoylesoftware.htmlunit.html.ClickableElement
click, click, click, dblClick, dblClick, doClickAction, getLangAttribute, getOnClickAttribute, getOnDblClickAttribute, getOnKeyDownAttribute, getOnKeyPressAttribute, getOnKeyUpAttribute, getOnMouseDownAttribute, getOnMouseMoveAttribute, getOnMouseOutAttribute, getOnMouseOverAttribute, getOnMouseUpAttribute, getTextDirectionAttribute, getXmlLangAttribute, isStateUpdateFirst
 
Methods inherited from class com.gargoylesoftware.htmlunit.html.StyledElement
getClassAttribute, getIdAttribute, getStyleAttribute, getTitleAttribute, isRenderedVisible
 
Methods inherited from class com.gargoylesoftware.htmlunit.html.HtmlElement
addHtmlAttributeChangeListener, appendChildIfNoneExists, assertNotEmpty, blur, cloneDomNode, cloneNode, fireEvent, fireEvent, fireHtmlAttributeAdded, fireHtmlAttributeRemoved, fireHtmlAttributeReplaced, focus, getAttribute, getAttributeEntriesIterator, getAttributeNS, getAttributeValue, getChildElementsIterator, getEnclosingElement, getEnclosingForm, getEnclosingFormOrDie, getEventHandler, getHtmlElementById, getHtmlElementsByAttribute, getHtmlElementsByTagName, getHtmlElementsByTagNames, getId, getNodeName, getNodeType, getOneHtmlElementByAttribute, getTabIndex, getTagName, hasAttribute, hasAttributeNS, hasAttributes, hasHtmlElementWithId, isAttributeDefined, isEmptyXmlTagExpanded, isSubmittableByEnter, keyDown, keyDown, mouseDown, mouseDown, mouseMove, mouseMove, mouseOut, mouseOut, mouseOver, mouseOver, mouseUp, mouseUp, notImplemented, preventDefault, printOpeningTagContentAsXml, printXml, removeAttribute, removeAttributeNS, removeChild, removeEventHandler, removeHtmlAttributeChangeListener, rightClick, rightClick, setAttribute, setAttributeNS, setAttributeValue, setAttributeValue, setEventHandler, setEventHandler, setId, toString, type, type, type, type
 
Methods inherited from class com.gargoylesoftware.htmlunit.html.DomNamespaceNode
getLocalName, getNamespaceURI, getPrefix, getQualifiedName, setPrefix
 
Methods inherited from class com.gargoylesoftware.htmlunit.html.DomNode
addDomChangeListener, addPropertyChangeListener, appendChild, appendDomChild, asText, asXml, fireNodeAdded, fireNodeDeleted, firePropertyChange, getAllHtmlChildElements, getByXPath, getChildIterator, getChildrenAsText, getEndColumnNumber, getEndLineNumber, getFirstByXPath, getFirstChild, getFirstDomChild, getLastChild, getLastDomChild, getLog, getNativePage, getNextDomSibling, getNextSibling, getNodeValue, getPage, getParentDomNode, getParentNode, getPreviousDomSibling, getPreviousSibling, getReadyState, getScriptObject, getStartColumnNumber, getStartLineNumber, insertBefore, isAncestorOf, isTrimmedText, notifyIncorrectness, onAddedToPage, onAllChildrenAddedToPage, printChildrenAsXml, reduceWhitespace, remove, removeAllChildren, removeDomChangeListener, removePropertyChangeListener, replace, setNextSibling, setNodeValue, setParentNode, setPreviousSibling, setReadyState, setScriptObject
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

TAG_NAME

public static final String TAG_NAME
the HTML tag represented by this element

See Also:
Constant Field Values
Constructor Detail

HtmlForm

public HtmlForm(HtmlPage htmlPage,
                Map attributes)
Deprecated. You should not directly construct HtmlForm.

Create an instance

Parameters:
htmlPage - The page that contains this element
attributes - the initial attributes
Method Detail

submit

public Page submit(String buttonName)
            throws IOException,
                   ElementNotFoundException
Deprecated. after 1.11, click on the specific SubmittableElement instead.

Submit this form to the appropriate server as if a submit button had been pressed

Parameters:
buttonName - The name of a submit input element or a button element which will be sent back up with the response
Returns:
A new Page that reflects the results of this submission
Throws:
IOException - If an IO error occurs
ElementNotFoundException - If a button with the specified name cannot be found.

submit

public Page submit()
            throws IOException
Deprecated. after 1.11, click on a specific SubmittableElement instead.

Submit this form to the appropriate server as if it had been submitted by javascript - i.e. no submit buttons were pressed. Note that because we are simulating a javascript submit, the onsubmit handler will not get executed.

Returns:
A new Page that reflects the results of this submission
Throws:
IOException - If an IO error occurs

submit

public Page submit(SubmittableElement submitElement)
            throws IOException
INTERNAL API - SUBJECT TO CHANGE AT ANY TIME - USE AT YOUR OWN RISK.
Submit this form to the appropriate server. If submitElement is null then treat this as if it was called by javascript. In this case, the onsubmit handler will not get executed.

Parameters:
submitElement - The element that caused the submit to occur
Returns:
A new Page that reflects the results of this submission
Throws:
IOException - If an IO error occurs

getParameterListForSubmit

public final List getParameterListForSubmit(SubmittableElement submitElement)
Return a list of KeyValuePairs that represent the data that will be sent to the server on a form submit. This is primarily intended to aid debugging.

Parameters:
submitElement - The element that would have been pressed to submit the form or null if the form was submitted by javascript.
Returns:
The list of KeyValuePairs.

reset

public Page reset()
Reset this form to its initial values.

Returns:
The page that is loaded at the end of calling this method. Typically this will be the same page that had been loaded previously but since javascript might have run, this isn't guaranteed.

getSubmittableElements

public Collection getSubmittableElements(SubmittableElement submitElement)
Return a collection of elements that represent all the "submittable" elements in this form

Parameters:
submitElement - The element that would have been pressed to submit the form or null if the form was submitted by javascript.
Returns:
See above

getInputsByName

public List getInputsByName(String name)
Return the input tags that have the specified name

Parameters:
name - The name of the input
Returns:
A list of HtmlInputs

getInputByName

public final HtmlInput getInputByName(String name)
                               throws ElementNotFoundException
Return the first input with the specified name

Parameters:
name - The name of the input
Returns:
The input
Throws:
ElementNotFoundException - If no inputs could be found with the specified name.

getRadioButtonInput

public HtmlRadioButtonInput getRadioButtonInput(String name,
                                                String value)
                                         throws ElementNotFoundException
Deprecated. Deprecated because 'name' and 'value' are sometimes not unique to select a single HtmlRadioButtonInput, it should not be called, you can use DomNode.getByXPath(String) instead.

Return the "radio" type input field that matches the specified name and value

Parameters:
name - The name of the HtmlInput
value - The value of the HtmlInput
Returns:
See above
Throws:
ElementNotFoundException - If the field could not be found

getSelectsByName

public List getSelectsByName(String name)
Return all the HtmlSelect that match the specified name

Parameters:
name - The name
Returns:
See above

getSelectByName

public HtmlSelect getSelectByName(String name)
                           throws ElementNotFoundException
Find the first select element with the specified name

Parameters:
name - The name of the select element
Returns:
The first select.
Throws:
ElementNotFoundException - If the select cannot be found.

getButtonsByName

public List getButtonsByName(String name)
                      throws ElementNotFoundException
Return all the HtmlButtons that match the specified name

Parameters:
name - The name
Returns:
See above
Throws:
ElementNotFoundException - If no matching buttons were found

getButtonByName

public HtmlButton getButtonByName(String name)
                           throws ElementNotFoundException
Find the first button element with the specified name.

Parameters:
name - The name of the button element.
Returns:
The first button.
Throws:
ElementNotFoundException - If the button cannot be found.

getTextAreasByName

public List getTextAreasByName(String name)
Return all the HtmlTextAreas that match the specified name

Parameters:
name - The name
Returns:
See above

getTextAreaByName

public HtmlTextArea getTextAreaByName(String name)
                               throws ElementNotFoundException
Find the first textarea element with the specified name.

Parameters:
name - The name of the textarea element.
Returns:
The first textarea.
Throws:
ElementNotFoundException - If the textarea cannot be found.

getRadioButtonsByName

public List getRadioButtonsByName(String name)
Return a list of HtmlInputs that are of type radio and match the specified name

Parameters:
name - The name
Returns:
See above

setCheckedRadioButton

public void setCheckedRadioButton(String name,
                                  String value)
                           throws ElementNotFoundException
Deprecated. Deprecated because 'name' and 'value' are sometimes not unique to select a single HtmlRadioButtonInput, it should not be called, you can use DomNode.getByXPath(String) instead.

Select the specified radio button in the form.

Only a radio button that is actually contained in the form can be selected. If you need to be able to select a button that really isn't there (ie during testing of error cases) then use fakeCheckedRadioButton(String,String) instead

Parameters:
name - The name of the radio buttons
value - The value to match
Throws:
ElementNotFoundException - If the specified element could not be found

fakeCheckedRadioButton

public final void fakeCheckedRadioButton(String name,
                                         String value)
                                  throws ElementNotFoundException
Deprecated. after 1.11

Set the "selected radio button" to a value that doesn't actually exist in the page. This is useful primarily for testing error cases.

Parameters:
name - The name of the radio buttons
value - The value to match
Throws:
ElementNotFoundException - If a particular xml element could not be found in the dom model

getCheckedRadioButton

public HtmlRadioButtonInput getCheckedRadioButton(String name)
Return the first checked radio button with the specified name. If none of the radio buttons by that name are checked then return null.

Parameters:
name - The name of the radio button
Returns:
The first checked radio button.

getActionAttribute

public final String getActionAttribute()
Return the value of the attribute "action". Refer to the HTML 4.01 documentation for details on the use of this attribute.

Returns:
The value of the attribute "action" or an empty string if that attribute isn't defined.

setActionAttribute

public final void setActionAttribute(String action)
Set the value of the attribute "action". Refer to the HTML 4.01 documentation for details on the use of this attribute.

Parameters:
action - The value of the attribute "action"

getMethodAttribute

public final String getMethodAttribute()
Return the value of the attribute "method". Refer to the HTML 4.01 documentation for details on the use of this attribute.

Returns:
The value of the attribute "method" or an empty string if that attribute isn't defined.

setMethodAttribute

public final void setMethodAttribute(String method)
Set the value of the attribute "method". Refer to the HTML 4.01 documentation for details on the use of this attribute.

Parameters:
method - The value of the attribute "method" or an empty string if that attribute isn't defined.

getNameAttribute

public final String getNameAttribute()
Return the value of the attribute "name". Refer to the HTML 4.01 documentation for details on the use of this attribute.

Returns:
The value of the attribute "name" or an empty string if that attribute isn't defined.

setNameAttribute

public final void setNameAttribute(String name)
Set the value of the attribute "name". Refer to the HTML 4.01 documentation for details on the use of this attribute.

Parameters:
name - the new value

getEnctypeAttribute

public final String getEnctypeAttribute()
Return the value of the attribute "enctype". Refer to the HTML 4.01 documentation for details on the use of this attribute.

Enctype is the encoding type used when submitting a form back to the server

Returns:
The value of the attribute "enctype" or an empty string if that attribute isn't defined.

setEnctypeAttribute

public final void setEnctypeAttribute(String encoding)
Set the value of the attribute "enctype". Refer to the HTML 4.01 documentation for details on the use of this attribute.

Enctype is the encoding type used when submitting a form back to the server

Parameters:
encoding - The value of the attribute "enctype" or an empty string if that attribute isn't defined.

getOnSubmitAttribute

public final String getOnSubmitAttribute()
Return the value of the attribute "onsubmit". Refer to the HTML 4.01 documentation for details on the use of this attribute.

Returns:
The value of the attribute "onsubmit" or an empty string if that attribute isn't defined.

getOnResetAttribute

public final String getOnResetAttribute()
Return the value of the attribute "onreset". Refer to the HTML 4.01 documentation for details on the use of this attribute.

Returns:
The value of the attribute "onreset" or an empty string if that attribute isn't defined.

getAcceptAttribute

public final String getAcceptAttribute()
Return the value of the attribute "accept". Refer to the HTML 4.01 documentation for details on the use of this attribute.

Returns:
The value of the attribute "accept" or an empty string if that attribute isn't defined.

getAcceptCharsetAttribute

public final String getAcceptCharsetAttribute()
Return the value of the attribute "accept-charset". Refer to the HTML 4.01 documentation for details on the use of this attribute.

Returns:
The value of the attribute "accept-charset" or an empty string if that attribute isn't defined.

getTargetAttribute

public final String getTargetAttribute()
Return the value of the attribute "target". Refer to the HTML 4.01 documentation for details on the use of this attribute.

Returns:
The value of the attribute "target" or an empty string if that attribute isn't defined.

setTargetAttribute

public final void setTargetAttribute(String target)
Set the value of the attribute "target". Refer to the HTML 4.01 documentation for details on the use of this attribute.

Parameters:
target - The value of the attribute "target" or an empty string if that attribute isn't defined.

getInputByValue

public HtmlInput getInputByValue(String value)
                          throws ElementNotFoundException
Return the first input with the specified value.

Parameters:
value - The value
Returns:
The first input with the specified value.
Throws:
ElementNotFoundException - If no elements can be found with the specified value.

getInputsByValue

public List getInputsByValue(String value)
Return all the inputs with the specified value.

Parameters:
value - The value
Returns:
all the inputs with the specified value.


Copyright © 2002-2010 Gargoyle Software Inc.. All Rights Reserved.