Spring/spring-webflow
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

el section

Browse Source
This commit is contained in:
Keith Donald
2008-04-08 07:56:05 +00:00
parent a359dcc910
commit 83b7932d61
3 changed files with 294 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
spring-webflow-reference/src/defining-flows.xml
View File

@@ -60,7 +60,7 @@
<sect1 id="essential-flow-elements">
<title>Essential language elements</title>
<sect2 id="flow-element">
<title>The root flow element</title>
<title>flow</title>
<para>
Every flow begins with the following root element:
</para>
@@ -75,11 +75,11 @@
</programlisting>
<para>
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.
</para>
</sect2>
<sect2 id="view-state-element">
<title>The view-state element</title>
<title>view-state</title>
<para>
Use the <code>view-state</code> element to define a step of the flow that renders a view:
</para>
@@ -88,11 +88,12 @@
</programlisting>
<para>
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 <filename>/WEB-INF/hotels/booking/enterBookingDetails.xhtml</filename>.
For example, the state above might render <filename>/WEB-INF/hotels/booking/enterBookingDetails.xhtml</filename>
if the flow itself was located in the <filename>/WEB-INF/hotels/booking</filename> directory.
</para>
</sect2>
<sect2 id="transition-element">
<title>The transition element</title>
<title>transition</title>
<para>
Use the <code>transition</code> element to handle events that occur within a state:
</para>
@@ -106,7 +107,7 @@
</para>
</sect2>
<sect2 id="end-state-element">
<title>The end-state element</title>
<title>end-state</title>
<para>
Use the <code>end-state</code> element to define a flow outcome:
</para>
@@ -167,10 +168,10 @@
</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 for defining actions.
The next few sections will cover the essential language elements for defining actions.
</para>
<sect2 id="evaluate-element">
<title>The evaluate element</title>
<title>evaluate</title>
<para>
The action element you will use the most often is the <code>evaluate</code> element.
Use the <code>evaluate</code> element to evaluate an expression at a point within your flow.
@@ -199,45 +200,6 @@
</programlisting>
</sect3>
</sect2>
<sect2 id="set-element">
<title>The set element</title>
<para>
Use the set element when you need to assign a flow variable:
</para>
<programlisting language="xml">
&lt;set name="flowScope.selectedHotel" value="hotels.selectedRow" /&gt;
</programlisting>
<para>
Both the name and value attributes are EL expressions.
</para>
<sect3 id="set-element-null">
<title>Assigning a null value</title>
<para>
Use the special <code>null</code> keyword to assign a variable to null:
</para>
<programlisting language="xml">
&lt;set name="flowScope.selectedHotel" value="null" /&gt;
</programlisting>
</sect3>
<sect3 id="set-element-literal">
<title>Assigning a literal value</title>
<para>
Enclose a value within tick marks to assign a literal:
</para>
<programlisting language="xml">
&lt;set name="flowScope.status" value="'Processing Order'" /&gt;
</programlisting>
</sect3>
<sect3 id="set-element-result-type">
<title>Converting a value prior to variable assignment</title>
<para>
Use the <literal>type</literal> attribute to specify a desired value type:
</para>
<programlisting language="xml">
&lt;set name="flowScope.id" value="requestParameters.id" type="long" /&gt;
</programlisting>
</sect3>
</sect2>
<sect2 id="checkpoint-actions">
<title>Checkpoint: flow actions</title>
<para>
@@ -272,7 +234,7 @@
&lt;/flow&gt;
</programlisting>
<para>
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.
</para>
</sect2>
@@ -297,7 +259,7 @@ public interface FlowOutcome {
}
</programlisting>
<sect2 id="input-element">
<title>The input element</title>
<title>input</title>
<para>
Use the input element to declare a flow input attribute:
</para>
@@ -321,7 +283,7 @@ public interface FlowOutcome {
</sect3>
<sect3 id="input-element-value">
<para>
Use the <code>value</code> attribute to denote a specific expression to assign the input value to:
Use the <code>value</code> attribute to specify an expression to assign the input value to:
</para>
<programlisting language="xml">
&lt;input name="hotelId" value="flowScope.myParameterObject.hotelId" /&gt;
@@ -340,7 +302,7 @@ public interface FlowOutcome {
</sect3>
</sect2>
<sect2 id="output-element">
<title>The output element</title>
<title>output</title>
<para>
Use the <code>output</code> 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.
</para>
<para>
Use the <code>var</code> element to declare a flow variable:
</para>
<programlisting language="xml">
<sect2 id="var-element">
<title>var</title>
<para>
Use the <code>var</code> element to declare a flow variable:
</para>
<programlisting language="xml">
&lt;var name="searchCriteria" class="com.mycompany.myapp.hotels.search.SearchCriteria"/>
</programlisting>
<para>
Make sure your variable's class implements <code>java.io.Serializable</code>, as the instance state is saved between flow requests.
</para>
</programlisting>
<para>
Make sure your variable's class implements <code>java.io.Serializable</code>, as the instance state is saved between flow requests.
</para>
</sect2>
</sect1>
<sect1 id="calling-subflows">
<title>Calling subflows</title>
@@ -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.
</para>
<sect2 id="subflow-state-element">
<title>The subflow-state element</title>
<title>subflow-state</title>
<para>
Use the <code>subflow-state</code> element to call another flow as a subflow:
</para>
<programlisting language="xml">
&lt;subflow-state id="addGuest" subflow="createGuest"&gt;
&lt;transition on="guestCreated" to="reviewBooking"&gt;
&lt;evaluate expression="booking.guests.add(guest)"/>
&lt;evaluate expression="booking.guests.add(currentEvent.guest)" /&gt;
&lt;transition /&gt;
&lt;transition on="creationCancelled" to="reviewBooking" /&gt;
&lt;/subfow-state&gt;
@@ -511,37 +476,4 @@ public interface FlowOutcome {
</programlisting>
</sect2>
</sect1>
<sect1 id="simple-event-handlers">
<title>Transitions without target states</title>
<para>
Transitions without targets can also be defined:
</para>
<programlisting language="xml">
&lt;transition on="event"&gt;
&lt;-- Handle event --&gt;
&lt;/transition&gt;
</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 view or a subset of the current view.
</para>
<para>
Below is a realistic example of two transitions that handle Ajax events to page through a search results list:
</para>
<programlisting language="xml">
&lt;view-state id="searchResults"&gt;
&lt;transition on="next"&gt;
&lt;evaluate expression="searchCriteria.nextPage()" /&gt;
&lt;render fragments="hotels:resultsTable" /&gt;
&lt;/transition&gt;
&lt;transition on="previous"&gt;
&lt;evaluate expression="searchCriteria.previousPage()" /&gt;
&lt;render fragments="hotels:resultsTable" /&gt;
&lt;/transition&gt;
&lt;/view-state&gt;
</programlisting>
<para>
These transitions change the current data-page, then request re-rendering of the hotels table fragment.
</para>
</sect1>
</chapter>

251
spring-webflow-reference/src/el.xml Normal file
View File

@@ -0,0 +1,251 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="el">
<title>Expression Language (EL)</title>
<sect1 id="el-introduction">
<title>Introduction</title>
<para>
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.
</para>
</sect1>
<sect1 id="el-language-choices">
<title>Supported EL implementations</title>
<sect2 id="el-unified-el">
<title>Unified EL</title>
<para>
Web Flow attempts to use the <ulink url="http://en.wikipedia.org/wiki/Unified_Expression_Language">Unified EL</ulink> by default.
<code>jboss-el</code> is currently the default EL implementation.
When found in your classpath along with the <code>el-api</code>, it will be used automatically.
<note>
The <code>el-api</code> dependency is typically a <emphasis>provided</emphasis> by your web container. Tomcat 6 includes it, for example.
</note>
</para>
</sect2>
<sect2 id="el-ognl">
<title>OGNL</title>
<para>
<ulink url="http://www.ognl.org">OGNL</ulink> 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 <code>ognl</code> in your classpath instead of <code>jboss-el</code>.
Please refer to the <ulink url="http://www.ognl.org/2.6.9/Documentation/html/LanguageGuide/index.html">OGNL language guide</ulink> for specifics on its EL syntax.
</para>
</sect2>
</sect1>
<sect1 id="el-portability">
<title>EL Portability</title>
<para>
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.
</para>
</sect1>
<sect1 id="el-usage">
<title>EL Usage</title>
<para>
EL is used for many things within a flow, including:
</para>
<orderedlist>
<listitem><para>Accessing data provided by the client, such as flow input attributes and request parameters.</para></listitem>
<listitem><para>Accessing internal data structures such as <code>flowScope.</code></para></listitem>
<listitem><para>Invoking methods on Spring beans.</para></listitem>
<listitem><para>Resolving constructs such as state transition criteria, subflow ids, and view names.</para></listitem>
</orderedlist>
<para>
Views rendered by flows often access flow data structures using EL as well.
</para>
<sect2 id="el-types">
<title>Expression Types</title>
<para>
There are basically two types of expressions in Web Flow.
</para>
<sect3 id="el-types-eval">
<title>Standard eval expressions</title>
<para>
The first, and most common type of expression, is the standard <emphasis>eval expression</emphasis>.
Such expressions are dynamically evaluated by the EL and should not be enclosed in delimiters like <code>${}</code> or <code>#{}</code>.
For example:
</para>
<programlisting type="xml">
&lt;evaluate expression="searchCriteria.nextPage()" /&gt;
</programlisting>
<para>
The expression above is a standard expression that invokes the <code>nextPage</code> method on the <code>searchCriteria</code> variable when evaluated.
Attempting to enclose this expression in special eval delimiters like <code>${}</code> or <code>#{}</code> will result in an <code>IllegalArgumentException</code>.
<note>
We view use of special eval delimiters as redundant in this context, as the only acceptable value for the <code>expression</code> attribute is a single eval expression string.
</note>
</para>
</sect3>
<sect3 id="el-types-template">
<title>Template expressions</title>
<para>
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 <code>${}</code> delimiters.
For example:
</para>
<programlisting type="xml">
&lt;view-state id="error" view="error-${externalContext.locale}.xhtml" /&gt;
</programlisting>
<para>
The expression above is a template expression.
The result of evaluation will be a string that combines the literal text <code>error-</code> with the result of evaluating <code>externalContext.locale</code>.
As you can see, explicit delimiters are necessary here to demarcate eval blocks within the template.
</para>
</sect3>
<para>
See the Web Flow XML schema for a complete listing of the XML attributes that accept standard expressions and template expressions.
</para>
</sect2>
</sect1>
<sect1 id="el-variables">
<title>Special EL variables</title>
<para>
There are several implicit variables you may reference from within a flow.
These variables are discussed in this section.
</para>
<sect2 id="el-variable-flowScope">
<title>flowScope</title>
<para>
Use <code>flowScope</code> to assign a flow variable.
Flow scope gets allocated when a flow starts and destroyed when the flow ends.
</para>
<programlisting type="xml">
&lt;evaluate expression="searchService.findHotel(hotelId)" result="flowScope.hotel" /&gt;
</programlisting>
</sect2>
<sect2 id="el-variable-viewScope">
<title>viewScope</title>
<para>
Use <code>viewScope</code> to assign a view variable.
View scope gets allocated when a <code>view-state</code> enters and destroyed when the state exits.
View scope is <emphasis>only</emphasis> referenceable from within a <code>view-state</code>.
</para>
<programlisting type="xml">
&lt;on-render&gt;
&lt;evaluate expression="searchService.findHotels(searchCriteria)" result="viewScope.hotels" type="dataModel" /&gt;
&lt;/on-render&gt;
</programlisting>
</sect2>
<sect2 id="el-variable-requestScope">
<title>requestScope</title>
<para>
Use <code>requestScope</code> to assign a request variable.
Request scope gets allocated when a flow is called and destroyed when the flow returns.
</para>
<programlisting type="xml">
&lt;set name="requestScope.hotelId" value="requestParameters.id" type="long" /&gt;
</programlisting>
</sect2>
<sect2 id="el-variable-flashScope">
<title>flashScope</title>
<para>
Use <code>flashScope</code> to assign a flash variable.
Flash scope gets allocated when a flow starts, cleared after every view render, and destroyed when the flow ends.
</para>
<programlisting type="xml">
&lt;set name="flashScope.statusMessage" value="'Booking confirmed'" /&gt;
</programlisting>
</sect2>
<sect2 id="el-variable-conversationScope">
<title>conversationScope</title>
<para>
Use <code>conversationScope</code> 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.
</para>
<programlisting type="xml">
&lt;evaluate expression="searchService.findHotel(hotelId)" result="conversationScope.hotel" /&gt;
</programlisting>
</sect2>
<sect2 id="el-variable-requestParameters">
<title>requestParameters</title>
<para>
Use <code>requestParameters</code> to access a client request parameter:
</para>
<programlisting type="xml">
&lt;set name="requestScope.hotelId" value="requestParameters.id" type="long" /&gt;
</programlisting>
</sect2>
<sect2 id="el-variable-currentEvent">
<title>currentEvent</title>
<para>
Use <code>currentEvent</code> to access attributes of the current <code>Event</code>:
</para>
<programlisting type="xml">
&lt;evaluate expression="booking.guests.add(currentEvent.guest)" /&gt;
</programlisting>
</sect2>
<sect2 id="el-variable-currentUser">
<title>currentUser</title>
<para>
Use <code>currentUser</code> to access the authenticated <code>Principal</code>:
</para>
<programlisting type="xml">
&lt;evaluate expression="bookingService.createBooking(hotelId, currentUser.name)" result="flowScope.booking" /&gt;
</programlisting>
</sect2>
<sect2 id="el-variable-messageContext">
<title>messageContext</title>
<para>
Use <code>messageContext</code> to access a context for retrieving and creating flow execution messages, including error and success messages.
See the <code>MessageContext</code> Javadocs for more information.
</para>
<programlisting type="xml">
&lt;evaluate expression="bookingValidator.validate(booking, messageContext)" /&gt;
</programlisting>
</sect2>
<sect2 id="el-variable-requestContext">
<title>flowRequestContext</title>
<para>
Use <code>flowRequestContext</code> to access the <code>RequestContext</code> API, which is a representation of the current flow request.
See the API Javadocs for more information.
</para>
</sect2>
<sect2 id="el-variable-flowExecutionContext">
<title>flowExecutionContext</title>
<para>
Use <code>flowExecutionContext</code> to access the <code>FlowExecutionContext</code> API, which is a representation of the current flow state.
See the API Javadocs for more information.
</para>
</sect2>
<sect2 id="el-variable-flowExecutionUrl">
<title>flowExecutionUrl</title>
<para>
Use <code>flowExecutionUrl</code> to access the context-relative URI for the current flow execution view-state.
</para>
</sect2>
<sect2 id="el-variable-externalContext">
<title>externalContext</title>
<para>
Use <code>externalContext</code> to access the client environment, including user session attributes.
See the <code>ExternalContext</code> API JavaDocs for more information.
</para>
<programlisting type="xml">
&lt;evaluate expression="searchService.suggestHotels(externalContext.sessionMap.userProfile)" result="viewScope.hotels" /&gt;
</programlisting>
</sect2>
</sect1>
<sect1 id="el-scope-searching">
<title>Scope Searching Algorithm</title>
<para>
When assigning a variable in one of the flow scopes, referencing that scope is required.
For example:
</para>
<programlisting type="xml">
&lt;set name="requestScope.hotelId" value="requestParameters.id" type="long" /&gt;
</programlisting>
<para>
When simply accessing a variable in one of the scopes, referencing the scope is optional.
For example:
</para>
<programlisting type="xml">
&lt;evaluate expression="entityManager.persist(booking)" /&gt;
</programlisting>
<para>
If no scope is specified, like in the use of <code>booking</code> 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 <code>EvaluationException</code> will be thrown.
</para>
</sect1>
</chapter>

17
spring-webflow-reference/src/spring-webflow-reference.xml
View File

@@ -4,6 +4,7 @@
[
<!ENTITY overview SYSTEM "overview.xml">
<!ENTITY defining-flows SYSTEM "defining-flows.xml">
<!ENTITY el SYSTEM "el.xml">
<!ENTITY flow-security SYSTEM "flow-security.xml">
<!ENTITY flow-inheritance SYSTEM "flow-inheritance.xml">
]>
@@ -18,22 +19,37 @@
<author>
<firstname>Keith</firstname>
<surname>Donald</surname>
<affiliation>
<orgname>SpringSource</orgname>
</affiliation>
</author>
<author>
<firstname>Erwin</firstname>
<surname>Vervaet</surname>
<affiliation>
<orgname>Ervacon</orgname>
</affiliation>
</author>
<author>
<firstname>Jeremy</firstname>
<surname>Grelle</surname>
<affiliation>
<orgname>SpringSource</orgname>
</affiliation>
</author>
<author>
<firstname>Scott</firstname>
<surname>Andrews</surname>
<affiliation>
<orgname>SpringSource</orgname>
</affiliation>
</author>
<author>
<firstname>Rossen</firstname>
<surname>Stoyanchev</surname>
<affiliation>
<orgname>SpringSource</orgname>
</affiliation>
</author>
</authorgroup>
<legalnotice>
@@ -51,6 +67,7 @@
&overview;
&defining-flows;
&el;
&flow-security;
&flow-inheritance;