diff --git a/spring-webflow/docs/reference/src/flow-executor.xml b/spring-webflow/docs/reference/src/flow-executor.xml index 4d626994..538238b8 100644 --- a/spring-webflow/docs/reference/src/flow-executor.xml +++ b/spring-webflow/docs/reference/src/flow-executor.xml @@ -295,57 +295,6 @@ - - Spring MVC integration - - 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. - - - For both Servlet and Portlet MVC, a FlowController 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. - - - A single flow controller executing all flows in a Servlet MVC environment - - <bean name="/flowController.htm" class="org.springframework.webflow.executor.mvc.FlowController"> - <property name="flowExecutor" ref="flowExecutor"/> - </bean> - - - This controller, exported at the context-relative /flowController.htm URL, - delegates to the configured flow executor for driving flow executions in a Spring Servlet - MVC environment. - - - - A single portlet flow controller executing a flow within a Portlet - - <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> - - - 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 search-flow - will be launched). - - - Flow executor parameterization @@ -493,6 +442,57 @@ + + Spring MVC integration + + 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. + + + For both Servlet and Portlet MVC, a FlowController 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. + + + A single flow controller executing all flows in a Servlet MVC environment + + <bean name="/flowController.htm" class="org.springframework.webflow.executor.mvc.FlowController"> + <property name="flowExecutor" ref="flowExecutor"/> + </bean> + + + This controller, exported at the context-relative /flowController.htm URL, + delegates to the configured flow executor for driving flow executions in a Spring Servlet + MVC environment. + + + + A single portlet flow controller executing a flow within a Portlet + + <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> + + + 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 search-flow + will be launched). + + + Struts integration @@ -514,271 +514,4 @@ - - Java Server Faces (JSF) integration - - 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. - - - 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. - - - Adding Spring Web Flow extensions to faces-config.xml - - Using Spring Web Flow in a JSF environment requires adding these custom artifacts to the application's - faces-config.xml file: - - -<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> - - - 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 - participating in the flow. Outcome strings are treated as events signaled against the current view state - of the flow execution automatically. - - - The DelegatingFlowVariableResolver 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. - - - - Configuring the Web Flow system - - 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: - - -<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> - - - This context should contain the Web Flow system configuration. - The example webflow-config.xml below shows a typical Web Flow configuration for a JSF environment: - - -<?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> - - - A bean named flowExecutor must be configured and linked with a flow definition registry - that contains the flows eligible for execution. Note the flowExecutor bean name is significant, - as that is bean name the Web Flow JSF extensions will expect. - - - Any flow 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"/> - - - The command link above says launch 'myflow' when clicked. 'myflow' is expected - to be a valid id of a flow definition registered in the configured registry. - - - - By default, an action outcome prefixed with flowId: 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. - - - - - Launching a flow execution - normal HTML anchor - - 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> - - - 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. - - - - Flow definitions in a JSF environment - - Flow definitions in a JSF environment are just plain Spring Web Flow definitions: - - -<?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> - - - 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. - - - 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. - - - - Resuming a flow execution - form bound to flow execution variables - - Views participating in flows are just plain JSF views. They may also incorporate other - JSF view technologies such as Facelets and Ajax4JSF. - - -<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> - - - 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. - - - - Spring Web Flow JSF Integration Samples - - See the sellitem-jsf sample that illustrates Spring Web Flow operating in - a JSF environment. - - - - A pre Spring Web Flow 1.0.2 faces-config.xml file - - 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 - (and not the other scopes such as flash and conversation shown above). This configuration is still supported - for backwards compatibility reasons: - - -<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> - - - - With 1.0.2 DelegatingFlowVariableResolver 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. - - - - - 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 - - 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 just plain JSF. - - -<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> - - - 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. - - - \ No newline at end of file diff --git a/spring-webflow/docs/reference/src/index.xml b/spring-webflow/docs/reference/src/index.xml index 1af1c955..e71f56d4 100644 --- a/spring-webflow/docs/reference/src/index.xml +++ b/spring-webflow/docs/reference/src/index.xml @@ -7,6 +7,7 @@ + ]> @@ -78,6 +79,7 @@ &flow-execution; &flow-execution-repository; &flow-executor; + &spring-faces; &practical; \ No newline at end of file diff --git a/spring-webflow/docs/reference/src/overview.xml b/spring-webflow/docs/reference/src/overview.xml index eb3b8b93..54d8dd32 100644 --- a/spring-webflow/docs/reference/src/overview.xml +++ b/spring-webflow/docs/reference/src/overview.xml @@ -550,20 +550,6 @@ Core, Struts 1.1 - - - Java Server Faces (JSF) - - The integration between Spring Web Flow and the Java Server Faces framework. - - - executor.jsf - - None - - Core, - JSF 1.0 - diff --git a/spring-webflow/docs/reference/src/spring-faces.xml b/spring-webflow/docs/reference/src/spring-faces.xml new file mode 100644 index 00000000..25523a56 --- /dev/null +++ b/spring-webflow/docs/reference/src/spring-faces.xml @@ -0,0 +1,233 @@ + + + Spring Faces + + Introduction + + + + Code Example + + + Sub section + + + + Tip + + + + + Sub-sub section + + + + Note + + + + + + + + Web Flow Java Server Faces (JSF) integration + + 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. + + + 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. + + + Adding Spring Web Flow extensions to faces-config.xml + + Using Spring Web Flow in a JSF environment requires adding these custom artifacts to the application's + faces-config.xml file: + + +<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> + + + 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 + participating in the flow. Outcome strings are treated as events signaled against the current view state + of the flow execution automatically. + + + The DelegatingFlowVariableResolver 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. + + + + Configuring the Web Flow system + + 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: + + +<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> + + + This context should contain the Web Flow system configuration. + The example webflow-config.xml below shows a typical Web Flow configuration for a JSF environment: + + +<?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> + + + A bean named flowExecutor must be configured and linked with a flow definition registry + that contains the flows eligible for execution. Note the flowExecutor bean name is significant, + as that is bean name the Web Flow JSF extensions will expect. + + + Any flow 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"/> + + + The command link above says launch 'myflow' when clicked. 'myflow' is expected + to be a valid id of a flow definition registered in the configured registry. + + + + By default, an action outcome prefixed with flowId: 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. + + + + + Launching a flow execution - normal HTML anchor + + 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> + + + 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. + + + + Flow definitions in a JSF environment + + Flow definitions in a JSF environment are just plain Spring Web Flow definitions: + + +<?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> + + + 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. + + + 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. + + + + Resuming a flow execution - form bound to flow execution variables + + Views participating in flows are just plain JSF views. They may also incorporate other + JSF view technologies such as Facelets and Ajax4JSF. + + +<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> + + + 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. + + + + Spring Web Flow JSF Integration Samples + + See the sellitem-jsf sample that illustrates Spring Web Flow operating in + a JSF environment. + + + + \ No newline at end of file