|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object org.apache.wicket.Component org.apache.wicket.MarkupContainer org.apache.wicket.markup.html.WebMarkupContainer org.apache.wicket.markup.html.form.Form
public class Form
Base class for forms. To implement a form, subclass this class, add FormComponents (such as CheckBoxes, ListChoices or TextFields) to the form. You can nest multiple IFormSubmittingComponents if you want to vary submit behavior. However, it is not necessary to use any of Wicket's classes (such as Button or SubmitLink), just putting e.g. <input type="submit" value="go"> suffices.
By default, the processing of a form works like this:
FileUploadField
components. You can attach
multiple FileUploadField components for multiple file uploads.
In case of an upload error two resource keys are available to specify error messages: uploadTooLarge and uploadFailed ie in [page].properties [form-id].uploadTooLarge=You have uploaded a file that is over the allowed limit of 2Mb
If you want to have multiple IFormSubmittingComponents which submit the same form, simply put two or more IFormSubmittingComponents somewhere in the hierarchy of components that are children of the form.
To get form components to persist their values for users via cookies, simply call setPersistent(true) on each component.
Forms can be nested. You can put a form in another form. Since HTML doesn't allow nested <form> tags, the inner forms will be rendered using the <div> tag. You have to submit the inner forms using explicit components (like Button or SubmitLink), you can't rely on implicit submit behavior (by using just <input type="submit"> that is not attached to a component).
When a nested form is submitted, the user entered values in outer (parent) forms are preserved and only the fields in the submitted form are validated.
Nested Class Summary | |
---|---|
static class |
Form.ValidationVisitor
Visitor used for validation |
Nested classes/interfaces inherited from class org.apache.wicket.Component |
---|
Component.ComponentModelChange, Component.EnabledChange, Component.IVisitor, Component.VisibilityChange |
Field Summary | |
---|---|
static java.lang.String |
METHOD_GET
Constant for specifying how a form is submitted, in this case using get. |
static java.lang.String |
METHOD_POST
Constant for specifying how a form is submitted, in this case using post. |
Fields inherited from class org.apache.wicket.Component |
---|
ENABLE, FLAG_RESERVED1, FLAG_RESERVED2, FLAG_RESERVED3, FLAG_RESERVED4, FLAG_RESERVED5, FLAG_RESERVED6, FLAG_RESERVED7, FLAG_RESERVED8, PATH_SEPARATOR, RENDER |
Fields inherited from interface org.apache.wicket.markup.html.form.IFormSubmitListener |
---|
INTERFACE |
Constructor Summary | |
---|---|
Form(java.lang.String id)
Constructs a form with no validation. |
|
Form(java.lang.String id,
IModel model)
|
Method Summary | |
---|---|
void |
add(IFormValidator validator)
Adds a form validator to the form. |
protected void |
appendDefaultButtonField(MarkupStream markupStream,
ComponentTag openTag)
If a default IFormSubmittingComponent was set on this form, this method will be called to render an extra field with an invisible style so that pressing enter in one of the textfields will do a form submit using this component. |
protected void |
beforeUpdateFormComponentModels()
Template method to allow clients to do any processing (like recording the current model so that, in case onSubmit does further validation, the model can be rolled back) before the actual updating of form component models is done. |
void |
clearInput()
Clears the input from the form's nested children of type FormComponent . |
protected void |
delegateSubmit(IFormSubmittingComponent submittingComponent)
Called (by the default implementation of 'process') when all fields validated, the form was updated and it's data was allowed to be persisted. |
void |
error(java.lang.String error,
java.util.Map args)
/** Registers an error feedback message for this component |
IFormSubmittingComponent |
findSubmittingButton()
Gets the IFormSubmittingComponent which submitted this form. |
IFormSubmittingComponent |
getDefaultButton()
Gets the default IFormSubmittingComponent. |
java.util.Collection |
getFormValidators()
Gets all IFormValidator s added to this form |
protected java.lang.String |
getHiddenFieldId()
Returns the HiddenFieldId which will be used as the name and id property of the hiddenfield that is generated for event dispatches. |
protected java.lang.String |
getInputNamePrefix()
Allows to customize input names of form components inside this form. |
protected java.lang.String |
getJavascriptId()
Deprecated. use Component.getMarkupId() |
java.lang.CharSequence |
getJsForInterfaceUrl(java.lang.CharSequence url)
This generates a piece of javascript code that sets the url in the special hidden field and submits the form. |
Bytes |
getMaxSize()
Gets the maximum size for uploads. |
protected java.lang.String |
getMethod()
Gets the HTTP submit method that will appear in form markup. |
Form |
getRootForm()
Returns the root form or this, if this is the root form. |
protected boolean |
getStatelessHint()
Returns whether the component can be stateless. |
java.lang.String |
getValidatorKeyPrefix()
Returns the prefix used when building validator keys. |
protected IValuePersister |
getValuePersister()
Gets the form component persistence manager; it is lazy loaded. |
protected boolean |
handleMultiPart()
Handles multi-part processing of the submitted data. |
boolean |
hasError()
Gets whether the current form has any error registered. |
protected void |
internalOnModelChanged()
THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. |
boolean |
isRootForm()
Returns whether the form is a root form, which means that there's no other form in it's parent hierarchy. |
boolean |
isSubmitted()
Checks if this form has been submitted during the current request |
boolean |
isVersioned()
Method made final because we want to ensure users call setVersioned. |
void |
loadPersistentFormComponentValues()
THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. |
protected void |
markFormComponentsInvalid()
Mark each form component on this form invalid. |
protected void |
markFormComponentsValid()
Mark each form component on this form and on nested forms valid. |
protected void |
onComponentTag(ComponentTag tag)
Processes the component tag. |
protected void |
onComponentTagBody(MarkupStream markupStream,
ComponentTag openTag)
Append an additional hidden input tag to support anchor tags that can submit a form. |
protected void |
onDetach()
Called to allow a component to detach resources after use. |
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 |
onRender(MarkupStream markupStream)
Renders this component. |
protected void |
onSubmit()
Implemented by subclasses to deal with form submits. |
boolean |
process()
Process the form. |
void |
remove(IFormValidator validator)
Removes a form validator from the form. |
void |
removePersistentFormComponentValues(boolean disablePersistence)
Removes already persisted data for all FormComponent children and disable persistence for the same components. |
void |
setDefaultButton(IFormSubmittingComponent submittingComponent)
Sets the default IFormSubmittingComponent. |
void |
setMaxSize(Bytes maxSize)
Sets the maximum size for uploads. |
void |
setMultiPart(boolean multiPart)
Set to true to use enctype='multipart/form-data', and to process file uploads by default multiPart = false |
Component |
setVersioned(boolean isVersioned)
|
protected void |
updateFormComponentModels()
Update the model of all components on this form and nested forms using the fields that were sent with the current request. |
protected void |
validate()
Validates the form by checking required fields, converting raw input and running validators for every form component, and last running global form validators. |
protected void |
validateComponents()
Triggers type conversion on form components |
protected void |
validateFormValidator(IFormValidator validator)
Validates form with the given form validator |
protected void |
validateFormValidators()
Triggers any added IFormValidator s. |
void |
visitFormComponents(FormComponent.IVisitor visitor)
Convenient and typesafe way to visit all the form components on a form. |
void |
visitFormComponentsPostOrder(FormComponent.IVisitor visitor)
Convenient and typesafe way to visit all the form components on a form postorder (deepest first) |
protected void |
writeParamsAsHiddenFields(java.lang.String[] params,
AppendingStringBuffer buffer)
|
Methods inherited from class org.apache.wicket.markup.html.WebMarkupContainer |
---|
getMarkupType, getWebPage |
Methods inherited from class org.apache.wicket.MarkupContainer |
---|
add, addOrReplace, autoAdd, autoAdd, contains, findMarkupStream, get, getAssociatedMarkupStream, getMarkupStream, hasAssociatedMarkup, internalAdd, isTransparentResolver, iterator, iterator, newMarkupResourceStream, remove, remove, removeAll, renderAll, renderAssociatedMarkup, renderComponentTagBody, replace, setMarkupStream, setModel, size, toString, toString, visitChildren, visitChildren |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final java.lang.String METHOD_GET
public static final java.lang.String METHOD_POST
Constructor Detail |
---|
public Form(java.lang.String id)
id
- See Componentpublic Form(java.lang.String id, IModel model)
id
- See Componentmodel
- See ComponentComponent.Component(String, IModel)
Method Detail |
---|
public void add(IFormValidator validator)
validator
- validator
java.lang.IllegalArgumentException
- if validator is nullIFormValidator
,
IValidatorAddListener
public void remove(IFormValidator validator)
validator
- validator
java.lang.IllegalArgumentException
- if validator is nullIFormValidator
public final void clearInput()
FormComponent
. This method
is typically called when a form needs to be reset.
public final void error(java.lang.String error, java.util.Map args)
error
- error messageargs
- argument replacement map for ${key} variablespublic final IFormSubmittingComponent findSubmittingButton()
public final IFormSubmittingComponent getDefaultButton()
WARNING: note that this is a best effort only. Unfortunately having a 'default' button in a form is ill defined in the standards, and of course IE has it's own way of doing things.
There can be only one default submit component per form hierarchy. So if you want to get the default component on a nested form, it will actually delegate the call to root form.
public final java.util.Collection getFormValidators()
IFormValidator
s added to this form
IFormValidator
spublic final java.lang.CharSequence getJsForInterfaceUrl(java.lang.CharSequence url)
url
- The interface url that has to be stored in the hidden field and submitted
public Bytes getMaxSize()
IApplicationSettings.getDefaultMaximumUploadSize()
is used.
public Form getRootForm()
public java.lang.String getValidatorKeyPrefix()
This can be useful when different designs are used for a form. In a form where error messages are displayed next to their respective form components as opposed to at the top of the form, the ${label} attribute is of little use and only causes redundant information to appear in the message. Forms like these can return the "short" (or any other string) validator prefix and declare key: short.Required=required to override the longer message which is usually declared like this: Required=${label} is a required field
Returned prefix will be used for all form components. The prefix can also be overridden on
form component level by overriding FormComponent.getValidatorKeyPrefix()
public final boolean hasError()
public boolean isRootForm()
public final boolean isSubmitted()
public boolean isVersioned()
isVersioned
in class Component
Component.isVersioned()
public final void loadPersistentFormComponentValues()
Retrieves FormComponent values related to the page using the persister and assign the values to the FormComponent. Thus initializing them.
public final void onFormSubmitted()
onFormSubmitted
in interface IFormSubmitListener
validate()
public boolean process()
See the class documentation for further details on the form processing
public void removePersistentFormComponentValues(boolean disablePersistence)
disablePersistence
- if true, disable persistence for all FormComponents on that page. If false, it
will remain unchanged.Page.removePersistedFormData(Class, boolean)
public final void setDefaultButton(IFormSubmittingComponent submittingComponent)
WARNING: note that this is a best effort only. Unfortunately having a 'default' button in a form is ill defined in the standards, and of course IE has it's own way of doing things.
There can be only one default button per form hierarchy. So if you set default button on a nested form, it will actually delegate the call to root form.
submittingComponent
- The component to set as the default submitting component, or null when you want to
'unset' any previously set default componentpublic void setMaxSize(Bytes maxSize)
IApplicationSettings.getDefaultMaximumUploadSize()
is used.
maxSize
- The maximum sizepublic void setMultiPart(boolean multiPart)
multiPart
- whether this form should behave as a multipart formpublic final Component setVersioned(boolean isVersioned)
setVersioned
in class Component
isVersioned
- True to turn on versioning for this component, false to turn it off for this
component and any children.
Component.setVersioned(boolean)
public final void visitFormComponents(FormComponent.IVisitor visitor)
visitor
- The visitor interface to callpublic final void visitFormComponentsPostOrder(FormComponent.IVisitor visitor)
visitor
- The visitor interface to callprotected void appendDefaultButtonField(MarkupStream markupStream, ComponentTag openTag)
markupStream
- The markup streamopenTag
- The open tag for the bodyprotected void beforeUpdateFormComponentModels()
protected void delegateSubmit(IFormSubmittingComponent submittingComponent)
This implementation first finds out whether the form processing was triggered by a nested IFormSubmittingComponent of this form. If that is the case, that component's onSubmit is called first.
Regardless of whether a submitting component was found, the form's onSubmit method is called next.
submittingComponent
- the component that triggered this form processing, or null if the processing was
triggered by something else (like a non-Wicket submit button or a javascript
execution)protected final java.lang.String getHiddenFieldId()
protected final java.lang.String getJavascriptId()
Component.getMarkupId()
protected java.lang.String getMethod()
protected boolean getStatelessHint()
Component
getStatelessHint
in class Component
protected IValuePersister getValuePersister()
protected boolean handleMultiPart()
FileUploadField
s on this form
protected void internalOnModelChanged()
Component
internalOnModelChanged
in class Component
Component.internalOnModelChanged()
protected final void markFormComponentsInvalid()
protected final void markFormComponentsValid()
protected void onComponentTag(ComponentTag tag)
Component
onComponentTag
in class Component
tag
- Tag to modifyComponent.onComponentTag(ComponentTag)
protected void onComponentTagBody(MarkupStream markupStream, ComponentTag openTag)
onComponentTagBody
in class MarkupContainer
markupStream
- The markup streamopenTag
- The open tag for the bodyprotected void writeParamsAsHiddenFields(java.lang.String[] params, AppendingStringBuffer buffer)
params
- buffer
- protected void onDetach()
Component
onDetach
in class Component
Component.onDetach()
protected void onError()
protected void onRender(MarkupStream markupStream)
MarkupContainer
onRender
in class MarkupContainer
Component.onRender(MarkupStream)
protected void onSubmit()
protected final void updateFormComponentModels()
FormComponent.updateModel()
protected void validate()
NOTE: in most cases, custom validations on the form can be achieved using an IFormValidator that can be added using addValidator().
protected final void validateComponents()
protected final void validateFormValidator(IFormValidator validator)
validator
- protected final void validateFormValidators()
IFormValidator
s.
protected java.lang.String getInputNamePrefix()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |