com.google.gwt.user.client.ui

Class FormPanel

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

All Implemented Interfaces:

HasAttachHandlers, HasHandlers, EventListener, AcceptsOneWidget, FiresFormEvents, HasOneWidget, HasVisibility, HasWidgets, HasWidgets.ForIsWidget, com.google.gwt.user.client.ui.impl.FormPanelImplHost, IsWidget, java.lang.Iterable<Widget>

public class FormPanel
extends SimplePanel
implements FiresFormEvents, com.google.gwt.user.client.ui.impl.FormPanelImplHost

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:

• TextBox
• PasswordTextBox
• RadioButton
• SimpleRadioButton
• CheckBox
• SimpleCheckBox
• TextArea
• ListBox
• FileUpload
• Hidden

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

Example

public class FormPanelExample implements EntryPoint {

  public void onModuleLoad() {
    // Create a FormPanel and point it at a service.
    final FormPanel form = new FormPanel();
    form.setAction("/myFormHandler");

    // Because we're going to add a FileUpload widget, we'll need to set the
    // form to use the POST method, and multipart MIME encoding.
    form.setEncoding(FormPanel.ENCODING_MULTIPART);
    form.setMethod(FormPanel.METHOD_POST);

    // Create a panel to hold all of the form widgets.
    VerticalPanel panel = new VerticalPanel();
    form.setWidget(panel);

    // Create a TextBox, giving it a name so that it will be submitted.
    final TextBox tb = new TextBox();
    tb.setName("textBoxFormElement");
    panel.add(tb);

    // Create a ListBox, giving it a name and some values to be associated with
    // its options.
    ListBox lb = new ListBox();
    lb.setName("listBoxFormElement");
    lb.addItem("foo", "fooValue");
    lb.addItem("bar", "barValue");
    lb.addItem("baz", "bazValue");
    panel.add(lb);

    // Create a FileUpload widget.
    FileUpload upload = new FileUpload();
    upload.setName("uploadFormElement");
    panel.add(upload);

    // Add a 'submit' button.
    panel.add(new Button("Submit", new ClickHandler() {
      public void onClick(ClickEvent event) {
        form.submit();
      }
    }));

    // Add an event handler to the form.
    form.addSubmitHandler(new FormPanel.SubmitHandler() {
      public void onSubmit(SubmitEvent event) {
        // This event is fired just before the form is submitted. We can take
        // this opportunity to perform validation.
        if (tb.getText().length() == 0) {
          Window.alert("The text box must not be empty");
          event.cancel();
        }
      }
    });
    form.addSubmitCompleteHandler(new FormPanel.SubmitCompleteHandler() {
      public void onSubmitComplete(SubmitCompleteEvent event) {
        // When the form submission is successfully completed, this event is
        // fired. Assuming the service returned a response of type text/html,
        // we can get the result text here (see the FormPanel documentation for
        // further explanation).
        Window.alert(event.getResults());
      }
    });

    RootPanel.get().add(form);
  }
}

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
(package private) static interface	FormPanel.IFrameTemplate
static class	FormPanel.SubmitCompleteEvent Fired when a form has been submitted successfully.
static interface	FormPanel.SubmitCompleteHandler Handler for FormPanel.SubmitCompleteEvent events.
static class	FormPanel.SubmitEvent Fired when the form is submitted.
static interface	FormPanel.SubmitHandler Handler for FormPanel.SubmitEvent events.

Nested classes/interfaces inherited from class com.google.gwt.user.client.ui.UIObject

UIObject.DebugIdImpl, UIObject.DebugIdImplEnabled

Nested classes/interfaces inherited from interface com.google.gwt.user.client.ui.HasWidgets

HasWidgets.ForIsWidget

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ENCODING_MULTIPART Used with setEncoding(String) to specify that the form will be submitted using MIME encoding (necessary for FileUpload to work properly).
static java.lang.String	ENCODING_URLENCODED Used with setEncoding(String) to specify that the form will be submitted using traditional URL encoding.
static java.lang.String	METHOD_GET Used with setMethod(String) to specify that the form will be submitted using an HTTP GET request.
static java.lang.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).

Fields inherited from class com.google.gwt.user.client.ui.SimplePanel

widget

Fields inherited from class com.google.gwt.user.client.ui.Widget

eventsToSink

Fields inherited from class com.google.gwt.user.client.ui.UIObject

DEBUG_ID_PREFIX, MISSING_ELEMENT_ERROR, SETELEMENT_TWICE_ERROR

Constructor Summary

Constructors

Modifier	Constructor and Description
	FormPanel() Creates a new FormPanel.
protected	FormPanel(Element element) This constructor may be used by subclasses to explicitly use an existing element.
protected	FormPanel(Element element, boolean createIFrame) This constructor may be used by subclasses to explicitly use an existing element.
	FormPanel(NamedFrame frameTarget) Creates a FormPanel that targets a NamedFrame.
	FormPanel(java.lang.String target) Creates a new FormPanel.

Method Summary

Modifier and Type	Method and Description
void	addFormHandler(FormHandler handler) Deprecated. Use addSubmitCompleteHandler(com.google.gwt.user.client.ui.FormPanel.SubmitCompleteHandler) and addSubmitHandler(com.google.gwt.user.client.ui.FormPanel.SubmitHandler) instead
HandlerRegistration	addSubmitCompleteHandler(FormPanel.SubmitCompleteHandler handler) Adds a FormPanel.SubmitCompleteEvent handler.
HandlerRegistration	addSubmitHandler(FormPanel.SubmitHandler handler) Adds a FormPanel.SubmitEvent handler.
java.lang.String	getAction() Gets the 'action' associated with this form.
java.lang.String	getEncoding() Gets the encoding used for submitting this form.
java.lang.String	getMethod() Gets the HTTP method used for submitting this form.
(package private) Element	getSynthesizedIFrame()
java.lang.String	getTarget() Gets the form's 'target'.
protected void	onAttach() This method is called when a widget is attached to the browser's document.
protected void	onDetach() This method is called when a widget is detached from the browser's document.
boolean	onFormSubmit() Fired when a form is submitted.
void	onFrameLoad() Called when the target frame is done loading.
void	removeFormHandler(FormHandler handler) Deprecated. Use the HandlerRegistration.removeHandler() method on the object returned by and add*Handler method instead
void	reset() Resets the form, clearing all fields.
void	setAction(SafeUri url) Sets the 'action' associated with this form.
void	setAction(java.lang.String url) Sets the 'action' associated with this form.
void	setEncoding(java.lang.String encodingType) Sets the encoding used for submitting this form.
void	setMethod(java.lang.String method) Sets the HTTP method used for submitting this form.
void	submit() Submits the form.
static FormPanel	wrap(Element element) Creates a FormPanel that wraps an existing <form> element.
static FormPanel	wrap(Element element, boolean createIFrame) Creates a FormPanel that wraps an existing <form> element.

Methods inherited from class com.google.gwt.user.client.ui.SimplePanel

add, getContainerElement, getWidget, iterator, remove, setWidget, setWidget

Methods inherited from class com.google.gwt.user.client.ui.Panel

add, adopt, clear, doAttachChildren, doDetachChildren, orphan, remove

Methods inherited from class com.google.gwt.user.client.ui.Widget

addAttachHandler, addBitlessDomHandler, addDomHandler, addHandler, asWidget, asWidgetOrNull, createHandlerManager, delegateEvent, ensureHandlers, fireEvent, getHandlerCount, getHandlerManager, getLayoutData, getParent, isAttached, isOrWasAttached, onBrowserEvent, onLoad, onUnload, removeFromParent, replaceElement, setLayoutData, setParent, sinkEvents, unsinkEvents

Methods inherited from class com.google.gwt.user.client.ui.UIObject

addStyleDependentName, addStyleName, ensureDebugId, ensureDebugId, ensureDebugId, getAbsoluteLeft, getAbsoluteTop, getElement, getOffsetHeight, getOffsetWidth, getStyleElement, getStyleName, getStyleName, getStylePrimaryName, getStylePrimaryName, getTitle, isVisible, isVisible, onEnsureDebugId, removeStyleDependentName, removeStyleName, resolvePotentialElement, setElement, setElement, setHeight, setPixelSize, setSize, setStyleDependentName, setStyleName, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setTitle, setVisible, setVisible, setWidth, sinkBitlessEvent, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

ENCODING_MULTIPART

public static final java.lang.String ENCODING_MULTIPART

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

See Also:

Constant Field Values

ENCODING_URLENCODED

public static final java.lang.String ENCODING_URLENCODED

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

See Also:

Constant Field Values

METHOD_GET

public static final java.lang.String METHOD_GET

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

See Also:

Constant Field Values

METHOD_POST

public static final java.lang.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).

See Also:

Constant Field Values

Constructor Detail

FormPanel

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.

Tip:

The initial implementation of FormPanel specified that the server respond with a content-type of 'text/plain'. This has been intentionally changed to specify 'text/html' because 'text/plain' cannot be made to work properly on all browsers.

FormPanel

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

FormPanel

public FormPanel(java.lang.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

FormPanel

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

FormPanel

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

Method Detail

wrap

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 RootPanel.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

wrap

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 RootPanel.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

addFormHandler

@Deprecated
public void addFormHandler(FormHandler handler)

Deprecated. Use addSubmitCompleteHandler(com.google.gwt.user.client.ui.FormPanel.SubmitCompleteHandler) and addSubmitHandler(com.google.gwt.user.client.ui.FormPanel.SubmitHandler) instead

Description copied from interface: FiresFormEvents

Adds a handler interface to receive click events.

Specified by:

addFormHandler in interface FiresFormEvents

Parameters:

handler - the handler interface to add

addSubmitCompleteHandler

public HandlerRegistration addSubmitCompleteHandler(FormPanel.SubmitCompleteHandler handler)

Adds a FormPanel.SubmitCompleteEvent handler.

Parameters:

handler - the handler

Returns:

the handler registration used to remove the handler

addSubmitHandler

public HandlerRegistration addSubmitHandler(FormPanel.SubmitHandler handler)

Adds a FormPanel.SubmitEvent handler.

Parameters:

handler - the handler

Returns:

the handler registration used to remove the handler

getAction

public java.lang.String getAction()

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

Returns:

the form's action

getEncoding

public java.lang.String getEncoding()

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

Returns:

the form's encoding

getMethod

public java.lang.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

getTarget

public java.lang.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.

onFormSubmit

public boolean onFormSubmit()

Fired when a form is submitted.

Specified by:

onFormSubmit in interface com.google.gwt.user.client.ui.impl.FormPanelImplHost

Returns:

true if the form is submitted, false if canceled

onFrameLoad

public void onFrameLoad()

Description copied from interface: com.google.gwt.user.client.ui.impl.FormPanelImplHost

Called when the target frame is done loading.

Specified by:

onFrameLoad in interface com.google.gwt.user.client.ui.impl.FormPanelImplHost

removeFormHandler

@Deprecated
public void removeFormHandler(FormHandler handler)

Deprecated. Use the HandlerRegistration.removeHandler() method on the object returned by and add*Handler method instead

Description copied from interface: FiresFormEvents

Removes a previously added handler interface.

Specified by:

removeFormHandler in interface FiresFormEvents

Parameters:

handler - the handler interface to remove

reset

public void reset()

Resets the form, clearing all fields.

setAction

public void setAction(java.lang.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

setAction

public void setAction(SafeUri url)

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

Parameters:

url - the form's action

setEncoding

public void setEncoding(java.lang.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

setMethod

public void setMethod(java.lang.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

submit

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.

onAttach

protected void onAttach()

Description copied from class: Widget

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 Widget.onLoad() method or use Widget.addAttachHandler(com.google.gwt.event.logical.shared.AttachEvent.Handler).

It is strongly recommended that you override Widget.onLoad() or Widget.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.

Overrides:

onAttach in class Widget

See Also:

Widget.onLoad(), Widget.doAttachChildren()

onDetach

protected void onDetach()

Description copied from class: Widget

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 Widget.onUnload() method or use Widget.addAttachHandler(com.google.gwt.event.logical.shared.AttachEvent.Handler).

It is strongly recommended that you override Widget.onUnload() or Widget.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.

Overrides:

onDetach in class Widget

See Also:

Widget.onUnload(), Widget.doDetachChildren()

getSynthesizedIFrame

Element getSynthesizedIFrame()