12.3. Configuring web.xml
Prev | 12. JSF Integration | Next

## 12.3. Configuring web.xml

The first step to using Spring Faces 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.

    <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>

In order for JSF to bootstrap correctly, the `FacesServlet` must be configured in `web.xml` as it normally would even though you generally will not need to route requests through it at all when using Spring Faces.

    <!-- 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>

When using the Spring Faces components, you also need to configure the Spring JavaScript `ResourceServlet` so that CSS and JavaScript resources may be output correctly by the components. This servlet must be mapped to /resources/* in order for the URL's rendered by the components to function correctly.

    <!-- 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>

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.

    !-- 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>

For optimal page-loading performance, the Spring Faces component library includes a few special components: `includeStyles` and `includeScripts`. These components will eagerly load the neccessary 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 `head` section of any page that uses the Spring Faces components. For example:

    <!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>Spring Faces: Hotel Booking Sample Application</title>

    	<sf:includeStyles />
    	<sf:includeScripts />

    	<ui:insert name="headIncludes"/>
    </head>
    ...
    </html>
    </f:view>

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.

The `includeStyles` 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 `includeStyles` component. For example:

    <sf:includeStyles themePath="/styles/" theme="foobar"/>

will try to load a CSS stylesheet at "/styles/foobar/foobar.css" using the Spring JavaScript ResourceServlet.

Prev | Up | Next
12.2. Spring-centric Integration Approach | Home | 12.4. Configuring Web Flow to render JSF views