diff --git a/spring-webflow-reference/src/defining-flows.xml b/spring-webflow-reference/src/defining-flows.xml index ebc393a1..dfbc0466 100644 --- a/spring-webflow-reference/src/defining-flows.xml +++ b/spring-webflow-reference/src/defining-flows.xml @@ -57,12 +57,14 @@ 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: - - + + Essential language elements + + 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" @@ -70,60 +72,60 @@ 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 view: - - + + + 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 view: + + <view-state id="enterBookingDetails" /> - - - 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 - - Use the transition element to handle events that occur within a state: - - + + + 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 + + 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 view navigations. - - - - The end-state element - - Use the end-state element to define a flow outcome: - - -<end-state id="bookingConfirmed" /> - - - 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, 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 view navigation logic using these elements and initially contains no additional behavior: - - + + + These transitions drive view navigations. + + + + The end-state element + + Use the end-state element to define a flow outcome: + + +<end-state id="bookingCancelled" /> + + + When a flow transitions to a end-state it terminates and the outcome is returned. + + + + Checkpoint: Essential language elements + + With the three elements view-state, transition, 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 view navigation logic using these elements: + + <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 @@ -145,10 +147,11 @@ <end-state id="bookingCancelled" /> </flow> - + + - Flow actions + Actions 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. @@ -166,39 +169,83 @@ 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 next few sections will cover the language elements for defining actions. - - - 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. - With this single tag you can invoke methods on Spring beans or any other flow variable. - For example: - - + + The evaluate element + + 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. + 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 flowScope: - - + + + Assigning an evaluate result + + 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 desired type using the result-type attribute: - - + + + + Converting an evaluate result + + 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"/> - - - - Checkpoint - flow actions - - Now review the sample booking flow with actions added: - - + + + + + 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 + + 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 @@ -226,14 +273,15 @@ <end-state id="bookingCancelled" /> </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. - + + + 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 + Input/Output Mapping 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. @@ -251,87 +299,94 @@ public interface FlowOutcome { public Map<String, Object> getOutputAttributes(); } - - - The input element - - Use the input element to declare a flow input attribute: - - + + 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 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: - - + + + 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" value="flowScope.myParameterObject.hotelId" /> + + + If the expression's value type can be determined, that metadata 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> + + + + + The output element + + Use the output element to declare a flow output attribute. + Output attributes are declared within end-states that represent specific flow outcomes. + + +<end-state> id="bookingConfirmed"; <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" /> - + + + 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="confirmationNumber" value="booking.confirmationNumber" /> + + + 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: - - + + 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