<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
	"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="spring-faces">
    <title>JSF Integration</title>
    <sect1 id="spring-faces-introduction">
        <title>Introduction</title>
        <para>
            Spring Web Flow provides an integration that simplifies using JSF with Spring. It lets you use the
            JSF UI Component Model with Spring MVC and Spring Web Flow controllers.
        </para>
        <para>
            A small Facelets component library that provides Ajax and client-side validation capabilities is also shipped with Web Flow. 
        </para>
    </sect1>
    <sect1 id="spring-faces-integration">
        <title>JSF Integration For Spring Developers</title>
        <para>
            Spring Web Flow complements the strengths of JSF, its component model, and provides more sophisticated state management and navigation. 
            In addition you have the ability to use Spring MVC @Controller or flow definitions as controllers in the web layer. 
        </para>
        <para>
            JSF applications using Spring Web Flow applications gain benefits in the following areas:
            <orderedlist>
                <listitem><para>Managed bean facility</para></listitem>
                <listitem><para>Scope management</para></listitem>
                <listitem><para>Event handling</para></listitem>
                <listitem><para>Navigation</para></listitem>
                <listitem><para>Modularization and packaging of views</para></listitem>
                <listitem><para>Cleaner URLs</para></listitem>
                <listitem><para>Model-level validation</para></listitem>
                <listitem><para>Progressivy-enhancement sytle client-side validation</para></listitem>
                <listitem><para>Progressive-enhancement style Ajax requests with partial page updates</para></listitem>
            </orderedlist>

            Using these features significantly reduce the amount of configuration required in faces-config.xml.
            They provide a cleaner separation between the view and controller layers along with better modularization of application functionals. 
            These features are detailed in the sections to follow. 
            The majority of these features build on the flow definition language of Spring Web Flow.
            Therefore it is assumed that you have an understanding of the foundations presented in <xref linkend="defining-flows"/>.
        </para>
    </sect1>
    <sect1 id="spring-faces-config-web.xml">
        <title>Configuring web.xml</title>
        <para>
            The first step is to route requests to the <code>DispatcherServlet</code> in the <code>web.xml</code> file. 
            In this example, we map all URLs that begin with <code>/spring/</code> to the servlet. 
            The servlet needs to be configured. 
            An <code>init-param</code> is used in the servlet to pass the <code>contextConfigLocation</code>. 
            This is the location of the Spring configuration for your web application.
        </para>
        <programlisting language="xml"><![CDATA[
<servlet>
    <servlet-name>Spring MVC Dispatcher Servlet</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>/WEB-INF/web-application-config.xml</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>
    
<servlet-mapping>
    <servlet-name>Spring MVC Dispatcher Servlet</servlet-name>
    <url-pattern>/spring/*</url-pattern>
</servlet-mapping>]]>
        </programlisting>
        <para>
            In order for JSF to bootstrap correctly, the
            <code>FacesServlet</code>
            must be configured in
            <code>web.xml</code>
            as it normally would even though you generally will not need to route requests through it at all when using JSF with Spring Web Flow.
        </para>
        <programlisting language="xml"><![CDATA[
<!-- Just here so the JSF implementation can initialize, *not* used at runtime -->
<servlet>
    <servlet-name>Faces Servlet</servlet-name>
    <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
</servlet>
    
<!-- Just here so the JSF implementation can initialize -->
<servlet-mapping>
    <servlet-name>Faces Servlet</servlet-name>
    <url-pattern>*.faces</url-pattern>
</servlet-mapping>]]>
        </programlisting>
        <para>
            When using the Spring Faces components, you also need to configure a servlet for serving
            CSS and JavaScript resources. This servlet must be mapped
            to /resources/* in order for the URL's rendered by the components to function correctly.
        </para>
        <programlisting language="xml"><![CDATA[
<!-- Serves static resource content from .jar files such as spring-faces.jar -->
<servlet>
    <servlet-name>Resource Servlet</servlet-name>
    <servlet-class>org.springframework.js.resource.ResourceServlet</servlet-class>
    <load-on-startup>0</load-on-startup>
</servlet>
        
<!-- Map all /resources requests to the Resource Servlet for handling -->
<servlet-mapping>
    <servlet-name>Resource Servlet</servlet-name>
    <url-pattern>/resources/*</url-pattern>
</servlet-mapping>]]>
        </programlisting>
        <para>
            The Spring Faces components require the use of Facelets instead of JSP, so the typical Facelets
            configuration must be added as well when using these components.
        </para>
        <programlisting language="xml"><![CDATA[
!-- Use JSF view templates saved as *.xhtml, for use with Facelets -->
<context-param>
    <param-name>javax.faces.DEFAULT_SUFFIX</param-name>
    <param-value>.xhtml</param-value>
</context-param>]]>
        </programlisting>
		<para>
			For optimal page-loading performance use the Spring Faces components
			<code>includeStyles</code> and <code>includeScripts</code>.  These components will eagerly load the necessary
			CSS stylesheets and JavaScript files at the position they are placed in your JSF view template.  In accordance
			with the recommendations of the Yahoo Performance Guildlines, these two tags should be placed in the <code>head</code>
			section of any page that uses the Spring Faces components.  For example:
		</para>
		<programlisting language="xml"><![CDATA[ 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<f:view xmlns="http://www.w3.org/1999/xhtml"
      xmlns:ui="http://java.sun.com/jsf/facelets"
      xmlns:f="http://java.sun.com/jsf/core"
	  xmlns:c="http://java.sun.com/jstl/core"
	  xmlns:sf="http://www.springframework.org/tags/faces"
	  contentType="text/html" encoding="UTF-8">
<html>
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<title>Hotel Booking Sample Application</title>
	
	<sf:includeStyles />
	<sf:includeScripts />
	
	<ui:insert name="headIncludes"/>
</head>
...
</html>
</f:view>]]>
	</programlisting>
	<para>
		This shows the opening of a typical Facelets XHTML layout template that uses these components to force the loading of
		the needed CSS and JavaScript resources at the ideal position.
	</para>
	<para>
		The <code>includeStyles</code> component includes the necessary resources for the Dojo widget theme.  By default, it includes
		the resources for the "tundra" theme.  An alternate theme may be selected by setting the optional "theme" and "themePath" attributes
		on the <code>includeStyles</code> component.  For example:
	</para>
	<programlisting language="xml"><![CDATA[ 
<sf:includeStyles themePath="/styles/" theme="foobar"/>
]]>
</programlisting>
	<para>
		will try to load a CSS stylesheet at "/styles/foobar/foobar.css" using the Spring JavaScript ResourceServlet.
	</para>
    </sect1>
    <sect1 id="spring-faces-webflow-config">
        <title>Configuring Web Flow to render JSF views</title>
        <para>
            The next step is to configure Web Flow to render JSF views. To do this, in your Spring Web Flow
            configuration include the
            <code>faces</code>
            namespace and link in the 
            <code>flow-builder-services</code> element from the faces custom namespace.
            :
        </para>
        <programlisting language="xml"><![CDATA[
<?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:webflow="http://www.springframework.org/schema/webflow-config"
       xmlns:faces="http://www.springframework.org/schema/faces"
       xsi:schemaLocation="
           http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
           http://www.springframework.org/schema/webflow-config
           http://www.springframework.org/schema/webflow-config/spring-webflow-config-2.0.xsd
           http://www.springframework.org/schema/faces
           http://www.springframework.org/schema/faces/spring-faces-2.0.xsd">

	<!-- Executes flows: the central entry point into the Spring Web Flow system -->
	<webflow:flow-executor id="flowExecutor" />

	<!-- The registry of executable flow definitions -->
	<webflow:flow-registry id="flowRegistry" flow-builder-services="facesFlowBuilderServices" base-path="/WEB-INF">
		<webflow:flow-location-pattern value="**/*-flow.xml" />
	</webflow:flow-registry>

	<!-- Configures the Spring Web Flow JSF integration -->
	<faces:flow-builder-services id="facesFlowBuilderServices" />

</beans>]]>
        </programlisting>
        <para>
        	The <code>faces:flow-builder-services</code> tag also configures several other defaults appropriate for a JSF environment.
        </para>
        <para>
            See the swf-booking-faces reference application in the distribution for a complete working example.
       	</para>
    </sect1>
    <sect1 id="spring-faces-config">
        <title>Configuring faces-config.xml</title>
        <para>
            If using JSF 1.2 you need to provide the below configuration in 
            <code>faces-config.xml</code>
            in order to use Facelets. If you are using JSP and not using the Spring Faces components, you do
            not need to add anything to your <code>faces-config.xml</code>
        </para>
        <programlisting language="xml"><![CDATA[
<faces-config>
    <application>
        <!-- Enables Facelets -->
        <view-handler>com.sun.facelets.FaceletViewHandler</view-handler>  
    </application>
</faces-config>]]>
        </programlisting>
        <para>
            If using JSF 2.0 then your faces-config.xml should use the faces-config schema version 2.0.
            Also you should remove the FaceletViewHandler shown above if it is present as Facelets are now the default rendering technology in JSF 2.
        </para>
        <programlisting language="xml"><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<faces-config xmlns="http://java.sun.com/xml/ns/javaee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_2_0.xsd"
        version="2.0">

    <application></application>
    
</faces-config>]]>
        </programlisting>
    </sect1>
    <sect1 id="spring-faces-managed-beans">
        <title>Replacing the JSF Managed Bean Facility</title>
        <para>
            When JSF with Spring Web Flow you can completely replace the JSF managed bean facility with a combination of
            Web Flow managed variables and Spring managed beans. It gives you a good deal more control over the lifecycle of
            your managed objects with well-defined hooks for initialization and execution of your domain model.
            Additionally, since you are presumably already using Spring for your business layer, it reduces the
            conceptual overhead of having to maintain two different managed bean models.
        </para>
        <para>
            In doing pure JSF development, you will quickly find that request scope is not long-lived enough for storing
            conversational model objects that drive complex event-driven views. In JSF 1.2 the only available option is to begin
            putting things into session scope, with the extra burden of needing to clean the objects up before
            progressing to another view or functional area of the application. What is really needed is a managed scope
            that is somewhere between request and session scope. 
        </para>
        <para>
      		JSF 2 provides flash and view scopes that can be accessed programmatically via UIViewRoot.getViewMap().      
            Spring Web Flow provides access to flash, view, flow, and conversation scopes.
            These scopes are seamlessly integrated through JSF variable resolvers and work the same in JSF 1.2 and in JSF 2.0 applications.
        </para>
        <sect2 id="spring-faces-flow-variables">
            <title>Using Flow Variables</title>
            <para>
                The easiest and most natural way to declare and manage the model is through the use of
                <link linkend="flow-variables">flow variables</link>. 
                You can declare these variables at the beginning of the flow:
            </para>
            <programlisting language="xml"><![CDATA[
<var name="searchCriteria" class="com.mycompany.myapp.hotels.search.SearchCriteria"/>]]>
            </programlisting>
            <para>and then reference this variable in one of the flow's JSF view templates through EL:</para>
            <programlisting language="xml"><![CDATA[
<h:inputText id="searchString" value="#{searchCriteria.searchString}"/>]]>
            </programlisting>
            <para>
                Note that you do not need to prefix the variable with its scope when referencing it from the template
                (though you can do so if you need to be more specific). As with standard JSF beans, all available scopes
                will be searched for a matching variable, so you could change the scope of the variable in your flow
                definition without having to modify the EL expressions that reference it.
            </para>
            <para>
                You can also define view instance variables that are scoped to the current view and get cleaned up
                automatically upon transitioning to another view. This is quite useful with JSF as views are often
                constructed to handle multiple in-page events across many requests before transitioning to another view.
            </para>
            <para>
                To define a view instance variable, you can use the
                <code>var</code>
                element inside a
                <code>view-state</code>
                definition:
            </para>
            <programlisting language="xml"><![CDATA[
<view-state id="enterSearchCriteria"> 
    <var name="searchCriteria" class="com.mycompany.myapp.hotels.search.SearchCriteria"/> 
</view-state>]]>
            </programlisting>
        </sect2>
        <sect2 id="spring-faces-spring-beans">
            <title>Using Scoped Spring Beans</title>
            <para>
                Though defining autowired flow instance variables provides nice modularization and readability,
                occasions may arise where you want to utilize the other capabilities of the Spring container such as
                AOP. In these cases, you can define a bean in your Spring ApplicationContext and give it a specific web
                flow scope:
            </para>
            <programlisting language="xml"><![CDATA[
<bean id="searchCriteria" class="com.mycompany.myapp.hotels.search.SearchCriteria" scope="flow"/>]]>
            </programlisting>
            <para>
                The major difference with this approach is that the bean will not be fully initialized until it is first
                accessed via an EL expression. This sort of lazy instantiation via EL is quite similar to how JSF
                managed beans are typically allocated.
            </para>
        </sect2>
        <sect2 id="faces-manipulating-model">
            <title>Manipulating The Model</title>
            <para>
                The need to initialize the model before view rendering (such as by loading persistent entities from a
                database) is quite common, but JSF by itself does not provide any convenient hooks for such
                initialization. The flow definition language provides a natural facility for this through its
                <link linkend="flow-actions">Actions</link>
                . Spring Web Flow provides some extra conveniences for converting the outcome of an action into a
                JSF-specific data structure. For example:
            </para>
            <programlisting language="xml"><![CDATA[ 
<on-render>
    <evaluate expression="bookingService.findBookings(currentUser.name)" 
              result="viewScope.bookings" result-type="dataModel" />
</on-render>]]>
            </programlisting>
            <para>
                This will take the result of the
                <code>bookingService.findBookings</code>
                method an wrap it in a custom JSF DataModel so that the list can be used in a standard JSF DataTable
                component:
            </para>
            <programlisting language="xml"><![CDATA[ 
<h:dataTable id="bookings" styleClass="summary" value="#{bookings}" var="booking" 
             rendered="#{bookings.rowCount > 0}">
    <h:column>
        <f:facet name="header">Name</f:facet>
        #{booking.hotel.name}
    </h:column>                   
    <h:column>
    <f:facet name="header">Confirmation number</f:facet>
        #{booking.id}
        </h:column>
    <h:column>
        <f:facet name="header">Action</f:facet>
        <h:commandLink id="cancel" value="Cancel" action="cancelBooking" />
    </h:column>
</h:dataTable>]]>
            </programlisting>
            <para>
                The custom DataModel provides some extra conveniences such as being serializable for storage beyond
                request scope and access to the currently selected row in EL expressions. For example, on postback from
                a view where the action event was fired by a component within a DataTable, you can take action on the
                selected row's model instance:
            </para>
            <programlisting language="xml"><![CDATA[
<transition on="cancelBooking">
    <evaluate expression="bookingService.cancelBooking(bookings.selectedRow)" />            
</transition>]]>
            </programlisting>
        </sect2>
    </sect1>
    <sect1 id="spring-faces-event-handling">
        <title>Handling JSF Events With Spring Web Flow</title>
        <para>
            Spring Web Flow allows you to handle JSF action events in a decoupled way, requiring no direct dependencies
            in your Java code on JSF API's. In fact, these events can often be handled completely in the flow definiton
            language without requiring any custom Java action code at all. This allows for a more agile development
            process since the artifacts being manipulated in wiring up events (JSF view templates and SWF flow
            definitions) are instantly refreshable without requiring a build and re-deploy of the whole application.
        </para>
        <sect2 id="spring-faces-in-page-events">
            <title>Handling JSF In-page Action Events</title>
            <para>
                A simple but common case in JSF is the need to signal an event that causes manipulation of the model in
                some way and then redisplays the same view to reflect the changed state of the model. The flow
                definition language has special support for this in the
                <code>transition</code>
                element.
            </para>
            <para>
                A good example of this is a table of paged list results. Suppose you want to be able to load and display
                only a portion of a large result list, and allow the user to page through the results. The initial
                <code>view-state</code>
                definition to load and display the list would be:
            </para>
            <programlisting language="xml"><![CDATA[ 
<view-state id="reviewHotels">
    <on-render>
        <evaluate expression="bookingService.findHotels(searchCriteria)" 
                  result="viewScope.hotels" result-type="dataModel" />
    </on-render>
</view-state>]]>
            </programlisting>
            <para>
                You construct a JSF DataTable that displays the current
                <code>hotels</code>
                list, and then place a "More Results" link below the table:
            </para>
            <programlisting language="xml"><![CDATA[ 
<h:commandLink id="nextPageLink" value="More Results" action="next"/>]]>
            </programlisting>
            <para>
                This commandLink signals a "next" event from its action attribute. You can then handle the event by
                adding to the
                <code>view-state</code>
                definition:
            </para>
            <programlisting language="xml"><![CDATA[ 
<view-state id="reviewHotels">
    <on-render>
        <evaluate expression="bookingService.findHotels(searchCriteria)" 
            result="viewScope.hotels" result-type="dataModel" />
    </on-render>
    <transition on="next">
        <evaluate expression="searchCriteria.nextPage()" />
    </transition>
</view-state>]]>
            </programlisting>
            <para>
                Here you handle the "next" event by incrementing the page count on the searchCriteria instance. The
                <code>on-render</code>
                action is then called again with the updated criteria, which causes the next page of results to be
                loaded into the DataModel. The same view is re-rendered since there was no
                <code>to</code>
                attribute on the
                <code>transition</code>
                element, and the changes in the model are reflected in the view.
            </para>
        </sect2>
        <sect2 id="spring-faces-action-events">
            <title>Handling JSF Action Events</title>
            <para>
                The next logical level beyond in-page events are events that require navigation to another view, with
                some manipulation of the model along the way. Achieving this with pure JSF would require adding a
                navigation rule to faces-config.xml and likely some intermediary Java code in a JSF managed bean (both
                tasks requiring a re-deploy). With the flow defintion language, you can handle such a case concisely in
                one place in a quite similar way to how in-page events are handled.
            </para>
            <para>
                Continuing on with our use case of manipulating a paged list of results, suppose we want each row in the
                displayed DataTable to contain a link to a detail page for that row instance. You can add a column to
                the table containing the following
                <code>commandLink</code>
                component:
            </para>
            <programlisting language="xml"><![CDATA[
<h:commandLink id="viewHotelLink" value="View Hotel" action="select"/>]]>
            </programlisting>
            <para>
                This raises the "select" event which you can then handle by adding another
                <code>transition</code>
                element to the existing
                <code>view-state</code>
                :
            </para>
            <programlisting language="xml"><![CDATA[ 
<view-state id="reviewHotels">
    <on-render>
        <evaluate expression="bookingService.findHotels(searchCriteria)" 
            result="viewScope.hotels" result-type="dataModel" />
    </on-render>
    <transition on="next">
        <evaluate expression="searchCriteria.nextPage()" />
    </transition>
    <transition on="select" to="reviewHotel">
            <set name="flowScope.hotel" value="hotels.selectedRow" />
    </transition>
</view-state>]]>
            </programlisting>
            <para>
                Here the "select" event is handled by pushing the currently selected hotel instance from the DataTable
                into flow scope, so that it may be referenced by the "reviewHotel"
                <code>view-state</code>
                .
            </para>
        </sect2>
        <sect2 id="spring-faces-model-validation">
            <title>Performing Model Validation</title>
            <para>
                JSF 1.2 provides useful facilities for validating input at field-level before changes are applied to the
                model, but when you need to then perform more complex validation at the model-level after the updates
                have been applied, you are generally left with having to add more custom code to your JSF action methods
                in the managed bean. Validation of this sort is something that is generally a responsibility of the
                domain model itself, but it is difficult to get any error messages propagated back to the view without
                introducing an undesirable dependency on the JSF API in your domain layer.
            </para>
            <para>
                With Web Flow, you can utilize the generic and low-level
                <code>MessageContext</code>
                in your business code and any messages added there will then be available to the
                <code>FacesContext</code>
                at render time.
            </para>
            <para>
                For example, suppose you have a view where the user enters the necessary details to complete a hotel
                booking, and you need to ensure the Check In and Check Out dates adhere to a given set of business
                rules. You can invoke such model-level validation from a
                <code>transition</code>
                element:
            </para>
            <programlisting language="xml"><![CDATA[ 
<view-state id="enterBookingDetails">
    <transition on="proceed" to="reviewBooking">
        <evaluate expression="booking.validateEnterBookingDetails(messageContext)" />
    </transition>
</view-state>]]>
            </programlisting>
            <para>
                Here the "proceed" event is handled by invoking a model-level validation method on the booking instance,
                passing the generic
                <code>MessageContext</code>
                instance so that messages may be recorded. The messages can then be displayed along with any other JSF
                messages with the
                <code>h:messages</code>
                component,
            </para>
        </sect2>
        <sect2 id="spring-faces-ajax-events">
            <title>Handling Ajax Events</title>
            <para>
                The Spring Faces 
                <code>UICommand</code> 
                components have the ability to do Ajax-based partial
                view updates. These components degrade gracefully so that the flow will still be fully functional by
                falling back to full page refreshes if a user with a less capable browser views the page.
            </para>
            <para>
                Revisiting the earlier example with the paged table, you can change the "More Results" link to use an
                Ajax request by replacing the standard
                <code>commandButton</code>
                with the Spring Faces component version (note that the Spring Faces command components use Ajax by default, but
                they can alternately be forced to use a normal form submit by setting ajaxEnabled="false" on the
                component):
            </para>
            <programlisting language="xml"><![CDATA[            
<sf:commandLink id="nextPageLink" value="More Results" action="next" />]]>
            </programlisting>
            <para>
                This event is handled just as in the non-Ajax case with the
                <code>transition</code>
                element, but now you will add a special
                <code>render</code>
                action that specifies which portions of the component tree need to be re-rendered:
            </para>
            <programlisting language="xml"><![CDATA[
<view-state id="reviewHotels">
    <on-render>
        <evaluate expression="bookingService.findHotels(searchCriteria)" 
                  result="viewScope.hotels" result-type="dataModel" />
    </on-render>
    <transition on="next">
        <evaluate expression="searchCriteria.nextPage()" />
        <render fragments="hotels:searchResultsFragment" />
    </transition>
</view-state>]]>
            </programlisting>
            <para>
                The
                <code>fragments="hotels:searchResultsFragment"</code>
                is an instruction that will be interpreted at render time, such that only the component with the JSF
                clientId "hotels:searchResultsFragment" will be rendered and returned to the client. This fragment will
                then be automatically replaced in the page. The
                <code>fragments</code>
                attribute can be a comma-delimited list of ids, with each id representing the root node of a subtree
                (meaning the root node and all of its children) to be rendered. If the "next" event is fired in a
                non-Ajax request (i.e., if JavaScript is disabled on the client), the
                <code>render</code>
                action will be ignored and the full page will be rendered as normal.
            </para>
            <para>
                In addition to the Spring Faces
                <code>commandLink</code>
                component, there is a corresponding
                <code>commandButton</code>
                component with the same functionality. There is also a special
                <code>ajaxEvent</code>
                component that will raise a JSF action even in response to any client-side DOM event. See the Spring
                Faces tag library docs for full details.
            </para>
            <para>
                An additional built-in feature when using the Spring Faces Ajax-enabled components is the ability to have the
                response rendered inside a rich modal popup widget by setting
                <code>popup="true"</code>
                on a
                <code>view-state</code>
                .
            </para>
            <programlisting language="xml"><![CDATA[
<view-state id="changeSearchCriteria" view="enterSearchCriteria.xhtml" popup="true">
    <on-entry>
        <render fragments="hotelSearchFragment" />
    </on-entry>
    <transition on="search" to="reviewHotels">
        <evaluate expression="searchCriteria.resetPage()"/>
    </transition>
</view-state>]]>
            </programlisting>
            <para>
                If the "changeSearchCriteria"
                <code>view-state</code>
                is reached as the result of an Ajax-request, the result will be rendered into a rich popup. If
                JavaScript is unavailable, the request will be processed with a full browser refresh, and the
                "changeSearchCriteria" view will be rendered as normal.
            </para>
        </sect2>
    </sect1>
    <sect1 id="spring-faces-ui-controls">
        <title>Enhancing The User Experience With Rich Web Forms</title>
        <para>
            JSF and Web Flow combine to provide an extensive server-side validation model for your web application, but
            excessive roundtrips to the server to execute this validation and return error messages can be a tedious
            experience for your users. The Spring Faces component library provides a number of client-side rich validation controls that can
            enhance the user experience by applying simple validations that give immediate feedback. Some simple
            examples are illustrated below. See the Spring Faces taglib docs for a complete tag reference.
        </para>
        <sect2 id="spring-faces-text-validation">
            <title>Validating a Text Field</title>
            <para>
                Simple client-side text validation can be applied with the
                <code>clientTextValidator</code>
                component:
            </para>
            <programlisting language="xml"><![CDATA[ 
<sf:clientTextValidator required="true">
    <h:inputText id="creditCardName" value="#{booking.creditCardName}" required="true"/>
</sf:clientTextValidator>]]>
            </programlisting>
            <para>
                This will apply client-side required validation to the child
                <code>inputText</code>
                component, giving the user a clear indicator if the field is left blank.
            </para>
        </sect2>
        <sect2 id="spring-faces-number-validation">
            <title>Validating a Numeric Field</title>
            <para>
                Simple client-side numeric validation can be applied with the
                <code>clientNumberValidator</code>
                component:
            </para>
            <programlisting language="xml"><![CDATA[ 
<sf:clientTextValidator required="true" regExp="[0-9]{16}" 
                        invalidMessage="A 16-digit credit card number is required.">
    <h:inputText id="creditCard" value="#{booking.creditCard}" required="true"/>
</sf:clientTextValidator>]]>
            </programlisting>
            <para>
                This will apply client-side validation to the child
                <code>inputText</code>
                component, giving the user a clear indicator if the field is left blank, is not numeric, or does not
                match the given regular expression.
            </para>
        </sect2>
        <sect2 id="spring-faces-date-validation">
            <title>Validating a Date Field</title>
            <para>
                Simple client-side date validation with a rich calendar popup can be applied with the
                <code>clientDateValidator</code>
                component:
            </para>
            <programlisting language="xml"><![CDATA[ 
<sf:clientDateValidator required="true" >
    <h:inputText id="checkinDate" value="#{booking.checkinDate}" required="true">
        <f:convertDateTime pattern="yyyy-MM-dd" timeZone="EST"/>
    </h:inputText>
</sf:clientDateValidator>]]>
            </programlisting>
            <para>
                This will apply client-side validation to the child
                <code>inputText</code>
                component, giving the user a clear indicator if the field is left blank or is not a valid date.
            </para>
        </sect2>
        <sect2 id="spring-faces-validate-all">
            <title>Preventing an Invalid Form Submission</title>
            <para>
                The
                <code>validateAllOnClick</code>
                component can be used to intercept the "onclick" event of a child component and suppress the event if
                all client-side validations do not pass.
            </para>
            <programlisting language="xml"><![CDATA[ 
<sf:validateAllOnClick>
    <sf:commandButton id="proceed" action="proceed" processIds="*" value="Proceed"/>&#160;
</sf:validateAllOnClick>]]>
            </programlisting>
            <para>
                This will prevent the form from being submitted when the user clicks the "proceed" button if the form is
                invalid. When the validations are executed, the user is given clear and immediate indicators of the
                problems that need to be corrected.
            </para>
        </sect2>
    </sect1>
    <sect1 id="spring-faces-component-libraries">
        <title>Third-Party Component Library Integration</title>
        <para>
            The Spring Web Flow JSF integration strives to be compatible with any third-party JSF component library. By honoring all of the
            standard semantics of the JSF specification within the SWF-driven JSF lifecycle, third-party libraries in
            general should "just work". The main thing to remember is that configuration in web.xml will change slightly
            since Web Flow requests are not routed through the standard FacesServlet. Typically, anything that is
            traditionally mapped to the FacesServlet should be mapped to the Spring DispatcherServlet instead. (You can
            also map to both if for example you are migrating a legacy JSF application page-by-page.) In some cases, a
            deeper level of integration can be achieved by configuring special flow services that are "aware" of a
            particular component library, and these will be noted in the examples to follow.
        </para>
        <sect2 id="spring-faces-with-richfaces">
            <title>Rich Faces Integration</title>
            <para>
                To use the Rich Faces component library with Spring Web Flow, the following filter configuration is needed
                in web.xml (in addition to the other typical configuration already shown):
            </para>
            <programlisting language="xml"><![CDATA[ 
<filter> 
    <display-name>RichFaces Filter</display-name> 
    <filter-name>richfaces</filter-name> 
    <filter-class>org.ajax4jsf.Filter</filter-class> 
</filter> 

<filter-mapping> 
    <filter-name>richfaces</filter-name> 
    <servlet-name>Spring Web MVC Dispatcher Servlet</servlet-name>
    <dispatcher>REQUEST</dispatcher>
    <dispatcher>FORWARD</dispatcher>
    <dispatcher>INCLUDE</dispatcher>
</filter-mapping>]]>
            </programlisting>
            <para>
                For deeper integration (including the ability to have a view with combined use of the Spring Faces Ajax
                components and Rich Faces Ajax components), configure the RichFacesAjaxHandler on your FlowController:
            </para>
            <programlisting language="xml"><![CDATA[ 
<bean id="flowController" class="org.springframework.webflow.mvc.servlet.FlowController">
    <property name="flowExecutor" ref="flowExecutor" />
    <property name="ajaxHandler">
        <bean class="org.springframework.faces.richfaces.RichFacesAjaxHandler"/>
    </property>
</bean>]]>
            </programlisting>
            <para>
                RichFaces Ajax components can be used in conjunction with the
                <code>render</code>
                tag to render partial fragments on an Ajax request. Instead of embedding the ids of the components to be
                re-rendered directly in the view template (as you traditionally do with Rich Faces), you can bind the
                <code>reRender</code>
                attribute of a RichFaces Ajax component to a special
                <code>flowRenderFragments</code>
                EL variable. For example, in your view template you can have a fragment that you would potentially like
                to re-render in response to a particular event:
            </para>
            <programlisting language="xml"><![CDATA[
<h:form id="hotels">
    <a4j:outputPanel id="searchResultsFragment">
        <h:outputText id="noHotelsText" value="No Hotels Found" rendered="#{hotels.rowCount == 0}"/>
        <h:dataTable id="hotels" styleClass="summary" value="#{hotels}" var="hotel" rendered="#{hotels.rowCount > 0}">
            <h:column>
                <f:facet name="header">Name</f:facet>
                #{hotel.name}
            </h:column>
            <h:column>
                <f:facet name="header">Address</f:facet>
                #{hotel.address}
            </h:column>
        </h:dataTable>
    </a4j:outputPanel>
</h:form>]]>
            </programlisting>
            <para>
                then a RichFaces Ajax
                <code>commandLink</code>
                to fire the event:
            </para>
            <programlisting language="xml"><![CDATA[
<a4j:commandLink id="nextPageLink" value="More Results" action="next" reRender="#{flowRenderFragments}" />]]>
            </programlisting>
            <para>
                and then in your flow definition a
                <code>transition</code>
                to handle the event:
            </para>
            <programlisting language="xml"><![CDATA[
<transition on="next">
    <evaluate expression="searchCriteria.nextPage()" />
    <render fragments="hotels:searchResultsFragment" />
</transition>]]>
            </programlisting>
        </sect2>
        <sect2 id="spring-faces-with-trinidad">
            <title>Apache MyFaces Trinidad Integration</title>
            <para>
                The Apache MyFaces Trinidad library has been tested with the Spring Web Flow's JSF integration and proven to fit
                in nicely. Deeper integration to allow the Trinidad components and Spring Faces components to play
                well together has not yet been attempted, but Trinidad provides a pretty thorough solution on its own
                when used in conjunction with the Spring Web Flow JSF integration.
            </para>
            <para>
            	NOTE: An <code>AjaxHandler</code> implementation for Trinidad is not currently provided out-of-the-box. 
            	In order to fully integrate with Trinidad's PPR functionality, a custom implementation should be 
            	provided.  An community-provided partial example can be found here: <ulink url="http://jira.springsource.org/browse/SWF-1160">SWF-1160</ulink>
            </para>
            <para>
                Typical configuration when using Trinidad with Web Flow is as follows in web.xml (in addition what has already been shown):
            </para>
            <programlisting language="xml"><![CDATA[
<context-param>
    <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
    <param-value>server</param-value>
</context-param>

<context-param>
    <param-name>
        org.apache.myfaces.trinidad.CHANGE_PERSISTENCE
    </param-name>
    <param-value>session</param-value>
</context-param>

<context-param>
    <param-name>
        org.apache.myfaces.trinidad.ENABLE_QUIRKS_MODE
    </param-name>
    <param-value>false</param-value>
</context-param>

<filter>
    <filter-name>Trinidad Filter</filter-name>
    <filter-class>
        org.apache.myfaces.trinidad.webapp.TrinidadFilter
    </filter-class>
</filter>

<filter-mapping>
    <filter-name>Trinidad Filter</filter-name>
    <servlet-name>Spring MVC Dispatcher Servlet</servlet-name>
</filter-mapping>

<servlet>
    <servlet-name>Trinidad Resource Servlet</servlet-name>
    <servlet-class>
        org.apache.myfaces.trinidad.webapp.ResourceServlet
    </servlet-class>
</servlet>

<servlet-mapping>
    <servlet-name>resources</servlet-name>
    <url-pattern>/adf/*</url-pattern>
</servlet-mapping>
]]>
            </programlisting>
        </sect2>
    </sect1>
</chapter>