diff --git a/spring-webflow/docs/reference/src/flow-executor.xml b/spring-webflow/docs/reference/src/flow-executor.xml index 59b0b764..ca18c124 100644 --- a/spring-webflow/docs/reference/src/flow-executor.xml +++ b/spring-webflow/docs/reference/src/flow-executor.xml @@ -551,8 +551,8 @@ </faces-config> - The FlowPhaseListener 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. + The FlowPhaseListener 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. The FlowNavigationHandler is required to continue a flow on an action outcome from a JSF view @@ -565,13 +565,62 @@ it finds a match. If no match is found this resolver delegates to the next resolver in the chain. + + + The artifacts defined faces-config.xml and managed by the JSF provider use Spring to locate + the Web Flow system. A Spring Web Application Context is bootstrapped using a ContextLoaderListener + in the web.xml deployment descriptor: + + +<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> + + + In this example inside webflow-config.xml resides the configuration of the Web Flow system the JSF + artifacts will delegate to. A bean named flowExecutor is configured and + linked with a flow definition registry containing the flows eligible for execution: + + +<?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> + + + Any executor property such as the flow execution repository type is configurable here, consistent + with the other environments Spring Web Flow supports. + + Launching a flow execution - JSF command link component Flows can be launched by firing JSF action outcomes that adhere to a special format: - <h:commandLink value="Go" action="flowId:myflow"/> +<h:commandLink value="Go" action="flowId:myflow"/> The command link above says launch 'myflow' when clicked. @@ -589,7 +638,7 @@ Flows can also be launched simply by accessing flow definition URLs directly using a bookmark or normal HTML link: - <a href="app.faces?flowId=myflow">Go</a> +<a href="app.faces?flowId=myflow">Go</a> This example link assumes *.faces has been mapped to the FacesServlet defined within web.xml. @@ -597,7 +646,7 @@ - Sample flow in a JSF environment + Flow definitions in a JSF environment Flow definitions in a JSF environment are just plain Spring Web Flow definitions: @@ -621,14 +670,15 @@ </flow> - A benefit of using JSF is UI components typically handle data binding and validation, so the actual flow - definition logic is often simpler and more focused. 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. + A primary benefit of using JSF is it a rich UI component framework, and components have behaviors. + As JSF components typically handle data binding and validation behaviors, the actual flow + definition logic is often simpler and more focused as a result. - How Spring Web Flow view names are mapped to JSF view ids is configurable. See the - FlowPhaseListener API documentation for more information. + 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 FlowPhaseListener API documentation for more information. @@ -664,7 +714,7 @@ A pre Spring Web Flow 1.0.2 faces-config.xml file - This section applies to those using Spring Web Flow's JSF integration before release 1.0.2. + The following three sections apply only to those using Spring Web Flow's JSF integration before release 1.0.2. Before release 1.0.2, Spring Web Flow only supported resolving variables in flow scope @@ -692,6 +742,17 @@ + + A pre Spring Web Flow 1.0.2 Web Flow system configuration + + Before release 1.0.2, Spring Web Flow did not support the configuration of a flowExecutor + 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 <flow:executor/> tag in the + webflow-config namespace for consistency and simplicity. + + Resuming a flow execution - pre Spring Web Flow 1.0.2