In contrast to classic forms, wizards have more than one form view page. Therefore, there are various actions instead of one single submit action:
Finish and cancel actions can be triggered by request parameters, named PARAM_FINISH ("_finish") and PARAM_CANCEL ("_cancel"), ignoring parameter values to allow for HTML buttons. The target page for page changes can be specified by PARAM_TARGET, appending the page number to the parameter name (e.g. "_target1"). The action parameters are recognized when triggered by image buttons too (via "_finish.x", "_abort.x", or "_target1.x").
The current page number will be stored in the session. It can also be specified as request parameter PARAM_PAGE, to properly handle usage of the back button in a browser: In this case, a submission always contains the correct page number, even if the user submitted from an old view.
The page can only be changed if it validates correctly, except if a "dirty back" or "dirty forward" is allowed. At finish, all pages get validated again to guarantee a consistent state.
Note that a validator's default validate method is not executed when using
this class! Rather, the validatePage implementation should call
special validateXXX methods that the validator needs to provide,
validating certain pieces of the object. These can be combined to validate
the elements of individual pages.
Note: Page numbering starts with 0, to be able to pass an array consisting of the corresponding view names to the "pages" bean property.
| Field Summary | |
|---|---|
| static String |
Parameter triggering the cancel action. |
| static String |
Parameter triggering the finish action. |
| static String |
Parameter specifying the current page as value. |
| static String |
Parameter specifying the target page, appending the page number to the name. |
| Fields inherited from org.springframework.context.supportApplicationObjectSupport |
|---|
| Fields inherited from org.springframework.web.servlet.mvcBaseCommandController |
|---|
| Fields inherited from org.springframework.web.servlet.supportWebContentGenerator |
|---|
| Constructor Summary |
|---|
|
Create a new AbstractWizardFormController. |
| Method Summary | |
|---|---|
| protected int |
Return the current page number. |
| protected int |
Return the initial page of the wizard, i.e. |
| protected int |
Return the initial page of the wizard, i.e. |
| String |
Return the name of the page attribute in the model. |
| protected int |
Return the number of wizard pages. |
| protected int |
Return the page count for this wizard form controller. |
| String[] |
Return the wizard pages, i.e. |
| protected String |
Return the name of the HttpSession attribute that holds the page object for this wizard form controller. |
| protected String |
Return the name of the HttpSession attribute that holds the page object for this wizard form controller. |
| protected int |
Return the target page specified in the request. |
| protected int |
Return the target page specified in the request. |
| protected String |
Return the name of the view for the specified page of this wizard form controller. |
| protected ModelAndView |
Handle an invalid submit request, e.g. |
| boolean |
Return whether "dirty back" is allowed. |
| boolean |
Return whether "dirty forward" is allowed. |
| protected boolean |
No description provided. |
| protected boolean |
Determine whether the incoming request is a request to cancel the processing of the current form. |
| protected boolean |
No description provided. |
| protected boolean |
Determine whether the incoming request is a request to finish the processing of the current form. |
| protected boolean |
Consider an explicit finish or cancel request as a form submission too. |
| protected void |
Calls page-specific onBindAndValidate method. |
| protected void |
Callback for custom post-processing in terms of binding and validation. |
| protected void |
Post-process the given page after binding and validation, potentially updating its command object. |
| protected ModelAndView |
Template method for processing the cancel action of this wizard. |
| protected ModelAndView |
Template method for processing the final action of this wizard. |
| protected ModelAndView |
Apply wizard workflow: finish, cancel, page change. |
| protected Map |
Calls page-specific referenceData method. |
| protected Map |
Create a reference data map for the given request, consisting of bean name/bean instance pairs as expected by ModelAndView. |
| protected Map |
Create a reference data map for the given request, consisting of bean name/bean instance pairs as expected by ModelAndView. |
| void |
Set if "dirty back" is allowed, i.e. |
| void |
Set if "dirty forward" is allowed, i.e. |
| void |
Set the name of the page attribute in the model, containing an Integer with the current page number. |
| void |
Set the wizard pages, i.e. |
| protected ModelAndView |
Show first page as form view. |
| protected ModelAndView |
Prepare the form model and view, including reference and error data, for the given page. |
| protected void |
Template method for custom validation logic for individual pages. |
| protected void |
Template method for custom validation logic for individual pages. |
| Methods inherited from org.springframework.web.servlet.mvcAbstractController |
|---|
| Methods inherited from org.springframework.contextApplicationContextAware |
|---|
| Methods inherited from org.springframework.context.supportApplicationObjectSupport |
|---|
| Methods inherited from org.springframework.web.servlet.mvcController |
|---|
| Methods inherited from java.langObject |
|---|
| Methods inherited from org.springframework.web.context.supportWebApplicationObjectSupport |
|---|
public AbstractWizardFormController
(
)
"sessionForm" is automatically turned on, "validateOnBinding" turned off, and "cacheSeconds" set to 0 by the base class (-> no caching for all form controllers).
The default implementation checks the page session attribute. Subclasses can override this for customized page determination.
getInitialPage(HttpServletRequest).
protected
int
getPageCount
(
)
Note that a concrete wizard form controller might override
getPageCount(HttpServletRequest, Object) to determine
the page count dynamically. The default implementation of that extended
getPageCount variant returns the static page count as
determined by this getPageCount() method.
getPageCount().
Can be overridden to dynamically adapt the page count.
Note that a concrete wizard form controller might override
getViewName(HttpServletRequest, Object, int) to
determine the view name for each page dynamically.
Default implementation delegates to the getPageSessionAttributeName
version without arguments.
Default is an internal name, of no relevance to applications, as the form session attribute is not usually accessed directly. Can be overridden to use an application-specific attribute name, which allows other code to access the session attribute directly.
protected
int
getTargetPage
(
HttpServletRequest
request,
Object
command,
Errors
errors,
int
currentPage
)
Default implementation delegates to
getTargetPage(HttpServletRequest, int).
Subclasses can override this for customized target page determination.
Default implementation examines "_target" parameter (e.g. "_target1"). Subclasses can override this for customized target page determination.
getPages() array.
Can be overridden to dynamically switch the page view or to return view names for dynamically defined pages.
protected
ModelAndView
handleInvalidSubmit
(
HttpServletRequest
request,
HttpServletResponse
response
)
Default implementation for wizard form controllers simply shows the initial page of a new wizard form. If you want to show some "invalid submit" message, you need to override this method.
public
boolean
isAllowDirtyBack
(
)
public
boolean
isAllowDirtyForward
(
)
By default, this method returns true if a parameter
matching the "_cancel" key is present in the request, otherwise it
returns false. Subclasses may override this method
to provide custom logic to detect a cancel request.
The parameter is recognized both when sent as a plain parameter ("_cancel") or when triggered by an image button ("_cancel.x").
By default, this method returns true if a parameter
matching the "_finish" key is present in the request, otherwise it
returns false. Subclasses may override this method
to provide custom logic to detect a finish request.
The parameter is recognized both when sent as a plain parameter ("_finish") or when triggered by an image button ("_finish.x").
protected
void
onBindAndValidate
(
HttpServletRequest
request,
Object
command,
BindException
errors
)
protected
void
onBindAndValidate
(
HttpServletRequest
request,
Object
command,
BindException
errors,
int
page
)
Note: AbstractWizardFormController does not perform standand validation on binding but rather applies page-specific validation on processing the form submission.
protected
void
postProcessPage
(
HttpServletRequest
request,
Object
command,
Errors
errors,
int
page
)
Only invoked when displaying another page or the same page again, not when finishing or cancelling.
protected
ModelAndView
processCancel
(
HttpServletRequest
request,
HttpServletResponse
response,
Object
command,
BindException
errors
)
Default implementation throws a ServletException, saying that a cancel operation is not supported by this controller. Thus, you do not need to implement this template method if you do not support a cancel operation.
Call errors.getModel() to populate the ModelAndView model
with the command and the Errors instance, under the specified command name,
as expected by the "spring:bind" tag.
protected
ModelAndView
processFinish
(
HttpServletRequest
request,
HttpServletResponse
response,
Object
command,
BindException
errors
)
Call errors.getModel() to populate the ModelAndView model
with the command and the Errors instance, under the specified command name,
as expected by the "spring:bind" tag.
You can call the showPage method to return back to the wizard,
in case of last-minute validation errors having been found that you would
like to present to the user within the original wizard form.
protected
ModelAndView
processFormSubmission
(
HttpServletRequest
request,
HttpServletResponse
response,
Object
command,
BindException
errors
)
protected
Map
referenceData
(
HttpServletRequest
request,
Object
command,
Errors
errors,
int
page
)
Default implementation delegates to referenceData(HttpServletRequest, int). Subclasses can override this to set reference data used in the view.
Default implementation returns null. Subclasses can override this to set reference data used in the view.
public
void
setAllowDirtyBack
(
boolean
allowDirtyBack
)
public
void
setAllowDirtyForward
(
boolean
allowDirtyForward
)
This will be necessary for single views rendering multiple view pages. It also allows for specifying the optional "_page" parameter.
protected
ModelAndView
showForm
(
HttpServletRequest
request,
HttpServletResponse
response,
BindException
errors
)
protected
ModelAndView
showPage
(
HttpServletRequest
request,
BindException
errors,
int
page
)
processFinish implementations,
to show the corresponding page in case of validation errors. validatePage(command, errors, page).
Implementations will typically call fine-granular validateXXX
methods of this instance's Validator, combining them to validation of the
corresponding pages. The Validator's default validate method
will not be called by a wizard form controller!
Implementations will typically call fine-granular validateXXX methods of this
instance's validator, combining them to validation of the corresponding pages.
The validator's default validate method will not be called by a
wizard form controller!