Spring Build-ified Spring Web Flow. Pray for us
This commit is contained in:
Ben Hale
264
spring-webflow-reference/src/defining-flows.xml
Normal file
264
spring-webflow-reference/src/defining-flows.xml
Normal file
@@ -0,0 +1,264 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<chapter id="defining-flows">
|
||||
<title>Defining Flows</title>
|
||||
<sect1 id="introduction">
|
||||
<title>Introduction</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</sect1>
|
||||
<sect1 id="flow-overview">
|
||||
<title>What is a Flow?</title>
|
||||
<para>
|
||||
A flow encapsulates a reusable sequence of steps that can execute in different contexts.
|
||||
Below is a <ulink url="http://www.jjg.net/ia/visvocab/">Garrett Information Architecture</ulink> diagram illustrating a reference to a flow that encapsulates the steps of a hotel booking process:
|
||||
</para>
|
||||
<mediaobject>
|
||||
<imageobject role="fo">
|
||||
<imagedata fileref="images/hotels-site.png" format="PNG" align="center"/>
|
||||
</imageobject>
|
||||
<imageobject role="html">
|
||||
<imagedata fileref="images/hotels-site.png" format="PNG" align="center"/>
|
||||
</imageobject>
|
||||
<caption>
|
||||
<para>Site Map illustrating a reference to a flow</para>
|
||||
</caption>
|
||||
</mediaobject>
|
||||
</sect1>
|
||||
<sect1 id="flow-makeup">
|
||||
<title>What is the makeup of a typical Flow?</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
The example below shows the structure of the book hotel flow referenced in the previous diagram:
|
||||
</para>
|
||||
<mediaobject>
|
||||
<imageobject role="fo">
|
||||
<imagedata fileref="images/hotels-site-bookhotel-flow.png" format="PNG" align="center"/>
|
||||
</imageobject>
|
||||
<imageobject role="html">
|
||||
<imagedata fileref="images/hotels-site-bookhotel-flow.png" format="PNG" align="center"/>
|
||||
</imageobject>
|
||||
<caption>
|
||||
<para>Flow diagram</para>
|
||||
</caption>
|
||||
</mediaobject>
|
||||
</sect1>
|
||||
<sect1 id="flow-definition">
|
||||
<title>How are Flows authored?</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</sect1>
|
||||
<sect1 id="flow-element">
|
||||
<title>The root <flow> element</title>
|
||||
<para>
|
||||
Every flow begins with the following root element:
|
||||
</para>
|
||||
<programlisting>
|
||||
<?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>
|
||||
</programlisting>
|
||||
<para>
|
||||
All states of the flow are defined within this element.
|
||||
The first state defined becomes the flow's starting point by default.
|
||||
</para>
|
||||
</sect1>
|
||||
<sect1 id="view-state-element">
|
||||
<title>The <view-state> element</title>
|
||||
<para>
|
||||
Use the view-state element to define a step of the flow that renders a page:
|
||||
</para>
|
||||
<programlisting>
|
||||
<view-state id="enterBookingDetails" />
|
||||
</programlisting>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</sect1>
|
||||
<sect1 id="transition-element">
|
||||
<title>The <transition> element</title>
|
||||
<para>
|
||||
Use the transition element to handle events that occur within a state:
|
||||
</para>
|
||||
<programlisting>
|
||||
<view-state id="enterBookingDetails">
|
||||
<transition on="submit" to="reviewBooking" />
|
||||
<transition on="cancel" to="bookingCancelled" />
|
||||
</view-state>
|
||||
</programlisting>
|
||||
<para>
|
||||
These transitions drive page navigations.
|
||||
</para>
|
||||
</sect1>
|
||||
<sect1 id="end-state-element">
|
||||
<title>The <end-state> element</title>
|
||||
<para>
|
||||
Use the end-state element to define a flow outcome.
|
||||
</para>
|
||||
<programlisting>
|
||||
<end-state id="bookingAuthorized" />
|
||||
</programlisting>
|
||||
<para>
|
||||
When a flow transitions to a end-state it terminates and the outcome is returned.
|
||||
</para>
|
||||
</sect1>
|
||||
<sect1 id="checkpoint-essential-flow-elements">
|
||||
<title>Checkpoint - Essential flow elements</title>
|
||||
<para>
|
||||
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:
|
||||
</para>
|
||||
<programlisting>
|
||||
<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>
|
||||
</programlisting>
|
||||
</sect1>
|
||||
<sect1 id="flow-actions">
|
||||
<title>Flow actions</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
Within a flow, there are several points where you can execute actions. These points are:
|
||||
<itemizedlist>
|
||||
<listitem><para>On flow start</para></listitem>
|
||||
<listitem><para>On state entry</para></listitem>
|
||||
<listitem><para>On transition execution</para></listitem>
|
||||
<listitem><para>On state exit</para></listitem>
|
||||
<listitem><para>On flow end</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</sect1>
|
||||
<sect1 id="evaluate-element">
|
||||
<title>The <evaluate> action element</title>
|
||||
<para>
|
||||
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:
|
||||
</para>
|
||||
<programlisting>
|
||||
<evaluate expression="entityManager.persist(booking)" />
|
||||
</programlisting>
|
||||
<para>
|
||||
If the expression returns a value, that value can be saved in the flow's data model called "flow scope":
|
||||
</para>
|
||||
<programlisting>
|
||||
<evaluate expression="bookingService.findHotels(searchCriteria)" result="flowScope.hotels" />
|
||||
</programlisting>
|
||||
<para>
|
||||
If the expression returns a value that may need to be converted, specify the expected type using the result-type attribute:
|
||||
</para>
|
||||
<programlisting>
|
||||
<evaluate expression="bookingService.findHotels(searchCriteria)" result="flowScope.hotels" result-type="dataModel"/>
|
||||
</programlisting>
|
||||
</sect1>
|
||||
<sect1 id="checkpoint-actions">
|
||||
<title>Checkpoint - flow actions</title>
|
||||
<para>
|
||||
Now review the sample booking flow with actions added:
|
||||
</para>
|
||||
<programlisting>
|
||||
<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>
|
||||
</programlisting>
|
||||
</sect1>
|
||||
<sect1 id="simple-event-handlers">
|
||||
<title>Transitions without target states</title>
|
||||
<para>
|
||||
Transitions without targets can also be defined:
|
||||
</para>
|
||||
<programlisting>
|
||||
<transition on="event">
|
||||
<-- Handle event -->
|
||||
</transition>
|
||||
</programlisting>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
Below is a realistic example of two transitions that handle Ajax events to page through a search results list:
|
||||
</para>
|
||||
<programlisting>
|
||||
<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>
|
||||
</programlisting>
|
||||
<para>
|
||||
These transitions change the current data-page, then request re-rendering of the hotels table fragment.
|
||||
</para>
|
||||
</sect1>
|
||||
</chapter>
|
||||
51
spring-webflow-reference/src/overview.xml
Normal file
51
spring-webflow-reference/src/overview.xml
Normal file
@@ -0,0 +1,51 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<preface id="preface">
|
||||
<title>Preface</title>
|
||||
<para>
|
||||
Many web applications require the same sequence of steps to execute in different contexts.
|
||||
Often these sequences are merely components of a larger task the user is trying to accomplish.
|
||||
Such a reusable sequence is called a flow.
|
||||
</para>
|
||||
<para>
|
||||
Consider a typical shopping cart application.
|
||||
User registration, login, and cart checkout are all examples of flows that can be invoked from several places in this type of application.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</preface>
|
||||
|
||||
<chapter id="introduction">
|
||||
<title>Introduction</title>
|
||||
<sect1 id="manual-overview">
|
||||
<title>What this guide covers</title>
|
||||
<para>
|
||||
This guide covers all aspects of Spring Web Flow.
|
||||
It is organized into two major sections, a Users Section followed by an Architects Section.
|
||||
The Users Section covers implementing flows in end-user applications and working with the feature set.
|
||||
The Architects Section covers extending the framework and the overall architectural model.
|
||||
</para>
|
||||
</sect1>
|
||||
<sect1 id="system-requirements">
|
||||
<title>What Web Flow requires to run</title>
|
||||
<para>
|
||||
Java 1.4 or higher
|
||||
</para>
|
||||
<para>
|
||||
Spring 2.5.2 or higher
|
||||
</para>
|
||||
</sect1>
|
||||
<sect1 id="support">
|
||||
<title>Where to get additional support</title>
|
||||
<para>
|
||||
Professional "from the source" support on Spring Web Flow is available from
|
||||
<ulink url="http://www.springsource.com">SpringSource</ulink>, the company behind Spring, and
|
||||
<ulink url="http://www.ervacon.com">Ervacon</ulink>, operated by Web Flow project co-founder Erwin Vervaet
|
||||
</para>
|
||||
<para>
|
||||
Spring Community support is available at <ulink url="http://www.springframework.org">www.springframework.org</ulink>
|
||||
</para>
|
||||
</sect1>
|
||||
</chapter>
|
||||
53
spring-webflow-reference/src/spring-webflow-reference.xml
Normal file
53
spring-webflow-reference/src/spring-webflow-reference.xml
Normal file
@@ -0,0 +1,53 @@
|
||||
<?xml version='1.0' encoding="iso-8859-1"?>
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
|
||||
[
|
||||
<!ENTITY overview SYSTEM "overview.xml">
|
||||
<!ENTITY defining-flows SYSTEM "defining-flows.xml">
|
||||
]>
|
||||
|
||||
<book>
|
||||
<bookinfo>
|
||||
<title>Spring Web Flow 2 Reference Guide</title>
|
||||
<subtitle>Reference Documentation</subtitle>
|
||||
<releaseinfo>Version 2.0 RC1</releaseinfo>
|
||||
<pubdate>March 2008</pubdate>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Keith</firstname>
|
||||
<surname>Donald</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Erwin</firstname>
|
||||
<surname>Vervaet</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Jeremy</firstname>
|
||||
<surname>Grelle</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Scott</firstname>
|
||||
<surname>Andrews</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Rossen</firstname>
|
||||
<surname>Stoyanchev</surname>
|
||||
</author>
|
||||
</authorgroup>
|
||||
<legalnotice>
|
||||
<para>
|
||||
Copies of this document may be made for your own use and for
|
||||
distribution to others, provided that you do not charge any
|
||||
fee for such copies and further provided that each copy
|
||||
contains this Copyright Notice, whether distributed in print
|
||||
or electronically.
|
||||
</para>
|
||||
</legalnotice>
|
||||
</bookinfo>
|
||||
|
||||
<toc />
|
||||
|
||||
&overview;
|
||||
&defining-flows;
|
||||
|
||||
</book>
|
||||
Reference in New Issue
Block a user