org.omnifaces.facesviews

Class Summary
Class	Description
FacesViewsForwardingFilter	This filter forwards request to a FacesServlet using an extension on which this Servlet is mapped.
FacesViewsInitializerListener	Convenience class for Servlet 3.0 users, which will auto-register all artifacts required for auto-mapping and extensionless view to work.
FacesViewsResolver	Facelets resource resolver that resolves mapped resources (views) to the special auto-scanned faces-views folder.
FacesViewsUtils	Collection of utilities for working with auto-scanned- and extensionless views.
FacesViewsViewHandler	View handler that renders action URL extensionless if the current request is extensionless and the requested resource is a mapped one, otherwise as-is.

Package org.omnifaces.facesviews Description

This package contains the classes for the OmniFaces' FacesViews feature.

FacesViews is a feature where a special dedicated directory (/WEB-INF/faces-views) can be used to store Facelets source files. All files found in this directory are automatically mapped as Facelets files and made available using both their original extension as well as without an extension (extensionless).

With FacesViews, there is thus no need to list all Facelets views that should be accessed without an extension in some configuration file. Additionally, it thus automatically maps Facelets files to their original file extension, which prevents exposing the source code of those Facelets that happens with the default JSF mapping.

In Servlet 3.0 containers, scanning is done automatically and no further configuration is needed. The feature is compatible with applications that don't have web.xml or faces-config.xml configuration files. As such, it can be used as an alternative to declaring the FacesServlet in web.xml for the .xhtml to .xhtml mapping.

Example:
Consider the following file structure:

    /WEB-INF/faces-views/index.xhtml
    /WEB-INF/faces-views/users/add.xhtml
    /normal.xhtml

This will make the Facelets available via the following URLs (given a root deployment on domain example.com):

    example.com/index
    example.com/users/add
    example.com/index.xhtml
    example.com/users/add.xhtml
    example.com/normal.xhtml

Note that although the directory outside /WEB-INF/faces-views is not scanned, the FacesServlet is mapped on all extensions found in /WEB-INF/faces-views, so this will also affect files outside this directory. In the above example normal.xhtml is thus also available via the .xhtml extension, since the whole FacesServlet is mapped on this.

JSF links in which logical view ids are used will be rendered as either extensionless or with an extension based on whether the request in which this rendering is done was extensionless or not. E.g. consider the following link on /WEB-INF/faces-views/index.xhtml:

 <h:link value="Add user" outcome="/users/add" />

This will render as /users/add if the request was to /index and as /users/add.xhtml if the request was to /index.xhtml.

Configuration

The following context parameters are available.

"org.omnifaces.FACES_VIEWS_ENABLED" Used to completely switch scanning off. Allowed values: {true,false} Default: true (note that if no /WEB-INF/faces-views directory is present, no scanning will be done either)

Servlet 2.5 configuration

Servlet 2.5 users will have to install the FacesViewsForwardingFilter and FacesViewsViewHandler manually:

web.xml

 <filter>
     <filter-name>FacesViewsForwardingFilter</filter-name>
     <filter-class>org.omnifaces.facesviews.FacesViewsForwardingFilter</filter-class>
 </filter>
 <filter-mapping>
     <filter-name>FacesViewsForwardingFilter</filter-name>
     <url-pattern>/*</url-pattern>
 </filter-mapping>

faces-config.xml

 <application>
     <view-handler>org.omnifaces.facesviews.FacesViewsViewHandler</view-handler>
 </application>

(at the moment Servlet 2.5 compatibility has not been tested)

Author:: Arjan Tijms