|
||||||||||
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<T>
T
- The model object typepublic class Form<T>
Container for FormComponent
s (such as CheckBox
es, ListChoice
s or
TextField
s). Subclass this class to receive submit notifications through
onSubmit()
or nest multiple IFormSubmittingComponent
s if you want to vary submit
behavior. In the former case 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.
As a IFormSubmitListener
the form gets notified of listener requests in
onFormSubmitted()
. By default, the processing of this submit works like this:
FormComponent
s are notified of new input via
FormComponent.inputChanged()
Button
is contained in the component
hierarchy of this form and was clicked by the user:
IFormSubmitter
was found which
IFormSubmitter.getDefaultFormProcessing()
returns false
(default is true
), it's IFormSubmitter.onSubmit()
method will be called right away, thus all further
processing is skipped. This has the same effect as nesting a normal link in the form. validate()
to
execute form validation, hasError()
to find out whether validate() resulted in
validation errors, and updateFormComponentModels()
to update the models of nested form
components.process(IFormSubmitter)
, resulting in
all nested components being validated via FormComponent.validate()
. onError()
is called to allow clients to provide custom error handling code.FormComponent.updateModel()
. After that submit notification is delegated to the
IFormSubmitter.onSubmit()
(if just found) before calling onSubmit()
on this
form. Subclasses may override delegateSubmit(IFormSubmitter)
if they want a different
behavior.setMultiPart(boolean)
(although Wicket will try to automatically detect this for you).
Use this with 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
, i.e. for a form with id myform
in
MyPage.properties
:
myform.uploadTooLarge=You have uploaded a file that is over the allowed limit of 2MbForms 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.MethodMismatchResponse
Response when a submission method mismatch is detected |
static class |
Form.ValidationVisitor
Visitor used for validation |
Field Summary | |
---|---|
static String |
ENCTYPE_MULTIPART_FORM_DATA
|
static String |
METHOD_GET
Constant for specifying how a form is submitted, in this case using get. |
static 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_INITIALIZED, FLAG_REMOVING_FROM_HIERARCHY, FLAG_RESERVED1, FLAG_RESERVED2, FLAG_RESERVED3, FLAG_RESERVED4, FLAG_RESERVED5, FLAG_RESERVED8, PARENT_PATH, PATH_SEPARATOR, RENDER |
Fields inherited from interface org.apache.wicket.markup.html.form.IFormSubmitListener |
---|
INTERFACE |
Constructor Summary | |
---|---|
Form(String id)
Constructs a form with no validation. |
|
Form(String id,
IModel<T> 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. |
|
protected void |
callOnError(IFormSubmitter submitter)
Calls onError on this Form and any enabled and visible nested form, if the respective
Form actually has errors. |
|
void |
clearInput()
Clears the input from the form's nested children of type FormComponent . |
|
protected void |
delegateSubmit(IFormSubmitter 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. |
|
protected boolean |
encodeUrlInHiddenFields()
|
|
void |
error(String error,
Map<String,Object> args)
Registers an error feedback message for this component |
|
static Form<?> |
findForm(Component component)
|
|
IFormSubmitter |
findSubmittingButton()
Gets the IFormSubmittingComponent which submitted this form. |
|
protected CharSequence |
getActionUrl()
Generates the action url for the form |
|
IFormSubmittingComponent |
getDefaultButton()
Gets the default IFormSubmittingComponent. |
|
Bytes |
getFileMaxSize()
Gets maximum size for each file of an upload. |
|
Collection<IFormValidator> |
getFormValidators()
Gets all IFormValidator s added to this form |
|
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 String |
getInputNamePrefix()
Allows to customize input names of form components inside this form. |
|
CharSequence |
getJsForInterfaceUrl(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 String |
getMethod()
Gets the HTTP submit method that will appear in form markup. |
|
IModel<T> |
getModel()
Typesafe getter for the model |
|
T |
getModelObject()
Typesafe getter for the model's object |
|
Form<?> |
getRootForm()
Returns the root form or this, if this is the root form. |
|
static String |
getRootFormRelativeId(Component component)
Utility method to assemble an id to distinct form components from different nesting levels. |
|
protected boolean |
getStatelessHint()
Returns whether the component can be stateless. |
|
String |
getValidatorKeyPrefix()
Returns the prefix used when building validator keys. |
|
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 |
isMultiPart()
|
|
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 |
|
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 |
onBeforeRender()
Called just before a component is rendered only if the component is visible. |
|
protected void |
onComponentTag(ComponentTag tag)
Processes the component tag. |
|
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). |
|
protected void |
onFileUploadException(FileUploadException e,
Map<String,Object> model)
The default message may look like ".. |
|
void |
onFormSubmitted()
THIS METHOD IS NOT PART OF THE WICKET API. |
|
void |
onFormSubmitted(IFormSubmitter submitter)
THIS METHOD IS NOT PART OF THE WICKET API. |
|
protected Form.MethodMismatchResponse |
onMethodMismatch()
Called when a form has been submitted using a method differing from return value of getMethod() . |
|
protected void |
onSubmit()
Implemented by subclasses to deal with form submits. |
|
protected void |
onValidate()
Callback during the validation stage of the form |
|
protected void |
onValidateModelObjects()
Called after form components have updated their models. |
|
void |
process(IFormSubmitter submittingComponent)
Process the form. |
|
protected void |
registerJavaScriptNamespaces(IHeaderResponse response)
Produces javascript that registereds Wicket.Forms namespaces |
|
void |
remove(IFormValidator validator)
Removes a form validator from the form. |
|
void |
renderHead(IHeaderResponse response)
Render to the web response whatever the component wants to contribute to the head section. |
|
protected void |
renderPlaceholderTag(ComponentTag tag,
Response response)
Renders a placeholder tag for the component when it is invisible and Component.setOutputMarkupPlaceholderTag(boolean) has been called with true . |
|
void |
setDefaultButton(IFormSubmittingComponent submittingComponent)
Sets the default IFormSubmittingComponent. |
|
void |
setFileMaxSize(Bytes fileMaxSize)
Sets maximum size of each file in upload request. |
|
void |
setMaxSize(Bytes maxSize)
Sets the maximum size for uploads. |
|
void |
setModel(IModel<T> model)
Typesafe setter for the model |
|
void |
setModelObject(T object)
Typesafe setter for the model object |
|
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. |
|
|
visitFormComponents(IVisitor<FormComponent<?>,R> visitor)
Convenient and typesafe way to visit all the form components on a form. |
|
|
visitFormComponentsPostOrder(IVisitor<? extends FormComponent<?>,R> visitor)
Convenient and typesafe way to visit all the form components on a form postorder (deepest first) |
|
boolean |
wantSubmitOnNestedFormSubmit()
Whether this form wants to be submitted too if a nested form is submitted. |
|
boolean |
wantSubmitOnParentFormSubmit()
Whether this *nested* form wants to be submitted when parent form is submitted. |
|
protected void |
writeParamsAsHiddenFields(String[] params,
AppendingStringBuffer buffer)
|
Methods inherited from class org.apache.wicket.markup.html.WebMarkupContainer |
---|
getWebApplication, getWebPage, getWebRequest, getWebResponse, getWebSession |
Methods inherited from class org.apache.wicket.MarkupContainer |
---|
add, addOrReplace, autoAdd, contains, get, get, getAssociatedMarkup, getAssociatedMarkupStream, getMarkup, getMarkupType, internalAdd, internalInitialize, iterator, iterator, onAfterRenderChildren, onRender, remove, remove, removeAll, renderAll, renderAssociatedMarkup, renderNext, replace, setDefaultModel, size, swap, toString, toString, visitChildren, visitChildren, visitChildren, visitChildren |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final String ENCTYPE_MULTIPART_FORM_DATA
public static final String METHOD_GET
public static final String METHOD_POST
Constructor Detail |
---|
public Form(String id)
id
- See Componentpublic Form(String id, IModel<T> model)
id
- See Componentmodel
- See ComponentComponent.Component(String, IModel)
Method Detail |
---|
public void add(IFormValidator validator)
validator
- validator
IllegalArgumentException
- if validator is nullIFormValidator
public void remove(IFormValidator validator)
validator
- validator
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(String error, Map<String,Object> args)
error
- error messageargs
- argument replacement map for ${key} variablespublic final IFormSubmitter 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 Collection<IFormValidator> getFormValidators()
IFormValidator
s added to this form
IFormValidator
spublic final CharSequence getJsForInterfaceUrl(CharSequence url)
url
- The interface url that has to be stored in the hidden field and submitted
public final Bytes getMaxSize()
IApplicationSettings.getDefaultMaximumUploadSize()
is used.
public Bytes getFileMaxSize()
public Form<?> getRootForm()
public 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 final void onFormSubmitted()
onFormSubmitted
in interface IFormSubmitListener
onFormSubmitted(IFormSubmitter)
protected Form.MethodMismatchResponse onMethodMismatch()
getMethod()
. For example, someone can copy and paste the action url and invoke the
form using a GET
instead of the desired POST
. This method allows the user to
react to this situation.
public final void onFormSubmitted(IFormSubmitter submitter)
submitter
- listener that will receive form processing events, if null
the form will
attempt to locate onevalidate()
public boolean wantSubmitOnNestedFormSubmit()
public boolean wantSubmitOnParentFormSubmit()
true
by defaultpublic void process(IFormSubmitter submittingComponent)
See the class documentation for further details on the form processing
submittingComponent
- component responsible for submitting the form, or null
if none (eg
the form has been submitted via the enter key or javascript calling form.submit())for an easy way to process submitting component in the
default manner
protected void callOnError(IFormSubmitter submitter)
Form
and any enabled and visible nested form, if the respective
Form
actually has errors.
submitter
- 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 setFileMaxSize(Bytes fileMaxSize)
fileMaxSize
- public 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 <R> R visitFormComponents(IVisitor<FormComponent<?>,R> visitor)
R
- return object typevisitor
- The visitor interface to call
public final <R> R visitFormComponentsPostOrder(IVisitor<? extends FormComponent<?>,R> visitor)
R
- Return object typevisitor
- The visitor interface to call
protected void appendDefaultButtonField(MarkupStream markupStream, ComponentTag openTag)
markupStream
- The markup streamopenTag
- The open tag for the bodyprotected void beforeUpdateFormComponentModels()
protected void delegateSubmit(IFormSubmitter 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 onSubmitBefore/AfterForm methods are called appropriately..
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)public final String getHiddenFieldId()
protected String getMethod()
protected boolean getStatelessHint()
Component
getStatelessHint
in class Component
Component.getStatelessHint()
public boolean isMultiPart()
protected boolean handleMultiPart()
FileUploadField
s on this form
protected void onFileUploadException(FileUploadException e, Map<String,Object> model)
Don't forget to call super.onFileUploadException(e, model) at the end of your method.
e
- model
- protected void internalOnModelChanged()
Component
Called anytime a model is changed via setModel or setModelObject.
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 CharSequence getActionUrl()
protected void renderPlaceholderTag(ComponentTag tag, Response response)
Component
Component.setOutputMarkupPlaceholderTag(boolean)
has been called with true
.
renderPlaceholderTag
in class Component
tag
- component tagresponse
- responseComponent.renderPlaceholderTag(org.apache.wicket.markup.ComponentTag,
org.apache.wicket.request.Response)
protected boolean encodeUrlInHiddenFields()
public void onComponentTagBody(MarkupStream markupStream, ComponentTag openTag)
onComponentTagBody
in class MarkupContainer
markupStream
- The markup streamopenTag
- The open tag for the bodyprotected void writeParamsAsHiddenFields(String[] params, AppendingStringBuffer buffer)
params
- buffer
- protected void onDetach()
Component
onDetach
in class Component
Component.onDetach()
protected void onError()
protected void onBeforeRender()
Component
NOTE: If you override this, you *must* call super.onBeforeRender() within
your implementation.
Because this method is responsible for cascading Component.onBeforeRender()
call to its
children it is strongly recommended that super call is made at the end of the override.
onBeforeRender
in class Component
MarkupContainer.addOrReplace(Component...)
protected void onSubmit()
protected final void updateFormComponentModels()
FormComponent.updateModel()
protected final void validate()
NOTE: in most cases, custom validations on the form can be achieved using an IFormValidator that can be added using addValidator().
protected void onValidate()
protected void onValidateModelObjects()
protected final void validateComponents()
protected final void validateFormValidator(IFormValidator validator)
validator
- protected final void validateFormValidators()
IFormValidator
s.
protected String getInputNamePrefix()
public final IModel<T> getModel()
IGenericComponent
getModel
in interface IGenericComponent<T>
public final void setModel(IModel<T> model)
IGenericComponent
setModel
in interface IGenericComponent<T>
model
- the new modelpublic final T getModelObject()
IGenericComponent
getModelObject
in interface IGenericComponent<T>
public final void setModelObject(T object)
IGenericComponent
setModelObject
in interface IGenericComponent<T>
object
- the new model objectpublic static Form<?> findForm(Component component)
component
-
public void renderHead(IHeaderResponse response)
renderHead
in interface IHeaderContributor
renderHead
in class Component
response
- Response objectprotected void registerJavaScriptNamespaces(IHeaderResponse response)
response
- public static String getRootFormRelativeId(Component component)
component
-
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |