[Springframework-developer] Documentation for AbstractWizardFormController

[jez h. <je...@in...>]

Hi there everyone.

First of all, great work on Spring. I've just started using it and it has=
 made my life a lot easier.

Having spent a few hours writing a wizard, I have come up with some docum=
entation for the AbstractWizardFormController (see below). Would you cons=
ider including this in your online reference manual, in section 12.3.4 (w=
hich currently lists WizardFormController instead of AbstractWizardFormCo=
ntroller) ?

With all best wishes,

Jez Humble
Director,
Urban Guru Ltd
http://www.urbanguru.net/


How to use Spring's AbstractWizardFormController

As the class name suggests, this is an abstract class - so your WizardCon=
troller should extend it. This means in particular you have to implement =
the following abstract methods: validatePage, processFinish and processCa=
ncel.

You'll also want to write a constructor, which should at the very least c=
all setPages and setCommandName. setPages takes as its argument an array =
of type String. This array is the list of views which comprise your wizar=
d. setCommandName takes as its argument a string, which will be used to r=
efer to your Command object from within your views.

As with any instance of AbstractFormController, you are required to use a=
 Command object - a JavaBean which will be populated with the data from y=
our forms. You can do this in one of two ways: either call setCommandClas=
s from the constructor with the class of your command object, or implemen=
t the formBackingObject method.

AbstractWizardFormController has a number of concrete methods that you ma=
y wish to override. Of these, the ones you are likely to find most useful=
 are: referenceData which you can use to pass model data to your view in =
the form of a Map; getTargetPage if your wizard needs to change page orde=
r or omit pages dynamically; and onBindAndValidate if you want to overrid=
e the built-in binding and validation workflow.

Finally, it is worth pointing out the setAllowDirtyBack and setAllowDirty=
Forward, which you can call from getTargetPage to allow users to move bac=
kwards and forwards in the wizard even if validation fails for the curren=
t page.

For a full list of methods, see the JavaDoc for AbstractWizardFormControl=
ler. There is an implemented example of this wizard in the jPetStore incl=
uded in the Spring distribution: org.springframework.samples.jpetstore.we=
b.spring.OrderFormController.java