diff --git a/spring-webflow-reference/src/flow-definition-field-mappings.xml b/spring-webflow-reference/src/flow-definition-field-mappings.xml
index d9659d73..6ca35e87 100644
--- a/spring-webflow-reference/src/flow-definition-field-mappings.xml
+++ b/spring-webflow-reference/src/flow-definition-field-mappings.xml
@@ -612,7 +612,7 @@
name or value
- name when in flow element, value when in subflow-state element
+ value when in flow element, name when in subflow-state element
diff --git a/spring-webflow-reference/src/portlet.xml b/spring-webflow-reference/src/portlet.xml
index 8bb874b9..2f53547e 100644
--- a/spring-webflow-reference/src/portlet.xml
+++ b/spring-webflow-reference/src/portlet.xml
@@ -5,6 +5,228 @@
Introduction
This chapter shows you how to use Web Flow in a Portlet environment.
+ Web Flow has full support for JSR-168 portlets.
+ The booking-portlet-mvc sample application is a good reference for using Web Flow within a portlet.
+ This application is a simplified travel site that allows users to search for and book hotel rooms.
-
\ No newline at end of file
+
+ Configuring web.xml & portlet.xml
+
+ The configuration for a portlet depends on the portlet container used.
+ The booking-portlet-mvc and booking-portlet-faces sample application are both configured to use Apache Pluto, the JSR-168 reference implementation.
+
+
+ In general the configuration requires adding a servlet mapping in the web.xml file to dispatch request to the portlet container.
+
+
+ swf-booking-mvc
+ org.apache.pluto.core.PortletServlet
+
+ portlet-name
+ swf-booking-mvc
+
+ 1
+
+
+
+ swf-booking-mvc
+ /PlutoInvoker/swf-booking-mvc
+
+ ]]>
+
+ The portlet.xml configuration is a standard portlet configuration.
+ The portlet-class needs to be set along with a pair of init-params.
+ Setting the expiration-cache to 0 is recommended to force Web Flow to always render a fresh view.
+
+
+ ...
+
+ org.springframework.web.portlet.DispatcherPortlet
+
+
+ contextConfigLocation
+
+ /WEB-INF/web-application-config.xml
+
+
+
+ viewRendererUrl
+ /WEB-INF/servlet/view
+
+ 0
+ ...
+
+ ]]>
+
+
+ Configuring Spring
+
+ Flow Handlers
+
+ The only supported mechanism for bridging a portlet request to Web Flow is via a FlowHandler.
+ The PortletFlowController used in Web Flow 1.0 is no longer supported.
+
+
+ The flow handler, similar to the servlet flow handler, provides hooks that can:
+
+
+ select the flow to execute
+
+
+ pass input parameters to the flow on initialization
+
+
+ handle the flow execution outcome
+
+
+ handle any exceptions
+
+
+ The AbstractFlowHandler class is an implementation of FlowHandler that provides default implementations for these hooks.
+
+
+ In a portlet environment the targeted flow id can not be inferred from the URL and must be defined explicitly in the handler.
+
+
+
+
+ Adapter Mappings
+
+ Spring Portlet MVC provides a rich set of methods to map portlet requests.
+ Complete documentation of the available methods is available in the Spring Reference Documentation.
+
+
+ The booking-portlet-mvc sample application uses a PortletModeHandlerMapping to map portlet requests.
+ The sample application only supports view mode, but support for other portlet modes is available.
+ Other modes can be added and point to the same flow as view mode, or any other flow.
+
+
+
+
+
+
+ ]]>
+
+
+ Flow Handler Adapter
+
+ A FlowHandlerAdapter converts the handler mappings to the flow handlers.
+ The flow executor is required as a constructor argument.
+
+
+
+
+ ]]>
+
+
+ Redirect on Pause
+
+ In a portlet environemnt, alwaysRedirectOnPause must be set to false.
+ If not turned off, the initial view will fail to render.
+
+
+
+
+
+
+ ]]>
+
+
+
+ Portlet Views
+
+ In order to facilitate view rendering, a ViewRendererServlet must be added to the web.xml file.
+ This servlet is not invoked directly, but it used by Web Flow to render views in a portlet environment.
+
+
+ ViewRendererServlet
+ org.springframework.web.servlet.ViewRendererServlet
+
+
+
+ ViewRendererServlet
+ /WEB-INF/servlet/view
+
+ ]]>
+
+
+ Portlet Modes and Window States
+
+ Window State
+
+ The Portlet API defined three window states: normal, minimized and maximized.
+ The portlet implementation must decide what to render for each of these window states.
+ Web Flow exposes the string value of the window state under portletWindowState via the request map on the external context.
+
+
+
+
+
+ Portlet Mode
+
+ The Portlet API defined three portlet modes: view, edit and help.
+ The portlet implementation must decide what to render for each of these modes.
+ Web Flow exposes the string value of the portlet mode under portletMode via the request map on the external context.
+
+
+
+
+
+
+ Issues in a Portlet Environment
+
+ Redirects
+
+ The Portlet API only allows redirects to be requested from an action request.
+ Because views are rendered on the render request, views and view-states cannot trigger a redirect.
+
+
+
+ Switching Portlet Modes
+
+ The portlet container passes the execution key from the previous flow when switching to a new mode.
+ Even if the mode is mapped to a different FlowHandler the flow execution will resume the previous execution.
+
+
+ One way to start the new flow is to create a URL targeting the mode without the execution key.
+
+
+
+ Portlets and JSF
+
+ Web Flow supports JSF as the view technology for a portlet.
+ However, a jsf-portlet bridge (JSR-301) must be provided.
+ At the time of this writing, no feature complete jsf-portlet bridge exists.
+ Some of the existing bridge implementations may appear to work, however, strange side effect may occur.
+
+
+ JSF portlets are considered experimental at this time.
+
+
+
+
diff --git a/spring-webflow-reference/src/spring-mvc.xml b/spring-webflow-reference/src/spring-mvc.xml
index 972cb762..6a6c12f7 100644
--- a/spring-webflow-reference/src/spring-mvc.xml
+++ b/spring-webflow-reference/src/spring-mvc.xml
@@ -5,6 +5,108 @@
Introduction
This chapter shows you how to integrate Web Flow into a Spring MVC web application.
+ The booking-mvc sample application is a good reference for Spring MVC with Web Flow.
+ This application is a simplified travel site that allows users to search for and book hotel rooms.
-
\ No newline at end of file
+
+ Configuring web.xml
+
+ The first step to using Spring MVC is to route requests to the DispatcherServlet in the web.xml file.
+ In this example, we map all URLs that begin with /spring/ to the servlet.
+ The servlet needs to be configured.
+ An init-param is used in the servlet to pass the contextConfigLocation.
+ This is the location of the Spring configuration for your application.
+
+
+ Spring MVC Dispatcher Servlet
+ org.springframework.web.servlet.DispatcherServlet
+
+ contextConfigLocation
+ /WEB-INF/web-application-config.xml
+
+ 1
+
+
+
+ Spring MVC Dispatcher Servlet
+ /spring/*
+
+ ]]>
+
+
+ Configuring Spring
+
+ URL Mapping
+
+ Inside the DispatcherServlet request need to be mapped with finer grain.
+ Using a SimpleUrlHandlerMapping request URLs are mapped to controllers and handlers.
+
+
+
+
+ /hotels/booking=bookingFlowHandler
+ /hotels/*=hotelsController
+
+
+
+ ]]>
+
+ For this example both a standard MVC controller and a Web Flow handler are configured.
+ The controller supports the free navigation aspects of searching and viewing hotels.
+ The flow handler supports the controlled navigation aspect of booking a hotel room.
+
+
+
+ Flow Adapters
+
+ The recommended way to bridge Spring MVC requests to Web Flow is via a flow adapter.
+
+
+ ]]>
+
+ The flow adapter provides hooks into the flow execution that can:
+
+
+ select the flow to execute (by default the flow id is inferred from the URL)
+
+
+ pass input parameters to the flow on initialization
+
+
+ handle the flow execution outcome
+
+
+ handle any exceptions
+
+
+ The AbstractFlowHandler class is an implementation of FlowHandler that provides default implementations for these hooks.
+
+
+ A common pattern to handle a flow outcome is to redirect to a new page instead of rendering a view in the end-state.
+ This allows the URL to be refreshed without throwing an exception.
+
+
+
+
+ Flow Controllers
+
+ Flow controllers provide a direct hook from Spring MVC into Web Flow.
+ The FlowController class is an implementation of an MVC Controller.
+
+
+ Web Flow 1.0 used controllers as the only way to hook Web Flow into Spring MVC.
+ In Web Flow 2.0 flow handler adapters are recommended instead of controllers as they provide much richer hooks into the web flow engine.
+
+
+
+
diff --git a/spring-webflow-reference/src/views.xml b/spring-webflow-reference/src/views.xml
index 03dbc0c4..333ec421 100644
--- a/spring-webflow-reference/src/views.xml
+++ b/spring-webflow-reference/src/views.xml
@@ -292,7 +292,7 @@ context.addMessage(builder.warn().source("smoking").defaultText("Smoking is bad
context.addMessage(builder.info().defaultText("We have processed your reservation - thank you and enjoy your stay").build());
-
+
Adding internationalized messages
MessageContext context = ...