From 83b7932d619f2057a50edf7a76878db6fea191e9 Mon Sep 17 00:00:00 2001 From: Keith Donald Date: Tue, 8 Apr 2008 07:56:05 +0000 Subject: [PATCH] el section --- .../src/defining-flows.xml | 120 ++------- spring-webflow-reference/src/el.xml | 251 ++++++++++++++++++ .../src/spring-webflow-reference.xml | 17 ++ 3 files changed, 294 insertions(+), 94 deletions(-) create mode 100644 spring-webflow-reference/src/el.xml 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;