diff --git a/spring-webflow/docs/reference/src/defining-flows.xml b/spring-webflow/docs/reference/src/defining-flows.xml
index bc6bd102..4e39cc7d 100644
--- a/spring-webflow/docs/reference/src/defining-flows.xml
+++ b/spring-webflow/docs/reference/src/defining-flows.xml
@@ -4,7 +4,7 @@
Introduction
- This chapter begins the Users Section of this guide.
+ This chapter begins the Users Section.
It shows how to implement flows using the flow definition language.
By the end of this chapter, you should have a good understanding of language constructs and capable of authoring a flow definition.
@@ -23,7 +23,7 @@
- A BookHotel Flow Definition
+ Site Map illustrating a reference to a flow
@@ -46,15 +46,219 @@
- Hotels Site Diagram that references a "Book Hotel" flow
+ Flow diagram
How are Flows authored?
- Flows are authored by web application developers using a XML-based flow definition language.
+ Flows are authored by web application developers using a simple XML-based flow definition language.
The next steps of this guide will walk you through the elements of this language.
+
+ The root <flow> element
+
+ Every flow begins with the following root element:
+
+
+<?xml version="1.0" encoding="UTF-8"?>
+<flow xmlns="http://www.springframework.org/schema/webflow"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://www.springframework.org/schema/webflow http://www.springframework.org/schema/webflow/spring-webflow-2.0.xsd">
+
+</flow>
+
+
+ All states of the flow are defined within this element.
+ The first state defined becomes the flow's starting point by default.
+
+
+
+ The <view-state> element
+
+ Use the view-state element to define a step of the flow that renders a page:
+
+
+ <view-state id="enterBookingDetails" />
+
+
+ By convention, a view-state maps its id to a page template in the
+ directory where the flow is located. For example, the state above might
+ render from /WEB-INF/booking/enterBookingDetails.xhtml.
+
+
+
+ The <transition> element
+
+ Use the transition element to handle events that occur within a state:
+
+
+ <view-state id="enterBookingDetails">
+ <transition on="submit" to="reviewBooking" />
+ <transition on="cancel" to="bookingCancelled" />
+ </view-state>
+
+
+ These transitions drive page navigations.
+
+
+
+ The <end-state> element
+
+ Use the end-state element to define a flow outcome.
+
+
+ <end-state id="bookingAuthorized" />
+
+
+ When a flow transitions to a end-state it terminates and the outcome is returned.
+
+
+
+ Checkpoint - Essential flow elements
+
+ With the three elements <view-state>, <transition>, and <end-state>, you can rapidly express your page navigation logic.
+ Teams often do this before adding flow behaviors so they can focus on developing the user interface of the application with end users first.
+ Below is a sample flow that implements its page navigation logic using these elements and initially contains no additional behavior:
+
+
+<flow xmlns="http://www.springframework.org/schema/webflow"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://www.springframework.org/schema/webflow http://www.springframework.org/schema/webflow/spring-webflow-2.0.xsd">
+
+ <view-state id="enterBookingDetails">
+ <transition on="proceed" to="reviewBooking" />
+ <transition on="cancel" to="bookingCancelled" />
+ </view-state>
+
+ <view-state id="reviewBooking">
+ <transition on="confirm" to="bookingConfirmed" />
+ <transition on="revise" to="enterBookingDetails" />
+ <transition on="cancel" to="bookingCancelled" />
+ </view-state>
+
+ <end-state id="bookingConfirmed" />
+
+ <end-state id="bookingCancelled" />
+
+</flow>
+
+
+
+ Flow actions
+
+ Most flows need to express more than just page navigation logic.
+ Typically they also need to invoke business services of the application or other actions.
+
+
+ Within a flow, there are several points where you can execute actions. These points are:
+
+ On flow start
+ On state entry
+ On transition execution
+ On state exit
+ On flow end
+
+
+
+ Actions are defined using a concise expression language. Spring Web Flow uses the Unified EL by default.
+ The next few sections will cover the language elements defining action expressions.
+
+
+
+ The <evaluate> action element
+
+ The action element you will use the most often is the <evaluate> element.
+ Use the evaluate element to execute an action expression at a point within your flow.
+ With this single tag you can invoke methods on Spring beans or any other flow variable.
+ For example:
+
+
+<evaluate expression="entityManager.persist(booking)" />
+
+
+ If the expression returns a value, that value can be saved in the flow's data model called "flow scope":
+
+
+<evaluate expression="bookingService.findHotels(searchCriteria)" result="flowScope.hotels" />
+
+
+ If the expression returns a value that may need to be converted, specify the expected type using the result-type attribute:
+
+
+<evaluate expression="bookingService.findHotels(searchCriteria)" result="flowScope.hotels" result-type="dataModel"/>
+
+
+
+ Checkpoint - flow actions
+
+ Now review the sample booking flow with actions added:
+
+
+<flow xmlns="http://www.springframework.org/schema/webflow"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://www.springframework.org/schema/webflow http://www.springframework.org/schema/webflow/spring-webflow-2.0.xsd">
+
+ <input name="hotelId" value="flowScope.hotelId" />
+
+ <on-start>
+ <evaluate expression="bookingService.findHotelById(hotelId)" result="flowScope.hotel" />
+ <evaluate expression="hotel.createBooking(bookingService.findUser(currentUser.name))" result="flowScope.booking" />
+ </on-start>
+
+ <view-state id="enterBookingDetails">
+ <transition on="submit" to="reviewBooking">
+ <evaluate expression="booking.validate(messageContext)" />
+ </transition>
+ <transition on="cancel" to="bookingCancelled" />
+ </view-state>
+
+ <view-state id="reviewBooking">
+ <transition on="confirm" to="bookingConfirmed" />
+ <transition on="revise" to="enterBookingDetails" />
+ <transition on="cancel" to="bookingCancelled" />
+ </view-state>
+
+ <end-state id="bookingConfirmed" />
+
+ <end-state id="bookingCancelled" />
+
+</flow>
+
+
+
+ Transitions without target states
+
+ Transitions without targets can also be defined:
+
+
+<transition on="event">
+ <-- Handle event -->
+</transition>
+
+
+ Such transitions are event handlers that do not change the state of the flow.
+ They simply execute their actions and re-render the current page or a subset of the current page.
+
+
+ Below is a realistic example of two transitions that handle Ajax events to page through a search results list:
+
+
+<view-state id="searchResults">
+ <transition on="next">
+ <evaluate expression="searchCriteria.nextPage()" />
+ <render fragments="hotels:resultsTable" />
+ </transition>
+ <transition on="previous">
+ <evaluate expression="searchCriteria.previousPage()" />
+ <render fragments="hotels:resultsTable" />
+ </transition>
+</view-state>
+
+
+ These transitions change the current data-page, then request re-rendering of the hotels table fragment.
+
+
\ No newline at end of file
diff --git a/spring-webflow/docs/reference/src/index.xml b/spring-webflow/docs/reference/src/index.xml
index 9ea2038d..99501cf5 100644
--- a/spring-webflow/docs/reference/src/index.xml
+++ b/spring-webflow/docs/reference/src/index.xml
@@ -8,9 +8,9 @@
- Spring Web Flow
+ Spring Web Flow 2 Reference Guide - Work in Progress
Reference Documentation
- Version 2.0 M4
+ Version 2.0 M4 - Work in Progress
March 2008
diff --git a/spring-webflow/docs/reference/src/overview.xml b/spring-webflow/docs/reference/src/overview.xml
index f696003c..a0b3fcde 100644
--- a/spring-webflow/docs/reference/src/overview.xml
+++ b/spring-webflow/docs/reference/src/overview.xml
@@ -11,7 +11,7 @@
User registration, login, and cart checkout are all examples of flows that can be invoked from several places in this type of application.
- Spring Web Flow (SWF) is the module of Spring that focuses on being the definitive solution for implementing flows.
+ Spring Web Flow is the module of Spring that focuses on being the definitive solution for implementing flows.
The Web Flow engine plugs into the Spring Web MVC platform and provides declarative flow definition language.
This reference guide shows you how to use and extend Spring Web Flow.
@@ -41,11 +41,11 @@
Where to get additional support
Professional "from the source" support on Spring Web Flow is available from
- SpringSource, the company behind Spring, and
- Ervacon, operated by Web Flow project co-founder Erwin Vervaet
+ SpringSource, the company behind Spring, and
+ Ervacon, operated by Web Flow project co-founder Erwin Vervaet
- Spring Community support is available at www.springframework.org
+ Spring Community support is available at www.springframework.org
\ No newline at end of file