From 367167b59b4ced641555a3a8666bf657adacec08 Mon Sep 17 00:00:00 2001 From: Keith Donald Date: Sun, 6 Apr 2008 20:44:23 +0000 Subject: [PATCH] doc updates --- .../src/defining-flows.xml | 210 +++++++++++++----- spring-webflow-reference/src/overview.xml | 4 +- .../src/spring-webflow-reference.xml | 2 +- 3 files changed, 160 insertions(+), 56 deletions(-) diff --git a/spring-webflow-reference/src/defining-flows.xml b/spring-webflow-reference/src/defining-flows.xml index 32c5361b..ebc393a1 100644 --- a/spring-webflow-reference/src/defining-flows.xml +++ b/spring-webflow-reference/src/defining-flows.xml @@ -10,7 +10,7 @@ - What is a Flow? + What is a flow? A flow encapsulates a reusable sequence of steps that can execute in different contexts. Below is a Garrett Information Architecture diagram illustrating a reference to a flow that encapsulates the steps of a hotel booking process: @@ -28,12 +28,12 @@ - What is the makeup of a typical Flow? + What is the makeup of a typical flow? In Spring Web Flow, a flow consists of a series of steps called "states". - Entering a state typically results in a page being displayed to the user. - On the page, user events occur that are handled by that state. - These events can trigger transitions to other states which result in page navigations. + Entering a state typically results in a view being displayed to the user. + On that view, user events occur that are handled by the state. + These events can trigger transitions to other states which result in view navigations. The example below shows the structure of the book hotel flow referenced in the previous diagram: @@ -51,22 +51,23 @@ - How are Flows authored? + How are flows authored? 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 + 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"> + xsi:schemaLocation="http://www.springframework.org/schema/webflow + http://www.springframework.org/schema/webflow/spring-webflow-2.0.xsd"> </flow> @@ -76,41 +77,40 @@ - The <view-state> element + The view-state element - Use the view-state element to define a step of the flow that renders a page: + Use the view-state element to define a step of the flow that renders a view: - - <view-state id="enterBookingDetails" /> + +<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. + By convention, a view-state maps its id to a view template in the directory where the flow is located. + For example, the state above might render from /WEB-INF/hotels/booking/enterBookingDetails.xhtml. - The <transition> element + The transition element - Use the transition element to handle events that occur within a state: + 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> + +<view-state id="enterBookingDetails"> + <transition on="submit" to="reviewBooking" /> + <transition on="cancel" to="bookingCancelled" /> +</view-state> - These transitions drive page navigations. + These transitions drive view navigations. - The <end-state> element + The end-state element - Use the end-state element to define a flow outcome. + Use the end-state element to define a flow outcome: - - <end-state id="bookingAuthorized" /> + +<end-state id="bookingConfirmed" /> When a flow transitions to a end-state it terminates and the outcome is returned. @@ -119,17 +119,18 @@ Checkpoint - Essential flow elements - With the three elements <view-state>, <transition>, and <end-state>, you can rapidly express your page navigation logic. + With the three elements view-state, transitio, and end-state, you can quickly express your view 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: + Below is a sample flow that implements its view 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"> + 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="submit" to="reviewBooking" /> <transition on="cancel" to="bookingCancelled" /> </view-state> @@ -149,7 +150,7 @@ Flow actions - Most flows need to express more than just page navigation logic. + Most flows need to express more than just view navigation logic. Typically they also need to invoke business services of the application or other actions. @@ -157,6 +158,7 @@ On flow start On state entry + On view render On transition execution On state exit On flow end @@ -168,26 +170,26 @@ - The <evaluate> action element + The evaluate 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. + 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": + If the expression returns a value, that value can be saved in the flow's data model called flowScope: - + <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: + If the expression returns a value that may need to be converted, specify the desired type using the result-type attribute: - + <evaluate expression="bookingService.findHotels(searchCriteria)" result="flowScope.hotels" result-type="dataModel"/> @@ -196,22 +198,20 @@ 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"> + 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" /> + <input name="hotelId" /> <on-start> - <evaluate expression="bookingService.findHotelById(hotelId)" result="flowScope.hotel" /> - <evaluate expression="hotel.createBooking(bookingService.findUser(currentUser.name))" result="flowScope.booking" /> + <evaluate expression="bookingService.createBooking(hotelId, currentUser.name)" result="flowScope.booking" /> </on-start> <view-state id="enterBookingDetails"> - <transition on="submit" to="reviewBooking"> - <evaluate expression="booking.validate(messageContext)" /> - </transition> + <transition on="submit" to="reviewBooking" /> <transition on="cancel" to="bookingCancelled" /> </view-state> @@ -227,25 +227,129 @@ </flow> + + This flow now creates Booking object in flow scope when it starts. + The id of the hotel to book is obtained from a flow input attribute. + + + The flow input/output contract + + Each flow has a well-defined input/output contract. + Flows can be passed input attributes when they start, and can return output attributes when they end. + In this respect, calling a flow is conceptually similar to calling a method with the following signature: + + +FlowOutcome flowId(Map<String, Object> inputAttributes); + + + ... where a FlowOutcome has the following signature: + + +public interface FlowOutcome { + public String getName(); + public Map<String, Object> getOutputAttributes(); +} + + + + The input element + + Use the input element to declare a flow input attribute: + + +<input name="hotelId" /> + + + Input values are saved in flow scope under the name of the attribute. + For example, the input above would be saved under the name hotelId. + + + Use the type attribute to declare the input attribute's type: + + +<input name="hotelId" type="long" /> + + + If an input value does not match the declared type, a type conversion will be attempted. + + + Use the value attribute to denote a specific expression to assign the input value to: + + +<input name="hotelId" type="long" value="flowScope.hotelId" /> + + + If the expression's value type can be determined, that information will be used for type coersion + if no type attribute is specified. + + + Use the required attribute to enforce the input is not null or empty: + + +<input name="hotelId" type="long" value="flowScope.hotelId" required="true" /> + + + + The output element + + Use the output element to declare a flow output attribute. + Output attributes are declared with the end-state that creates the flow outcome. + + +<end-state> + <output name="bookingId" /> +</end-state> + + + Output values are obtained from flow scope under the name of the attribute. + For example, the output above would be assigned the value of the bookingId variable. + + + Use the value attribute to denote a specific output value expression: + + +<output name="bookingId" value="booking.id" /> + + + + Calling subflows + + A flow may call another flow as a subflow. The flow will wait until the subflow returns before responding to its outcome. + + + + The subflow-state element + + Use the subflow-state element to call another flow: + + +<subflow-state id="addGuest"> + <transition on="guestAdded" to="reviewBooking" > + <evaluate expression="booking.guests.add(guest)"/> + <transition /> + <transition on="cancel" to="reviewBooking" /> +</subfow-state> + + 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. + They simply execute their actions and re-render the current view or a subset of the current view. 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()" /> diff --git a/spring-webflow-reference/src/overview.xml b/spring-webflow-reference/src/overview.xml index a0b3fcde..215f3407 100644 --- a/spring-webflow-reference/src/overview.xml +++ b/spring-webflow-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 is the module of Spring that focuses on being the definitive solution for implementing flows. + Spring Web Flow is the module of Spring 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. @@ -34,7 +34,7 @@ Java 1.4 or higher - Spring 2.5.2 or higher + Spring 2.5.3 or higher diff --git a/spring-webflow-reference/src/spring-webflow-reference.xml b/spring-webflow-reference/src/spring-webflow-reference.xml index f5f3d31d..206c7977 100644 --- a/spring-webflow-reference/src/spring-webflow-reference.xml +++ b/spring-webflow-reference/src/spring-webflow-reference.xml @@ -11,7 +11,7 @@ Spring Web Flow 2 Reference Guide Reference Documentation Version 2.0 RC1 - March 2008 + April 2008 Keith