diff --git a/spring-webflow-reference/src/defining-flows.xml b/spring-webflow-reference/src/defining-flows.xml
index d41346d1..b4c9e4f4 100644
--- a/spring-webflow-reference/src/defining-flows.xml
+++ b/spring-webflow-reference/src/defining-flows.xml
@@ -60,7 +60,7 @@
Essential language elements
- The root flow element
+ flow
Every flow begins with the following root element:
@@ -75,11 +75,11 @@
All states of the flow are defined within this element.
- The first state defined becomes the flow's starting point by default.
+ The first state defined becomes the flow's starting point.
- The view-state element
+ view-state
Use the view-state element to define a step of the flow that renders a view:
@@ -88,11 +88,12 @@
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.
+ For example, the state above might render /WEB-INF/hotels/booking/enterBookingDetails.xhtml
+ if the flow itself was located in the /WEB-INF/hotels/booking directory.
- The transition element
+ transition
Use the transition element to handle events that occur within a state:
@@ -106,7 +107,7 @@
- The end-state element
+ end-state
Use the end-state element to define a flow outcome:
@@ -167,10 +168,10 @@
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 for defining actions.
+ The next few sections will cover the essential language elements for defining actions.
- The evaluate element
+ evaluate
The action element you will use the most often is the evaluate element.
Use the evaluate element to evaluate an expression at a point within your flow.
@@ -199,45 +200,6 @@
-
- The set element
-
- Use the set element when you need to assign a flow variable:
-
-
-<set name="flowScope.selectedHotel" value="hotels.selectedRow" />
-
-
- Both the name and value attributes are EL expressions.
-
-
- Assigning a null value
-
- Use the special null keyword to assign a variable to null:
-
-
-<set name="flowScope.selectedHotel" value="null" />
-
-
-
- Assigning a literal value
-
- Enclose a value within tick marks to assign a literal:
-
-
-<set name="flowScope.status" value="'Processing Order'" />
-
-
-
- Converting a value prior to variable assignment
-
- Use the type attribute to specify a desired value type:
-
-
-<set name="flowScope.id" value="requestParameters.id" type="long" />
-
-
-
Checkpoint: flow actions
@@ -272,7 +234,7 @@
</flow>
- This flow now creates Booking object in flow scope when it starts.
+ This flow now creates a Booking object in flow scope when it starts.
The id of the hotel to book is obtained from a flow input attribute.
@@ -297,7 +259,7 @@ public interface FlowOutcome {
}
- The input element
+ input
Use the input element to declare a flow input attribute:
@@ -321,7 +283,7 @@ public interface FlowOutcome {
- Use the value attribute to denote a specific expression to assign the input value to:
+ Use the value attribute to specify an expression to assign the input value to:
<input name="hotelId" value="flowScope.myParameterObject.hotelId" />
@@ -340,7 +302,7 @@ public interface FlowOutcome {
- The output element
+ output
Use the output element to declare a flow output attribute.
Output attributes are declared within end-states that represent specific flow outcomes.
@@ -407,15 +369,18 @@ public interface FlowOutcome {
These variables are allocated when the flow starts.
Any @Autowired transient references the variable holds are also rewired when the flow resumes.
-
- Use the var element to declare a flow variable:
-
-
+
+ var
+
+ Use the var element to declare a flow variable:
+
+
<var name="searchCriteria" class="com.mycompany.myapp.hotels.search.SearchCriteria"/>
-
-
- Make sure your variable's class implements java.io.Serializable, as the instance state is saved between flow requests.
-
+
+
+ Make sure your variable's class implements java.io.Serializable, as the instance state is saved between flow requests.
+
+
Calling subflows
@@ -423,14 +388,14 @@ public interface FlowOutcome {
A flow may call another flow as a subflow. The flow will wait until the subflow returns, then respond to the subflow outcome.
- The subflow-state element
+ subflow-state
Use the subflow-state element to call another flow as a subflow:
<subflow-state id="addGuest" subflow="createGuest">
<transition on="guestCreated" to="reviewBooking">
- <evaluate expression="booking.guests.add(guest)"/>
+ <evaluate expression="booking.guests.add(currentEvent.guest)" />
<transition />
<transition on="creationCancelled" to="reviewBooking" />
</subfow-state>
@@ -511,37 +476,4 @@ public interface FlowOutcome {
-
- 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 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()" />
- <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-reference/src/el.xml b/spring-webflow-reference/src/el.xml
new file mode 100644
index 00000000..6ddd1240
--- /dev/null
+++ b/spring-webflow-reference/src/el.xml
@@ -0,0 +1,251 @@
+
+
+ Expression Language (EL)
+
+ Introduction
+
+ Web Flow uses EL to access its data model and invoke actions.
+ This chapter will familiarize you with the EL syntax, and special EL variables you can reference from your flow definition.
+
+
+
+ Supported EL implementations
+
+ Unified EL
+
+ Web Flow attempts to use the Unified EL by default.
+ jboss-el is currently the default EL implementation.
+ When found in your classpath along with the el-api, it will be used automatically.
+
+ The el-api dependency is typically a provided by your web container. Tomcat 6 includes it, for example.
+
+
+
+
+ OGNL
+
+ OGNL is the other EL supported by Web Flow 2.
+ OGNL is the EL most familiar to Web Flow version 1.0 users.
+ To use ognl, simply include ognl in your classpath instead of jboss-el.
+ Please refer to the OGNL language guide for specifics on its EL syntax.
+
+
+
+
+ EL Portability
+
+ In general, you will find the Unified EL and OGNL have a very similar syntax.
+ For basic variable resolution, property access, and method invocation the syntax is identical.
+ We recommend adhering to Unified EL syntax whenever possible, and only relying on proprietary EL features when needed.
+
+
+
+ EL Usage
+
+ EL is used for many things within a flow, including:
+
+
+ Accessing data provided by the client, such as flow input attributes and request parameters.
+ Accessing internal data structures such as flowScope.
+ Invoking methods on Spring beans.
+ Resolving constructs such as state transition criteria, subflow ids, and view names.
+
+
+ Views rendered by flows often access flow data structures using EL as well.
+
+
+ Expression Types
+
+ There are basically two types of expressions in Web Flow.
+
+
+ Standard eval expressions
+
+ The first, and most common type of expression, is the standard eval expression.
+ Such expressions are dynamically evaluated by the EL and should not be enclosed in delimiters like ${} or #{}.
+ For example:
+
+
+<evaluate expression="searchCriteria.nextPage()" />
+
+
+ The expression above is a standard expression that invokes the nextPage method on the searchCriteria variable when evaluated.
+ Attempting to enclose this expression in special eval delimiters like ${} or #{} will result in an IllegalArgumentException.
+
+ We view use of special eval delimiters as redundant in this context, as the only acceptable value for the expression attribute is a single eval expression string.
+
+
+
+
+ Template expressions
+
+ The second type of expression is a "template" expression.
+ Such expressions allow a mixing of literal text with one or more eval blocks.
+ Each evaluateable block is explictly delimited with the ${} delimiters.
+ For example:
+
+
+<view-state id="error" view="error-${externalContext.locale}.xhtml" />
+
+
+ The expression above is a template expression.
+ The result of evaluation will be a string that combines the literal text error- with the result of evaluating externalContext.locale.
+ As you can see, explicit delimiters are necessary here to demarcate eval blocks within the template.
+
+
+
+ See the Web Flow XML schema for a complete listing of the XML attributes that accept standard expressions and template expressions.
+
+
+
+
+ Special EL variables
+
+ There are several implicit variables you may reference from within a flow.
+ These variables are discussed in this section.
+
+
+ flowScope
+
+ Use flowScope to assign a flow variable.
+ Flow scope gets allocated when a flow starts and destroyed when the flow ends.
+
+
+<evaluate expression="searchService.findHotel(hotelId)" result="flowScope.hotel" />
+
+
+
+ viewScope
+
+ Use viewScope to assign a view variable.
+ View scope gets allocated when a view-state enters and destroyed when the state exits.
+ View scope is only referenceable from within a view-state.
+
+
+<on-render>
+ <evaluate expression="searchService.findHotels(searchCriteria)" result="viewScope.hotels" type="dataModel" />
+</on-render>
+
+
+
+ requestScope
+
+ Use requestScope to assign a request variable.
+ Request scope gets allocated when a flow is called and destroyed when the flow returns.
+
+
+<set name="requestScope.hotelId" value="requestParameters.id" type="long" />
+
+
+
+ flashScope
+
+ Use flashScope to assign a flash variable.
+ Flash scope gets allocated when a flow starts, cleared after every view render, and destroyed when the flow ends.
+
+
+<set name="flashScope.statusMessage" value="'Booking confirmed'" />
+
+
+
+ conversationScope
+
+ Use conversationScope to assign a conversation variable.
+ Conversation scope gets allocated when a top-level flow starts and destroyed when the top-level flow ends.
+ Conversation scope is shared by a top-level flow and all of its subflows.
+
+
+<evaluate expression="searchService.findHotel(hotelId)" result="conversationScope.hotel" />
+
+
+
+ requestParameters
+
+ Use requestParameters to access a client request parameter:
+
+
+<set name="requestScope.hotelId" value="requestParameters.id" type="long" />
+
+
+
+ currentEvent
+
+ Use currentEvent to access attributes of the current Event:
+
+
+<evaluate expression="booking.guests.add(currentEvent.guest)" />
+
+
+
+ currentUser
+
+ Use currentUser to access the authenticated Principal:
+
+
+<evaluate expression="bookingService.createBooking(hotelId, currentUser.name)" result="flowScope.booking" />
+
+
+
+ messageContext
+
+ Use messageContext to access a context for retrieving and creating flow execution messages, including error and success messages.
+ See the MessageContext Javadocs for more information.
+
+
+<evaluate expression="bookingValidator.validate(booking, messageContext)" />
+
+
+
+ flowRequestContext
+
+ Use flowRequestContext to access the RequestContext API, which is a representation of the current flow request.
+ See the API Javadocs for more information.
+
+
+
+ flowExecutionContext
+
+ Use flowExecutionContext to access the FlowExecutionContext API, which is a representation of the current flow state.
+ See the API Javadocs for more information.
+
+
+
+ flowExecutionUrl
+
+ Use flowExecutionUrl to access the context-relative URI for the current flow execution view-state.
+
+
+
+ externalContext
+
+ Use externalContext to access the client environment, including user session attributes.
+ See the ExternalContext API JavaDocs for more information.
+
+
+<evaluate expression="searchService.suggestHotels(externalContext.sessionMap.userProfile)" result="viewScope.hotels" />
+
+
+
+
+ Scope Searching Algorithm
+
+ When assigning a variable in one of the flow scopes, referencing that scope is required.
+ For example:
+
+
+<set name="requestScope.hotelId" value="requestParameters.id" type="long" />
+
+
+ When simply accessing a variable in one of the scopes, referencing the scope is optional.
+ For example:
+
+
+<evaluate expression="entityManager.persist(booking)" />
+
+
+ If no scope is specified, like in the use of booking above, a scope searching algorithm will be employed.
+ The algorithm will look in request, flash, view, flow, and conversation scope for the variable.
+ If no such variable is found, an EvaluationException will be thrown.
+
+
+
\ No newline at end of file
diff --git a/spring-webflow-reference/src/spring-webflow-reference.xml b/spring-webflow-reference/src/spring-webflow-reference.xml
index 2a22ade2..79531737 100644
--- a/spring-webflow-reference/src/spring-webflow-reference.xml
+++ b/spring-webflow-reference/src/spring-webflow-reference.xml
@@ -4,6 +4,7 @@
[
+
]>
@@ -18,22 +19,37 @@
Keith
Donald
+
+ SpringSource
+
Erwin
Vervaet
+
+ Ervacon
+
Jeremy
Grelle
+
+ SpringSource
+
Scott
Andrews
+
+ SpringSource
+
Rossen
Stoyanchev
+
+ SpringSource
+
@@ -51,6 +67,7 @@
&overview;
&defining-flows;
+ ⪙
&flow-security;
&flow-inheritance;