added initial spring-faces chapter focusing on jsf integration
This commit is contained in:
Keith Donald
@@ -295,57 +295,6 @@
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
<sect1 id="executor-mvc">
|
||||
<title>Spring MVC integration</title>
|
||||
<para>
|
||||
Spring Web Flow integrates with both Servlet and Portlet MVC which ship with the
|
||||
core Spring Framework. Use of Portlet MVC requires Spring 2.0.
|
||||
</para>
|
||||
<para>
|
||||
For both Servlet and Portlet MVC, a <literal>FlowController</literal> acts as an adapter
|
||||
between Spring MVC and Spring Web Flow. As an adapter, this controller has knowledge
|
||||
of both systems and delegates to a flow executor for driving the execution of flows.
|
||||
One controller typically executes all flows of an application, relying on
|
||||
parameterization to determine what flow to launch or what flow execution to resume.
|
||||
</para>
|
||||
<sect2 id="executor-servletmvc">
|
||||
<title>A single flow controller executing all flows in a Servlet MVC environment</title>
|
||||
<programlisting>
|
||||
<bean name="/flowController.htm" class="org.springframework.webflow.executor.mvc.FlowController">
|
||||
<property name="flowExecutor" ref="flowExecutor"/>
|
||||
</bean>
|
||||
</programlisting>
|
||||
<para>
|
||||
This controller, exported at the context-relative <literal>/flowController.htm</literal> URL,
|
||||
delegates to the configured flow executor for driving flow executions in a Spring Servlet
|
||||
MVC environment.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2 id="executor-portletmvc">
|
||||
<title>A single portlet flow controller executing a flow within a Portlet</title>
|
||||
<programlisting>
|
||||
<bean id="portletModeControllerMapping"
|
||||
class="org.springframework.web.portlet.handler.PortletModeHandlerMapping">
|
||||
<property name="portletModeMap">
|
||||
<map>
|
||||
<entry key="view" value-ref="flowController"/>
|
||||
</map>
|
||||
</property>
|
||||
</bean>
|
||||
|
||||
<bean id="flowController" class="org.springframework.webflow.executor.mvc.PortletFlowController">
|
||||
<property name="flowExecutor" ref="flowExecutor"/>
|
||||
<property name="defaultFlowId" ref="search-flow"/>
|
||||
</bean>
|
||||
</programlisting>
|
||||
<para>
|
||||
This controller, exported for access with the configured portlet mode,
|
||||
delegates to the configured flow executor for driving flow executions in a Spring Portlet
|
||||
MVC environment (by default, an execution of the <literal>search-flow</literal>
|
||||
will be launched).
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
<sect1 id="executor-parameterization">
|
||||
<title>Flow executor parameterization</title>
|
||||
<para>
|
||||
@@ -493,6 +442,57 @@
|
||||
</sect3>
|
||||
</sect2>
|
||||
</sect1>
|
||||
<sect1 id="executor-mvc">
|
||||
<title>Spring MVC integration</title>
|
||||
<para>
|
||||
Spring Web Flow integrates with both Servlet and Portlet MVC which ship with the
|
||||
core Spring Framework. Use of Portlet MVC requires Spring 2.0.
|
||||
</para>
|
||||
<para>
|
||||
For both Servlet and Portlet MVC, a <literal>FlowController</literal> acts as an adapter
|
||||
between Spring MVC and Spring Web Flow. As an adapter, this controller has knowledge
|
||||
of both systems and delegates to a flow executor for driving the execution of flows.
|
||||
One controller typically executes all flows of an application, relying on
|
||||
parameterization to determine what flow to launch or what flow execution to resume.
|
||||
</para>
|
||||
<sect2 id="executor-servletmvc">
|
||||
<title>A single flow controller executing all flows in a Servlet MVC environment</title>
|
||||
<programlisting>
|
||||
<bean name="/flowController.htm" class="org.springframework.webflow.executor.mvc.FlowController">
|
||||
<property name="flowExecutor" ref="flowExecutor"/>
|
||||
</bean>
|
||||
</programlisting>
|
||||
<para>
|
||||
This controller, exported at the context-relative <literal>/flowController.htm</literal> URL,
|
||||
delegates to the configured flow executor for driving flow executions in a Spring Servlet
|
||||
MVC environment.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2 id="executor-portletmvc">
|
||||
<title>A single portlet flow controller executing a flow within a Portlet</title>
|
||||
<programlisting>
|
||||
<bean id="portletModeControllerMapping"
|
||||
class="org.springframework.web.portlet.handler.PortletModeHandlerMapping">
|
||||
<property name="portletModeMap">
|
||||
<map>
|
||||
<entry key="view" value-ref="flowController"/>
|
||||
</map>
|
||||
</property>
|
||||
</bean>
|
||||
|
||||
<bean id="flowController" class="org.springframework.webflow.executor.mvc.PortletFlowController">
|
||||
<property name="flowExecutor" ref="flowExecutor"/>
|
||||
<property name="defaultFlowId" ref="search-flow"/>
|
||||
</bean>
|
||||
</programlisting>
|
||||
<para>
|
||||
This controller, exported for access with the configured portlet mode,
|
||||
delegates to the configured flow executor for driving flow executions in a Spring Portlet
|
||||
MVC environment (by default, an execution of the <literal>search-flow</literal>
|
||||
will be launched).
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
<sect1 id="executor-struts">
|
||||
<title>Struts integration</title>
|
||||
<para>
|
||||
@@ -514,271 +514,4 @@
|
||||
</programlisting>
|
||||
</sect2>
|
||||
</sect1>
|
||||
<sect1 id="executor-jsf">
|
||||
<title>Java Server Faces (JSF) integration</title>
|
||||
<para>
|
||||
Spring Web Flow provides strong integration with Java Server Faces (JSF). When used with JSF, Spring Web Flow
|
||||
takes responsibility for view navigation handling and managing model state, adding power and
|
||||
simplicity to JSF's default navigation system and object scopes. Plain JSF views and components continue to work just as before,
|
||||
and are able to participate in flows with full access to flow state. In addition, other view technologies
|
||||
such as Facelets continue to plug-in normally.
|
||||
</para>
|
||||
<para>
|
||||
The JSF integration relies on custom implementations of core JSF artifacts such as the PhaseListener
|
||||
and NavigationHandler to drive the execution of flows. In addition, it relies on a custom VariableResolver to
|
||||
access flow execution attributes from JSF components.
|
||||
</para>
|
||||
<sect2 id="executor-jsf-simple">
|
||||
<title>Adding Spring Web Flow extensions to faces-config.xml</title>
|
||||
<para>
|
||||
Using Spring Web Flow in a JSF environment requires adding these custom artifacts to the application's
|
||||
<literal>faces-config.xml</literal> file:
|
||||
</para>
|
||||
<programlisting>
|
||||
<faces-config>
|
||||
<application>
|
||||
<navigation-handler>org.springframework.webflow.executor.jsf.FlowNavigationHandler</navigation-handler>
|
||||
<variable-resolver>org.springframework.webflow.executor.jsf.DelegatingFlowVariableResolver</variable-resolver>
|
||||
</application>
|
||||
|
||||
<lifecycle>
|
||||
<phase-listener>org.springframework.webflow.executor.jsf.FlowPhaseListener</phase-listener>
|
||||
</lifecycle>
|
||||
</faces-config>
|
||||
</programlisting>
|
||||
<para>
|
||||
The <classname>FlowPhaseListener</classname> is required to manage the overall flow execution lifecycle in a JSF environment.
|
||||
It handles launching new flows accessed by browsers via direct URLs, and also handles restoring flow executions on postback and browser refreshes.
|
||||
</para>
|
||||
<para>
|
||||
The <classname>FlowNavigationHandler</classname> is required to continue a flow on an action outcome from a JSF view
|
||||
participating in the flow. Outcome strings are treated as events signaled against the current view state
|
||||
of the flow execution automatically.
|
||||
</para>
|
||||
<para>
|
||||
The <classname>DelegatingFlowVariableResolver</classname> resolves JSF a value binding expression like {#someBean.someProperty}
|
||||
to a flow execution attribute. This resolver searches flash, flow, and conversation scope in that order until
|
||||
it finds a match. If no match is found, this resolver delegates to the next resolver in the chain.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2 id="executor-jsf-simple-webflow-setup">
|
||||
<title>Configuring the Web Flow system</title>
|
||||
<para>
|
||||
The artifacts defined in the faces-config.xml use Spring to access the Web Flow system configuration.
|
||||
This requires a Spring Web Application Context to be bootstrapped using a ContextLoaderListener in
|
||||
the web.xml deployment descriptor:
|
||||
</para>
|
||||
<programlisting>
|
||||
<context-param>
|
||||
<param-name>contextConfigLocation</param-name>
|
||||
<param-value>
|
||||
/WEB-INF/webflow-config.xml
|
||||
</param-value>
|
||||
</context-param>
|
||||
|
||||
<listener>
|
||||
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
|
||||
</listener>
|
||||
</programlisting>
|
||||
<para>
|
||||
This context should contain the Web Flow system configuration.
|
||||
The example <literal>webflow-config.xml</literal> below shows a typical Web Flow configuration for a JSF environment:
|
||||
</para>
|
||||
<programlisting>
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<beans xmlns="http://www.springframework.org/schema/beans"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xmlns:flow="http://www.springframework.org/schema/webflow-config"
|
||||
xsi:schemaLocation="
|
||||
http://www.springframework.org/schema/beans
|
||||
http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
|
||||
http://www.springframework.org/schema/webflow-config
|
||||
http://www.springframework.org/schema/webflow-config/spring-webflow-config-1.0.xsd">
|
||||
|
||||
<!-- Launches new flow executions and resumes existing executions. -->
|
||||
<flow:executor id="flowExecutor" registry-ref="flowRegistry"/>
|
||||
|
||||
<!-- Creates the registry of flow definitions for this application -->
|
||||
<flow:registry id="flowRegistry">
|
||||
<flow:location path="/WEB-INF/flows/**/*-flow.xml"/>
|
||||
</flow:registry>
|
||||
|
||||
</beans>
|
||||
</programlisting>
|
||||
<para>
|
||||
A bean named <literal>flowExecutor</literal> must be configured and linked with a flow definition registry
|
||||
that contains the flows eligible for execution. Note the <literal>flowExecutor</literal> bean name is significant,
|
||||
as that is bean name the Web Flow JSF extensions will expect.
|
||||
</para>
|
||||
<para>
|
||||
Any flow executor property such as the flow execution repository type is configurable here, consistent
|
||||
with the other environments Spring Web Flow supports.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2 id="executor-jsf-launch-commandlink">
|
||||
<title>Launching a flow execution - JSF command link component</title>
|
||||
<para>
|
||||
Flows can be launched by firing JSF action outcomes that adhere to a special format:
|
||||
</para>
|
||||
<programlisting>
|
||||
<h:commandLink value="Go" action="flowId:myflow"/>
|
||||
</programlisting>
|
||||
<para>
|
||||
The command link above says <emphasis>launch 'myflow' when clicked</emphasis>. 'myflow' is expected
|
||||
to be a valid id of a flow definition registered in the configured registry.
|
||||
</para>
|
||||
<tip>
|
||||
<para>
|
||||
By default, an action outcome prefixed with <literal>flowId:</literal> will be treated as a flow definition identifier.
|
||||
The flow id prefix respected by the FlowNavigationHandler is configurable. See the API documentation for
|
||||
more information.
|
||||
</para>
|
||||
</tip>
|
||||
</sect2>
|
||||
<sect2 id="executor-jsf-launch-normal-anchor">
|
||||
<title>Launching a flow execution - normal HTML anchor</title>
|
||||
<para>
|
||||
Flows can also be launched simply by accessing flow definition URLs directly using a bookmark or normal HTML link:
|
||||
</para>
|
||||
<programlisting>
|
||||
<a href="app.faces?_flowId=myflow">Go</a>
|
||||
</programlisting>
|
||||
<para>
|
||||
This example link assumes *.faces has been mapped to the FacesServlet defined within web.xml.
|
||||
The format of a flow definition URL is configurable on the FlowPhaseListener.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2 id="executor-jsf-sampleflow">
|
||||
<title>Flow definitions in a JSF environment</title>
|
||||
<para>
|
||||
Flow definitions in a JSF environment are just plain Spring Web Flow definitions:
|
||||
</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-1.0.xsd">
|
||||
|
||||
<var name="myBean" class="example.ManagedBeanImpl" scope="conversation" />
|
||||
|
||||
<start-state idref="displayView" />
|
||||
|
||||
<view-state id="displayView" view="/myview.jsp">
|
||||
<transition on="submit" to="displayNextView"/>
|
||||
</view-state>
|
||||
|
||||
<view-state id="displayNextView" view="/mynextview.jsp" />
|
||||
|
||||
</flow>
|
||||
</programlisting>
|
||||
<para>
|
||||
A primary benefit of using JSF is it a rich UI component framework, and UI components have both data and behavior.
|
||||
As JSF components typically handle data binding and validation behaviors, the actual flow
|
||||
definition logic is often simpler and more focused as a result.
|
||||
</para>
|
||||
<para>
|
||||
In general, it is recommended views selected by
|
||||
view states follow the standard JSF view identifier format, which requires a leading forward-slash
|
||||
and ends in a prefix. How Spring Web Flow view names are mapped to JSF view ids is configurable.
|
||||
See the <classname>FlowPhaseListener</classname> API documentation for more information.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2 id="executor-jsf-resume-form">
|
||||
<title>Resuming a flow execution - form bound to flow execution variables</title>
|
||||
<para>
|
||||
Views participating in flows are just plain JSF views. They may also incorporate other
|
||||
JSF view technologies such as Facelets and Ajax4JSF.
|
||||
</para>
|
||||
<programlisting>
|
||||
<f:view>
|
||||
<h:form id="form">
|
||||
...
|
||||
<h:inputText id="propertyName" value="#{someBean.someProperty}"/>
|
||||
...
|
||||
<h:commandButton type="submit" value="Next" action="submit"/>
|
||||
</h:form>
|
||||
</f:view>
|
||||
</programlisting>
|
||||
<para>
|
||||
As shown above, there is nothing Spring Web Flow specific here. The flow execution
|
||||
key is automatically tracked by a special UI component in the view root, so there is no need to
|
||||
track it manually. Action outcomes are automatically mapped to Spring Web Flow event identifiers
|
||||
signaled against the current state.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2 id="executor-jsf-sample">
|
||||
<title>Spring Web Flow JSF Integration Samples</title>
|
||||
<para>
|
||||
See the <link linkend="sellitem-JSF-sample">sellitem-jsf</link> sample that illustrates Spring Web Flow operating in
|
||||
a JSF environment.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2 id="executor-jsf-simple-pre-102">
|
||||
<title>A pre Spring Web Flow 1.0.2 faces-config.xml file</title>
|
||||
<note>
|
||||
<para>The following three sections apply only to those using Spring Web Flow's JSF integration before release 1.0.2.</para>
|
||||
</note>
|
||||
<para>
|
||||
Before release 1.0.2, Spring Web Flow only supported resolving variables in flow scope
|
||||
(and not the other scopes such as flash and conversation shown above). This configuration is still supported
|
||||
for backwards compatibility reasons:
|
||||
</para>
|
||||
<programlisting>
|
||||
<faces-config>
|
||||
<application>
|
||||
<navigation-handler>org.springframework.webflow.executor.jsf.FlowNavigationHandler</navigation-handler>
|
||||
<variable-resolver>org.springframework.webflow.executor.jsf.FlowVariableResolver</variable-resolver>
|
||||
<property-resolver>org.springframework.webflow.executor.jsf.FlowPropertyResolver</property-resolver>
|
||||
</application>
|
||||
|
||||
<lifecycle>
|
||||
<phase-listener>org.springframework.webflow.executor.jsf.FlowPhaseListener</phase-listener>
|
||||
</lifecycle>
|
||||
</faces-config>
|
||||
</programlisting>
|
||||
<note>
|
||||
<para>
|
||||
With 1.0.2 <classname>DelegatingFlowVariableResolver</classname> is now the recommended default resolver,
|
||||
as it allows full access to all flow execution scopes transparently from the point of view of the
|
||||
JSF view developer.
|
||||
</para>
|
||||
</note>
|
||||
</sect2>
|
||||
<sect2 id="executor-jsf-webflowsystem-pre-102">
|
||||
<title>A pre Spring Web Flow 1.0.2 Web Flow system configuration</title>
|
||||
<para>
|
||||
Before release 1.0.2, Spring Web Flow did not support the configuration of a <literal>flowExecutor</literal>
|
||||
in a JSF environment. Those who needed to customize Web Flow services such as the flow execution repository
|
||||
or registry deployed those beans individually with special bean names. This configuration is still
|
||||
supported for backwards compatability reasons. However, it is recommended that existing users of
|
||||
Spring Web Flow's JSF integration use the standard <literal><flow:executor/></literal> tag in the
|
||||
<literal>webflow-config</literal> namespace for consistency and simplicity.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2 id="executor-jsf-resume-form-pre-102">
|
||||
<title>Resuming a flow execution - pre Spring Web Flow 1.0.2</title>
|
||||
<para>
|
||||
Before release 1.0.2, the flow execution key had to be tracked manually in JSF views participating
|
||||
in a flow execution. This configuration is still supported for backwards compatibility reasons.
|
||||
However, it is highly recommended that existing users of Spring Web Flow's JSF integration
|
||||
update their views to be <emphasis>just plain JSF</emphasis>.
|
||||
</para>
|
||||
<programlisting>
|
||||
<f:view>
|
||||
<h:form id="form">
|
||||
...
|
||||
<h:inputText id="propertyName" value="#{flowScope.aFlowScopeAttribute}"/>
|
||||
...
|
||||
<input type="hidden" name="_flowExecutionKey" value="${flowExecutionKey}">
|
||||
<h:commandButton type="submit" value="Next" action="submit"/>
|
||||
</h:form>
|
||||
</f:view>
|
||||
</programlisting>
|
||||
<para>
|
||||
The hidden form field above can now be safely removed. In addition, the new variable resolver
|
||||
can be plugged in to gain access to other scopes such as flash and conversation.
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
</chapter>
|
||||
@@ -7,6 +7,7 @@
|
||||
<!ENTITY flow-execution SYSTEM "flow-execution.xml">
|
||||
<!ENTITY flow-execution-repository SYSTEM "flow-execution-repository.xml">
|
||||
<!ENTITY flow-executor SYSTEM "flow-executor.xml">
|
||||
<!ENTITY spring-faces SYSTEM "spring-faces.xml">
|
||||
<!ENTITY practical SYSTEM "practical.xml">
|
||||
]>
|
||||
|
||||
@@ -78,6 +79,7 @@
|
||||
&flow-execution;
|
||||
&flow-execution-repository;
|
||||
&flow-executor;
|
||||
&spring-faces;
|
||||
&practical;
|
||||
|
||||
</book>
|
||||
@@ -550,20 +550,6 @@
|
||||
Core,
|
||||
Struts 1.1
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>Java Server Faces (JSF)</entry>
|
||||
<entry>
|
||||
The integration between Spring Web Flow and the Java Server Faces framework.
|
||||
</entry>
|
||||
<entry>
|
||||
executor.jsf
|
||||
</entry>
|
||||
<entry>None</entry>
|
||||
<entry>
|
||||
Core,
|
||||
JSF 1.0
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
|
||||
233
spring-webflow/docs/reference/src/spring-faces.xml
Normal file
233
spring-webflow/docs/reference/src/spring-faces.xml
Normal file
@@ -0,0 +1,233 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<chapter id="spring-faces">
|
||||
<title>Spring Faces</title>
|
||||
<sect1 id="spring-faces-intro">
|
||||
<title>Introduction</title>
|
||||
<para>
|
||||
</para>
|
||||
<programlisting>
|
||||
Code Example
|
||||
</programlisting>
|
||||
<sect2>
|
||||
<title>Sub section</title>
|
||||
<para>
|
||||
<tip>
|
||||
<para>
|
||||
Tip
|
||||
</para>
|
||||
</tip>
|
||||
</para>
|
||||
<sect3>
|
||||
<title>Sub-sub section</title>
|
||||
<para>
|
||||
<note>
|
||||
<para>
|
||||
Note
|
||||
</para>
|
||||
</note>
|
||||
</para>
|
||||
</sect3>
|
||||
</sect2>
|
||||
</sect1>
|
||||
<sect1 id="jsf-webflow">
|
||||
<title>Web Flow Java Server Faces (JSF) integration</title>
|
||||
<para>
|
||||
Spring Web Flow provides strong integration with Java Server Faces (JSF). When used with JSF, Spring Web Flow
|
||||
takes responsibility for view navigation handling and managing model state, adding power and
|
||||
simplicity to JSF's default navigation system and object scopes. Plain JSF views and components continue to work just as before,
|
||||
and are able to participate in flows with full access to flow state. In addition, other view technologies
|
||||
such as Facelets continue to plug-in normally.
|
||||
</para>
|
||||
<para>
|
||||
The JSF integration relies on custom implementations of core JSF artifacts such as the PhaseListener
|
||||
and NavigationHandler to drive the execution of flows. In addition, it relies on a custom VariableResolver to
|
||||
access flow execution attributes from JSF components.
|
||||
</para>
|
||||
<sect2 id="executor-jsf-simple">
|
||||
<title>Adding Spring Web Flow extensions to faces-config.xml</title>
|
||||
<para>
|
||||
Using Spring Web Flow in a JSF environment requires adding these custom artifacts to the application's
|
||||
<literal>faces-config.xml</literal> file:
|
||||
</para>
|
||||
<programlisting>
|
||||
<faces-config>
|
||||
<application>
|
||||
<navigation-handler>org.springframework.webflow.executor.jsf.FlowNavigationHandler</navigation-handler>
|
||||
<variable-resolver>org.springframework.webflow.executor.jsf.DelegatingFlowVariableResolver</variable-resolver>
|
||||
</application>
|
||||
|
||||
<lifecycle>
|
||||
<phase-listener>org.springframework.webflow.executor.jsf.FlowPhaseListener</phase-listener>
|
||||
</lifecycle>
|
||||
</faces-config>
|
||||
</programlisting>
|
||||
<para>
|
||||
The <classname>FlowPhaseListener</classname> is required to manage the overall flow execution lifecycle in a JSF environment.
|
||||
It handles launching new flows accessed by browsers via direct URLs, and also handles restoring flow executions on postback and browser refreshes.
|
||||
</para>
|
||||
<para>
|
||||
The <classname>FlowNavigationHandler</classname> is required to continue a flow on an action outcome from a JSF view
|
||||
participating in the flow. Outcome strings are treated as events signaled against the current view state
|
||||
of the flow execution automatically.
|
||||
</para>
|
||||
<para>
|
||||
The <classname>DelegatingFlowVariableResolver</classname> resolves JSF a value binding expression like {#someBean.someProperty}
|
||||
to a flow execution attribute. This resolver searches flash, flow, and conversation scope in that order until
|
||||
it finds a match. If no match is found, this resolver delegates to the next resolver in the chain.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2 id="executor-jsf-simple-webflow-setup">
|
||||
<title>Configuring the Web Flow system</title>
|
||||
<para>
|
||||
The artifacts defined in the faces-config.xml use Spring to access the Web Flow system configuration.
|
||||
This requires a Spring Web Application Context to be bootstrapped using a ContextLoaderListener in
|
||||
the web.xml deployment descriptor:
|
||||
</para>
|
||||
<programlisting>
|
||||
<context-param>
|
||||
<param-name>contextConfigLocation</param-name>
|
||||
<param-value>
|
||||
/WEB-INF/webflow-config.xml
|
||||
</param-value>
|
||||
</context-param>
|
||||
|
||||
<listener>
|
||||
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
|
||||
</listener>
|
||||
</programlisting>
|
||||
<para>
|
||||
This context should contain the Web Flow system configuration.
|
||||
The example <literal>webflow-config.xml</literal> below shows a typical Web Flow configuration for a JSF environment:
|
||||
</para>
|
||||
<programlisting>
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<beans xmlns="http://www.springframework.org/schema/beans"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xmlns:flow="http://www.springframework.org/schema/webflow-config"
|
||||
xsi:schemaLocation="
|
||||
http://www.springframework.org/schema/beans
|
||||
http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
|
||||
http://www.springframework.org/schema/webflow-config
|
||||
http://www.springframework.org/schema/webflow-config/spring-webflow-config-1.0.xsd">
|
||||
|
||||
<!-- Launches new flow executions and resumes existing executions. -->
|
||||
<flow:executor id="flowExecutor" registry-ref="flowRegistry"/>
|
||||
|
||||
<!-- Creates the registry of flow definitions for this application -->
|
||||
<flow:registry id="flowRegistry">
|
||||
<flow:location path="/WEB-INF/flows/**/*-flow.xml"/>
|
||||
</flow:registry>
|
||||
|
||||
</beans>
|
||||
</programlisting>
|
||||
<para>
|
||||
A bean named <literal>flowExecutor</literal> must be configured and linked with a flow definition registry
|
||||
that contains the flows eligible for execution. Note the <literal>flowExecutor</literal> bean name is significant,
|
||||
as that is bean name the Web Flow JSF extensions will expect.
|
||||
</para>
|
||||
<para>
|
||||
Any flow executor property such as the flow execution repository type is configurable here, consistent
|
||||
with the other environments Spring Web Flow supports.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2 id="executor-jsf-launch-commandlink">
|
||||
<title>Launching a flow execution - JSF command link component</title>
|
||||
<para>
|
||||
Flows can be launched by firing JSF action outcomes that adhere to a special format:
|
||||
</para>
|
||||
<programlisting>
|
||||
<h:commandLink value="Go" action="flowId:myflow"/>
|
||||
</programlisting>
|
||||
<para>
|
||||
The command link above says <emphasis>launch 'myflow' when clicked</emphasis>. 'myflow' is expected
|
||||
to be a valid id of a flow definition registered in the configured registry.
|
||||
</para>
|
||||
<tip>
|
||||
<para>
|
||||
By default, an action outcome prefixed with <literal>flowId:</literal> will be treated as a flow definition identifier.
|
||||
The flow id prefix respected by the FlowNavigationHandler is configurable. See the API documentation for
|
||||
more information.
|
||||
</para>
|
||||
</tip>
|
||||
</sect2>
|
||||
<sect2 id="executor-jsf-launch-normal-anchor">
|
||||
<title>Launching a flow execution - normal HTML anchor</title>
|
||||
<para>
|
||||
Flows can also be launched simply by accessing flow definition URLs directly using a bookmark or normal HTML link:
|
||||
</para>
|
||||
<programlisting>
|
||||
<a href="app.faces?_flowId=myflow">Go</a>
|
||||
</programlisting>
|
||||
<para>
|
||||
This example link assumes *.faces has been mapped to the FacesServlet defined within web.xml.
|
||||
The format of a flow definition URL is configurable on the FlowPhaseListener.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2 id="executor-jsf-sampleflow">
|
||||
<title>Flow definitions in a JSF environment</title>
|
||||
<para>
|
||||
Flow definitions in a JSF environment are just plain Spring Web Flow definitions:
|
||||
</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-1.0.xsd">
|
||||
|
||||
<var name="myBean" class="example.ManagedBeanImpl" scope="conversation" />
|
||||
|
||||
<start-state idref="displayView" />
|
||||
|
||||
<view-state id="displayView" view="/myview.jsp">
|
||||
<transition on="submit" to="displayNextView"/>
|
||||
</view-state>
|
||||
|
||||
<view-state id="displayNextView" view="/mynextview.jsp" />
|
||||
|
||||
</flow>
|
||||
</programlisting>
|
||||
<para>
|
||||
A primary benefit of using JSF is it a rich UI component framework, and UI components have both data and behavior.
|
||||
As JSF components typically handle data binding and validation behaviors, the actual flow
|
||||
definition logic is often simpler and more focused as a result.
|
||||
</para>
|
||||
<para>
|
||||
In general, it is recommended views selected by
|
||||
view states follow the standard JSF view identifier format, which requires a leading forward-slash
|
||||
and ends in a prefix. How Spring Web Flow view names are mapped to JSF view ids is configurable.
|
||||
See the <classname>FlowPhaseListener</classname> API documentation for more information.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2 id="executor-jsf-resume-form">
|
||||
<title>Resuming a flow execution - form bound to flow execution variables</title>
|
||||
<para>
|
||||
Views participating in flows are just plain JSF views. They may also incorporate other
|
||||
JSF view technologies such as Facelets and Ajax4JSF.
|
||||
</para>
|
||||
<programlisting>
|
||||
<f:view>
|
||||
<h:form id="form">
|
||||
...
|
||||
<h:inputText id="propertyName" value="#{someBean.someProperty}"/>
|
||||
...
|
||||
<h:commandButton type="submit" value="Next" action="submit"/>
|
||||
</h:form>
|
||||
</f:view>
|
||||
</programlisting>
|
||||
<para>
|
||||
As shown above, there is nothing Spring Web Flow specific here. The flow execution
|
||||
key is automatically tracked by a special UI component in the view root, so there is no need to
|
||||
track it manually. Action outcomes are automatically mapped to Spring Web Flow event identifiers
|
||||
signaled against the current state.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2 id="executor-jsf-sample">
|
||||
<title>Spring Web Flow JSF Integration Samples</title>
|
||||
<para>
|
||||
See the <link linkend="sellitem-JSF-sample">sellitem-jsf</link> sample that illustrates Spring Web Flow operating in
|
||||
a JSF environment.
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
</chapter>
|
||||
Reference in New Issue
Block a user