Quick Start - Spring Web Flow

This quick start is here to help you hit the ground running quickly with Spring Web Flow 1.0.

Note: this document is pending update to 1.0 RC4 - please review the sample applications in the release for complete, working examples

This document assumes you've downloaded a Spring Web Flow 1.0 and the Spring Framework. It also assumes basic working knowledge of Spring, HTML, and JSP/JSTL. In addition, some familiarity with finite state machines and UML state diagrams is assumed.

Below demonstrates the steps required to implement your first flow, with a purposefully simple example:

First ensure spring-webflow-1.0.jar and spring-binding-1.0.jar in your classpath. You'll also need the core Spring Framework version 1.2.7 or later as well--the simplest way to achieve this is to just include the convenient all-in-one spring.jar file in your classpath.
Next, design your first flow. For this quick start, assume the simplest possible flow. Specifically the flow should:
- On startup, render a form view for display in the browser
- On "submit", bind form input data to a backing form object and validate it. If there is an error, go back to the form view. If everything is kosher, execute a submit action.
  (For those of you familiar with Spring MVC, you'll recognize this as the dynamic equivalent to the workflow defined within SimpleFormController.)

Next, create your first flow definition. This quickstart shows how to define the flow in XML:

myFlow.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE flow PUBLIC "-//SPRING//DTD WEBFLOW 1.0//EN"
       "http://www.springframework.org/dtd/spring-webflow-1.0.dtd">

<flow start-state="displayForm">

    <view-state id="displayForm" view="form">
        <entry-actions>
            <action bean="formAction" method="setupForm"/>
        </entry-actions>
        <transition on="submit" to="processSubmit">
            <action bean="formAction" method="bindAndValidate"/>
        </transition>
    </view-state>

    <action-state id="processSubmit">
        <action bean="formAction" method="processSubmit"/>
        <transition on="success" to="finish"/>
    </action-state>

    <end-state id="finish" view="success"/>

</flow>

Next, create your first flow action. This quickstart shows how to define the formAction bean referenced above, which centralizes form setup, bind and validate, and submit logic.

MyFormAction.java

public class MyFormAction extends FormAction {
    public MyFormAction() {
        setFormObjectClass(FormObject.class);
    }

    public static class FormObject implements Serializable {
        private String data;

        public String getData() {
            return data;
        }

        public void setData(String data) {
            this.data = data;
        }
    }

    /**
     * A "submit" hook: an action execute method, called after
     * binding and validation.
     */
    public Event processSubmit(RequestContext context) throws Exception {
        FormObject formObject = (FormObject)getFormObject(context);
        // do submit logic
        return success();
    }

}

Next, deploy your first flow using the Spring Application Context. Here, you select to use the XmlFlowRegistryFactoryBean, which creates a registry containing the flow built from the above xml resource. This is also also where you deploy your flow's form action.
dispatcher-servlet.xml
```
<bean id="flowRegistry" class="org.springframework.webflow.registry.XmlFlowRegistryFactoryBean">
   <property name="flowLocations" value="/WEB-INF/flows/myflow.xml"/>
</bean>

<bean id="formAction" class="example.MyFormAction"/>
```

Next, ready your flow for use by your favorite web framework. For use with Spring MVC, define a FlowController and ViewResolver:

dispatcher-servlet.xml

<bean name="/myApp.htm" class="org.springframework.webflow.executor.mvc.FlowController">
    <property name="flowLocator" ref="flowRegistry"/>
</bean>

<!-- Maps flow view-state view names to JSP templates with JSTL support -->
<bean id="viewResolver" class="org.springframework.web.servlet.view.InternalResourceViewResolver">
    <property name="viewClass" value="org.springframework.web.servlet.view.JstlView"/>
    <property name="prefix" value="/WEB-INF/jsp/"/>
    <property name="suffix" value=".jsp"/>
</bean>

The above definition maps the /myApp.htm URL to the flow controller defined above. One controller typically manages executions of all flows for the whole app - this is achieved by having the views that launch new flow executions parameterize the flow controller with a _flowId parameter.

Next, create the views (aka pages) that participate in the flow.

/WEB-INF/jsp/form.jsp

<html>
<head>
   <title>My Form</title>
</head>
<body>
<p>
   <table>
   <form action="myApp.htm">
       <tr>
           <td>Field:</td>
           <td><input type="text" name="data" size="25"/></td>
       </tr>
       <tr>
           <td colspan="2" align="right">
               <input name="_eventId_submit" type="submit">
               <input type="hidden" name="_flowExecutionKey" value="${flowExecutionKey}">
           </td>
       </tr>
   </form>
   </table>
</p>
</body>
</html>

Note: flows are stateful. As a result, a view participating in a flow must submit the _flowExecutionKey parameter back to the server to identify which flow the client is participating in. In addition, a view must submit a parseable form of the _eventId parameter back to the server to signal the event that occured when a button was pressed; for example, submit if the submit buttion was pressed.

Lastly, access the flow! In this case, we simply access the /myApp.htm?_flowId=myFlow URL. When we access it, a new 'myFlow' FlowExecution will be created server-side and transitioned to its start-state. When this happens, the following process is set in motion:
1. The form is rendered.
2. The user completes the form and signals the 'submit' event by clicking the submit button.
3. Receipt of the submit event triggers the bindAndValidate method on the MyFlowAction to be invoked, which returns a result (e.g success or error).
4. The action result triggers another transition - e.g back to displayForm on error or on to submit on success.
5. The processSubmit state triggers the processSubmit method on the same MyFlowAction to be invoked. It returns a result.
6. On a submit success result, the flow ends, rendering a ending success view.

As you can see, the Flow definition fully defines the workflow described above. The Action implementations focus on executing command logic when requested, returning a logical result outcome the flow can respond to.

This completes this Quick Start, a brief introductory to the Spring Web Flow system. A good place to go to learn more is the reference documentation and support forums. Another good way to learn more is to checkout the samples in the release archive within the spring-webflow-samples directory of the release archive. See the readme.txt there for instructions on how to build and deploy the sample applications.