public class

FormPanel

extends SimplePanel
implements FiresFormEvents FormPanelImplHost
java.lang.Object
   ↳ com.google.gwt.user.client.ui.UIObject
     ↳ com.google.gwt.user.client.ui.Widget
       ↳ com.google.gwt.user.client.ui.Panel
         ↳ com.google.gwt.user.client.ui.SimplePanel
           ↳ com.google.gwt.user.client.ui.FormPanel

Class Overview

A panel that wraps its contents in an HTML <FORM> element.

This panel can be used to achieve interoperability with servers that accept traditional HTML form encoding. The following widgets (those that implement HasName) will be submitted to the server if they are contained within this panel:

In particular, FileUpload is only useful when used within a FormPanel, because the browser will only upload files using form submission.

Example

{@example com.google.gwt.examples.FormPanelExample}

Summary

Nested Classes
class FormPanel.SubmitCompleteEvent Fired when a form has been submitted successfully. 
interface FormPanel.SubmitCompleteHandler Handler for FormPanel.SubmitCompleteEvent events. 
class FormPanel.SubmitEvent Fired when the form is submitted. 
interface FormPanel.SubmitHandler Handler for FormPanel.SubmitEvent events. 
Constants
String ENCODING_MULTIPART Used with setEncoding(String) to specify that the form will be submitted using MIME encoding (necessary for FileUpload to work properly).
String ENCODING_URLENCODED Used with setEncoding(String) to specify that the form will be submitted using traditional URL encoding.
String METHOD_GET Used with setMethod(String) to specify that the form will be submitted using an HTTP GET request.
String METHOD_POST Used with setMethod(String) to specify that the form will be submitted using an HTTP POST request (necessary for FileUpload to work properly).
[Expand]
Inherited Constants
From class com.google.gwt.user.client.ui.UIObject
Public Constructors
FormPanel()
Creates a new FormPanel.
FormPanel(NamedFrame frameTarget)
Creates a FormPanel that targets a NamedFrame.
FormPanel(String target)
Creates a new FormPanel.
Protected Constructors
FormPanel(Element element)
This constructor may be used by subclasses to explicitly use an existing element.
FormPanel(Element element, boolean createIFrame)
This constructor may be used by subclasses to explicitly use an existing element.
Public Methods
void addFormHandler(FormHandler handler)
This method is deprecated. Use addSubmitCompleteHandler(FormPanel.SubmitCompleteHandler) and addSubmitHandler(FormPanel.SubmitHandler) instead
HandlerRegistration addSubmitCompleteHandler(FormPanel.SubmitCompleteHandler handler)
Adds a FormPanel.SubmitCompleteEvent handler.
HandlerRegistration addSubmitHandler(FormPanel.SubmitHandler handler)
Adds a FormPanel.SubmitEvent handler.
String getAction()
Gets the 'action' associated with this form.
String getEncoding()
Gets the encoding used for submitting this form.
String getMethod()
Gets the HTTP method used for submitting this form.
String getTarget()
Gets the form's 'target'.
boolean onFormSubmit()
Fired when a form is submitted.
void onFrameLoad()
Called when the target frame is done loading.
void removeFormHandler(FormHandler handler)
This method is deprecated. Use the removeHandler() method on the object returned by and add*Handler method instead
void reset()
Resets the form, clearing all fields.
void setAction(String url)
Sets the 'action' associated with this form.
void setEncoding(String encodingType)
Sets the encoding used for submitting this form.
void setMethod(String method)
Sets the HTTP method used for submitting this form.
void submit()
Submits the form.
static FormPanel wrap(Element element, boolean createIFrame)
Creates a FormPanel that wraps an existing <form> element.
static FormPanel wrap(Element element)
Creates a FormPanel that wraps an existing <form> element.
Protected Methods
void onAttach()

This method is called when a widget is attached to the browser's document.

void onDetach()

This method is called when a widget is detached from the browser's document.

[Expand]
Inherited Methods
From class com.google.gwt.user.client.ui.SimplePanel
From class com.google.gwt.user.client.ui.Panel
From class com.google.gwt.user.client.ui.Widget
From class com.google.gwt.user.client.ui.UIObject
From class java.lang.Object
From interface com.google.gwt.event.logical.shared.HasAttachHandlers
From interface com.google.gwt.event.shared.HasHandlers
From interface com.google.gwt.user.client.EventListener
From interface com.google.gwt.user.client.ui.AcceptsOneWidget
From interface com.google.gwt.user.client.ui.FiresFormEvents
From interface com.google.gwt.user.client.ui.HasOneWidget
From interface com.google.gwt.user.client.ui.HasWidgets
From interface com.google.gwt.user.client.ui.HasWidgets.ForIsWidget
From interface com.google.gwt.user.client.ui.IsWidget
From interface com.google.gwt.user.client.ui.impl.FormPanelImplHost
From interface java.lang.Iterable

Constants

public static final String ENCODING_MULTIPART

Used with setEncoding(String) to specify that the form will be submitted using MIME encoding (necessary for FileUpload to work properly).

Constant Value: "multipart/form-data"

public static final String ENCODING_URLENCODED

Used with setEncoding(String) to specify that the form will be submitted using traditional URL encoding.

Constant Value: "application/x-www-form-urlencoded"

public static final String METHOD_GET

Used with setMethod(String) to specify that the form will be submitted using an HTTP GET request.

Constant Value: "get"

public static final String METHOD_POST

Used with setMethod(String) to specify that the form will be submitted using an HTTP POST request (necessary for FileUpload to work properly).

Constant Value: "post"

Public Constructors

public FormPanel ()

Creates a new FormPanel. When created using this constructor, it will be submitted to a hidden <iframe> element, and the results of the submission made available via FormPanel.SubmitCompleteHandler.

The back-end server is expected to respond with a content-type of 'text/html', meaning that the text returned will be treated as HTML. If any other content-type is specified by the server, then the result HTML sent in the onFormSubmit event will be unpredictable across browsers, and the onSubmitComplete event may not fire at all.

public FormPanel (NamedFrame frameTarget)

Creates a FormPanel that targets a NamedFrame. The target frame is not physically attached to the form, and must therefore still be added to a panel elsewhere.

When the FormPanel targets an external frame in this way, it will not fire the FormSubmitComplete event.

Parameters
frameTarget the NamedFrame to be targetted

public FormPanel (String target)

Creates a new FormPanel. When created using this constructor, it will be submitted either by replacing the current page, or to the named <iframe>.

When the FormPanel targets an external frame in this way, it will not fire the FormSubmitComplete event.

Parameters
target the name of the <iframe> to receive the results of the submission, or null to specify that the current page be replaced

Protected Constructors

protected FormPanel (Element element)

This constructor may be used by subclasses to explicitly use an existing element. This element must be a <form> element.

The specified form element's target attribute will not be set, and the FormSubmitCompleteEvent will not be fired.

Parameters
element the element to be used

protected FormPanel (Element element, boolean createIFrame)

This constructor may be used by subclasses to explicitly use an existing element. This element must be a <form> element.

If the createIFrame parameter is set to true, then the wrapped form's target attribute will be set to a hidden iframe. If not, the form's target will be left alone, and the FormSubmitComplete event will not be fired.

Parameters
element the element to be used
createIFrame true to create an <iframe> element that will be targeted by this form

Public Methods

public void addFormHandler (FormHandler handler)

This method is deprecated.
Use addSubmitCompleteHandler(FormPanel.SubmitCompleteHandler) and addSubmitHandler(FormPanel.SubmitHandler) instead

Adds a handler interface to receive click events.

Parameters
handler the handler interface to add

public HandlerRegistration addSubmitCompleteHandler (FormPanel.SubmitCompleteHandler handler)

Adds a FormPanel.SubmitCompleteEvent handler.

Parameters
handler the handler
Returns
  • the handler registration used to remove the handler

public HandlerRegistration addSubmitHandler (FormPanel.SubmitHandler handler)

Adds a FormPanel.SubmitEvent handler.

Parameters
handler the handler
Returns
  • the handler registration used to remove the handler

public String getAction ()

Gets the 'action' associated with this form. This is the URL to which it will be submitted.

Returns
  • the form's action

public String getEncoding ()

Gets the encoding used for submitting this form. This should be either ENCODING_MULTIPART or ENCODING_URLENCODED.

Returns
  • the form's encoding

public String getMethod ()

Gets the HTTP method used for submitting this form. This should be either METHOD_GET or METHOD_POST.

Returns
  • the form's method

public String getTarget ()

Gets the form's 'target'. This is the name of the NamedFrame that will receive the results of submission, or null if none has been specified.

Returns
  • the form's target.

public boolean onFormSubmit ()

Fired when a form is submitted.

Returns
  • true if the form is submitted, false if canceled

public void onFrameLoad ()

Called when the target frame is done loading.

public void removeFormHandler (FormHandler handler)

This method is deprecated.
Use the removeHandler() method on the object returned by and add*Handler method instead

Removes a previously added handler interface.

Parameters
handler the handler interface to remove

public void reset ()

Resets the form, clearing all fields.

public void setAction (String url)

Sets the 'action' associated with this form. This is the URL to which it will be submitted.

Parameters
url the form's action

public void setEncoding (String encodingType)

Sets the encoding used for submitting this form. This should be either ENCODING_MULTIPART or ENCODING_URLENCODED.

Parameters
encodingType the form's encoding

public void setMethod (String method)

Sets the HTTP method used for submitting this form. This should be either METHOD_GET or METHOD_POST.

Parameters
method the form's method

public void submit ()

Submits the form.

The FormPanel must not be detached (i.e. removed from its parent or otherwise disconnected from a RootPanel) until the submission is complete. Otherwise, notification of submission will fail.

public static FormPanel wrap (Element element, boolean createIFrame)

Creates a FormPanel that wraps an existing <form> element. This element must already be attached to the document. If the element is removed from the document, you must call detachNow(Widget).

If the createIFrame parameter is set to true, then the wrapped form's target attribute will be set to a hidden iframe. If not, the form's target will be left alone, and the FormSubmitComplete event will not be fired.

Parameters
element the element to be wrapped
createIFrame true to create an <iframe> element that will be targeted by this form

public static FormPanel wrap (Element element)

Creates a FormPanel that wraps an existing <form> element. This element must already be attached to the document. If the element is removed from the document, you must call detachNow(Widget).

The specified form element's target attribute will not be set, and the FormSubmitCompleteEvent will not be fired.

Parameters
element the element to be wrapped

Protected Methods

protected void onAttach ()

This method is called when a widget is attached to the browser's document. To receive notification after a Widget has been added to the document, override the onLoad() method or use addAttachHandler(AttachEvent.Handler).

It is strongly recommended that you override onLoad() or doAttachChildren() instead of this method to avoid inconsistencies between logical and physical attachment states.

Subclasses that override this method must call super.onAttach() to ensure that the Widget has been attached to its underlying Element.

protected void onDetach ()

This method is called when a widget is detached from the browser's document. To receive notification before a Widget is removed from the document, override the onUnload() method or use addAttachHandler(AttachEvent.Handler).

It is strongly recommended that you override onUnload() or doDetachChildren() instead of this method to avoid inconsistencies between logical and physical attachment states.

Subclasses that override this method must call super.onDetach() to ensure that the Widget has been detached from the underlying Element. Failure to do so will result in application memory leaks due to circular references between DOM Elements and JavaScript objects.