wicket.markup.html.form
Class Form

java.lang.Object
  wicket.Component
      wicket.MarkupContainer
          wicket.markup.html.WebMarkupContainer
              wicket.markup.html.form.Form

All Implemented Interfaces:

IFeedbackBoundary, IFormSubmitListener, IRequestListener, java.io.Serializable

Direct Known Subclasses:

UploadForm

public abstract class Form

extends WebMarkupContainer

implements IFormSubmitListener, IFeedbackBoundary

Base class for forms. To implement a form, subclass this class, add FormComponents (such as CheckBoxes, ListChoices or TextFields) to the form and provide an implementation of handleValidSubmit(). The handleValidSubmit() method will be called by validate() when the form passes validation. If your form has only one button, there is nothing else to do. However, if you want to have multiple buttons which submit the same form, simply put two or more button components somewhere in the hierarchy of components that are children of the form. Forms which have two or more buttons do not automatically validate themselves via validate(). Instead, they determine which Button submitted the form and call that Button's onSubmit() method. In any onSubmit() method where you want to attempt to validate the form and update models, simply call validate().

If you want to do something when validation errors occur you can override onError(), but if you do, you probably will want to call super.onError() to get the default handling to occur.

To get form components to persist their values for users via cookies, simply call setPersistent(true) on the form component.

Author:

Jonathan Locke, Juergen Donnerstag, Eelco Hillenius

See Also:

Serialized Form

Nested Class Summary

Nested classes inherited from class wicket.Component

Component.ComponentModelChange, Component.IVisitor, Component.VisibilityChange

Field Summary

Fields inherited from class wicket.Component

FLAG_RESERVED1, FLAG_RESERVED2, FLAG_RESERVED3, FLAG_RESERVED4

Constructor Summary

Form(java.lang.String id)
Constructs a form with no validation.

Form(java.lang.String id, IFeedback feedback)

Form(java.lang.String id, IModel model, IFeedback feedback)

Method Summary

IFormValidationStrategy	getValidationStrategy() Gets the strategy to be used for form validation
protected IValuePersister	getValuePersister() Gets the form component persistence manager; it is lazy loaded.
protected void	internalOnModelChanged() THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
void	loadPersistentFormComponentValues() THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
protected void	onComponentTag(ComponentTag tag) Processes the component tag.
protected void	onError() Method to override if you want to do something special when an error occurs (other than simply displaying validation errors).
void	onFormSubmitted() THIS METHOD IS NOT PART OF THE WICKET API.
protected void	onSubmit() Implemented by subclasses to deal with form submits.
protected void	onValidate() Called when a form that has been submitted needs to be validated.
void	removePersistentFormComponentValues(boolean disablePersistence) Removes already persisted data for all FormComponent childs and disable persistence for the same components.
void	setVersioned(boolean isVersioned)
protected boolean	validate() Validates the form and updates the models of form components.
protected void	visitFormComponents(FormComponent.IVisitor visitor) Convenient and typesafe way to visit all the form components on a form

Methods inherited from class wicket.markup.html.WebMarkupContainer

getMarkupType, onRender

Methods inherited from class wicket.MarkupContainer

add, autoAdd, contains, findMarkupStream, get, getMarkupStream, internalAdd, internalBeginRequest, internalEndRequest, iterator, onComponentTagBody, remove, removeAll, renderAssociatedMarkup, renderComponentTagBody, replace, setMarkupStream, setModel, size, toString, toString, visitChildren, visitChildren

Methods inherited from class wicket.Component

add, addStateChange, checkComponentTag, checkComponentTagAttribute, debug, detachModel, error, exceptionMessage, fatal, findPage, findParent, findParentWithAssociatedMarkup, getApplication, getApplicationPages, getApplicationSettings, getClassRelativePath, getConverter, getEscapeModelStrings, getFeedbackMessage, getFlag, getId, getLocale, getLocalizer, getModel, getModelObject, getModelObjectAsString, getPage, getPageFactory, getPageRelativePath, getParent, getPath, getRenderBodyOnly, getRequest, getRequestCycle, getResource, getResponse, getSession, getString, getString, getString, getStyle, hasErrorMessage, hasFeedbackMessage, info, initModel, internalOnBeginRequest, internalOnEndRequest, internalOnModelChanging, isAncestorOf, isVersioned, isVisible, isVisibleInHierarchy, modelChanged, modelChanging, newPage, newPage, onBeginRequest, onEndRequest, onModelChanged, onModelChanging, onSessionAttach, redirectTo, remove, render, renderComponent, renderComponentTag, rendered, replaceComponentTagBody, sameRootModel, sameRootModel, setFlag, setModelObject, setRedirect, setRenderBodyOnly, setResponsePage, setShouldEscapeModelStrings, setVisible, urlFor, visitParents, warn

Methods inherited from class java.lang.Object

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

Constructor Detail

Form

public Form(java.lang.String id)

Constructs a form with no validation.

Parameters:

id - See Component

Form

public Form(java.lang.String id,
            IFeedback feedback)

Parameters:

id - See Component

feedback - Interface to a component that can handle/display validation errors

See Also:

Component.Component(String)

Form

public Form(java.lang.String id,
            IModel model,
            IFeedback feedback)

Parameters:

id - See Component

model - See Component

feedback - Interface to a component that can handle/display validation errors

See Also:

Component.Component(String, IModel)

Method Detail

getValidationStrategy

public IFormValidationStrategy getValidationStrategy()

Gets the strategy to be used for form validation

Returns:

The strategy to be used for validating this form

loadPersistentFormComponentValues

public final void loadPersistentFormComponentValues()

THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT CALL IT.

Retrieves FormComponent values related to the page using the persister and assign the values to the FormComponent. Thus initializing them.

onFormSubmitted

public void onFormSubmitted()

THIS METHOD IS NOT PART OF THE WICKET API. DO NOT ATTEMPT TO OVERRIDE OR CALL IT. Handles form submissions. By default, this method simply calls validate() to validate the form and update the model if there is only one button. If there is more than one button, it calls the onClick() method for the button which submitted the form.

Specified by:

onFormSubmitted in interface IFormSubmitListener

See Also:

validate()

removePersistentFormComponentValues

public void removePersistentFormComponentValues(boolean disablePersistence)

Removes already persisted data for all FormComponent childs and disable persistence for the same components.

Parameters:

disablePersistence - if true, disable persistence for all FormComponents on that page. If false, it will remain unchanged.

See Also:

Page.removePersistedFormData(Class, boolean)

setVersioned

public void setVersioned(boolean isVersioned)

Overrides:

setVersioned in class Component

Parameters:

isVersioned - True to turn on versioning for this component, false to turn it off for this component and any children.

See Also:

Component.setVersioned(boolean)

getValuePersister

protected IValuePersister getValuePersister()

Gets the form component persistence manager; it is lazy loaded.

Returns:

The form component value persister

onComponentTag

protected void onComponentTag(ComponentTag tag)

Description copied from class: Component

Processes the component tag.

Overrides:

onComponentTag in class Component

Parameters:

tag - Tag to modify

See Also:

Component.onComponentTag(ComponentTag)

onError

protected void onError()

Method to override if you want to do something special when an error occurs (other than simply displaying validation errors).

internalOnModelChanged

protected void internalOnModelChanged()

Description copied from class: Component

THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT CALL OR OVERRIDE. Called anytime a model is changed via setModel or setModelObject.

Overrides:

internalOnModelChanged in class Component

See Also:

Component.internalOnModelChanged()

onSubmit

protected void onSubmit()

Implemented by subclasses to deal with form submits.

onValidate

protected void onValidate()

Called when a form that has been submitted needs to be validated.

validate

protected final boolean validate()

Validates the form and updates the models of form components. If the form validates successfully, handleValidSubmit() is called. If not, handleErrors() is called.

Returns:

True if the form validated

See Also:

onSubmit(), onError()

visitFormComponents

protected void visitFormComponents(FormComponent.IVisitor visitor)

Convenient and typesafe way to visit all the form components on a form

Parameters:

visitor - The visitor interface to call