FacesViews (OmniFaces 2.5 API)

java.lang.Object
- org.omnifaces.facesviews.FacesViews

```
public final class FacesViews
extends Object
```
FacesViews is a mechanism to use SEO-friendly extensionless URLs in a JSF application without the need to enlist individual Facelet source files in some configuration file.
By default, all URLs generated by ViewHandler.getActionURL(FacesContext, String), which is used by among others <h:form>, <h:link>, <h:button> and all extended tags, will also be extensionless. And, URLs with an extension will be 301-redirected to the extensionless one.
Usage

Zero configuration

Put Facelets source files into /WEB-INF/faces-views directory. All Facelets files in this special directory will be automatically scanned as extensionless URLs.
Minimal configuration

Below is the minimal web.xml configuration to make all Facelets source files found in the root folder and all subdirectories of the public web content (excluding /WEB-INF, /META-INF and /resources) available as extensionless URLs:
```
 <context-param>
     <param-name>org.omnifaces.FACES_VIEWS_SCAN_PATHS</param-name>
     <param-value>/*.xhtml</param-value>
 </context-param>
 
```
The path pattern /*.xhtml basically means that all files with the .xhtml extension from the directory / must be scanned, including all sub directories. In case you want to scan only .xhtml files in the directory /foo, then use path pattern of /foo/*.xhtml instead. In case you want to scan all files in the directory /foo, then use path pattern of /foo. You can specify multiple values separated by a comma.
MultiViews configuration

Enabling MultiViews is a matter of suffixing the path pattern with /*. The support was added in OmniFaces 2.5. Below is the web.xml configuration which extends the above minimal configuration with MultiViews support:
```
 <context-param>
     <param-name>org.omnifaces.FACES_VIEWS_SCAN_PATHS</param-name>
     <param-value>/*.xhtml/*</param-value>
 </context-param>
 
```
On an example URL of http://example.com/context/foo/bar/baz when neither /foo/bar/baz.xhtml nor /foo/bar.xhtml exist, but /foo.xhtml does exist, then the request will forward to /foo.xhtml and make the values bar and baz available as injectable path parameters via @Param in the managed bean associated with /foo.xhtml.
```
 @Inject @Param(pathIndex=0)
 private String bar;

 @Inject @Param(pathIndex=1)
 private String baz;
 
```
Advanced configuration

See package documentation for configuration settings as to mapping, filtering and forwarding behavior.
PrettyFaces

Note that there is some overlap between this feature and PrettyFaces. The difference is that FacesViews has a focus on zero- or very minimal config, where PrettyFaces has a focus on very powerful mapping mechanisms, which of course need some level of configuration. As such FacesViews will only focus on auto discovering views and mapping them to both .xhtml and to no-extension without needing to explicitly declare the FacesServlet in web.xml.
Specifically, FacesViews will thus not become a general URL rewriting tool (e.g. one that maps path segments to parameters, or that totally changes the name of the URL). For this the user is advised to look at the aforementioned PrettyFaces.
Author:

Arjan Tijms

See Also:

FacesViewsResolver, FacesViewsForwardingFilter, ExtensionAction, PathAction, FacesServletDispatchMethod, UriExtensionRequestWrapper, FacesViewsViewHandlerInstaller, FacesViewsViewHandler, ViewHandlerMode

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`FACES_VIEWS_DISPATCH_METHOD_PARAM_NAME` The name of the enum context parameter that determines the method used by FacesViews to invoke the FacesServlet.
`static String`	`FACES_VIEWS_ENABLED_PARAM_NAME` The name of the boolean context parameter to switch auto-scanning completely off for Servlet 3.0 containers.
`static String`	`FACES_VIEWS_EXTENSION_ACTION_PARAM_NAME` The name of the enum context parameter that determines the action that is performed whenever a resource is requested WITH extension that's also available without an extension.
`static String`	`FACES_VIEWS_FILTER_AFTER_DECLARED_FILTERS_PARAM_NAME` The name of the boolean context parameter via which the user can set whether the `FacesViewsForwardingFilter` should match before declared filters (false) or after declared filters (true).
`static String`	`FACES_VIEWS_ORIGINAL_PATH_INFO` The name of the request attribute under which the original request path info is stored.
`static String`	`FACES_VIEWS_ORIGINAL_SERVLET_PATH` The name of the request attribute under which the original request servlet path is stored.
`static String`	`FACES_VIEWS_PATH_ACTION_PARAM_NAME` The name of the enum context parameter that determines the action that is performed whenever a resource is requested in a public path that has been used for scanning views by faces views.
`static String`	`FACES_VIEWS_SCAN_PATHS_PARAM_NAME` The name of the commaseparated context parameter where the value holds a comma separated list of paths that are to be scanned by faces views.
`static String`	`FACES_VIEWS_SCANNED_VIEWS_EXTENSIONLESS_PARAM_NAME` The name of the boolean context parameter via which the user can set scanned views to be always rendered extensionless.
`static String`	`FACES_VIEWS_VIEW_HANDLER_MODE_PARAM_NAME` The name of the enum context parameter via which the user can set whether the `FacesViewsViewHandler` should strip the extension from the parent view handler's outcome or construct the URL itself and only take the query parameters (if any) from the parent.
`static String`	`WEB_INF_VIEWS` A special dedicated "well-known" directory where facelets implementing views can be placed.

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static void`	`addFacesServletMappings(ServletContext servletContext)` This will map the `FacesServlet` to extensions found during scanning in `ApplicationInitializer`.
`static boolean`	`isFacesViewsEnabled(ServletContext servletContext)` Returns whether FacesViews feature is enabled.
`static boolean`	`isMultiViewsEnabled(ServletContext servletContext)` Returns whether MultiViews feature is enabled.
`static void`	`registerForwardingFilter(ServletContext servletContext)` This will register the `FacesViewsForwardingFilter`.
`static void`	`registerViewHander(ServletContext servletContext)` Register a view handler that transforms a view id with extension back to an extensionless one.
`static String`	`stripFacesViewsPrefix(String resource)` Strips any special '/WEB-INF/faces-views' prefix path from the given resource.
`static String`	`stripWelcomeFilePrefix(ServletContext servletContext, String resource)` Strips any mapped welcome file prefix path from the given resource.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - WEB_INF_VIEWS
```
public static final String WEB_INF_VIEWS
```
    A special dedicated "well-known" directory where facelets implementing views can be placed. This directory is scanned by convention so that no explicit configuration is needed.
    
    See Also:
    
    Constant Field Values
  - FACES_VIEWS_ENABLED_PARAM_NAME
```
public static final String FACES_VIEWS_ENABLED_PARAM_NAME
```
    The name of the boolean context parameter to switch auto-scanning completely off for Servlet 3.0 containers.
    
    See Also:
    
    Constant Field Values
  - FACES_VIEWS_SCAN_PATHS_PARAM_NAME
```
public static final String FACES_VIEWS_SCAN_PATHS_PARAM_NAME
```
    The name of the commaseparated context parameter where the value holds a comma separated list of paths that are to be scanned by faces views.
    
    See Also:
    
    Constant Field Values
  - FACES_VIEWS_SCANNED_VIEWS_EXTENSIONLESS_PARAM_NAME
```
public static final String FACES_VIEWS_SCANNED_VIEWS_EXTENSIONLESS_PARAM_NAME
```
    The name of the boolean context parameter via which the user can set scanned views to be always rendered extensionless. Without this setting (or it being set to false), it depends on whether the request URI uses an extension or not. If it doesn't, links are also rendered without one, otherwise are rendered with an extension.
    
    See Also:
    
    Constant Field Values
  - FACES_VIEWS_EXTENSION_ACTION_PARAM_NAME
```
public static final String FACES_VIEWS_EXTENSION_ACTION_PARAM_NAME
```
    The name of the enum context parameter that determines the action that is performed whenever a resource is requested WITH extension that's also available without an extension. See ExtensionAction
    
    See Also:
    
    ExtensionAction, Constant Field Values
  - FACES_VIEWS_PATH_ACTION_PARAM_NAME
```
public static final String FACES_VIEWS_PATH_ACTION_PARAM_NAME
```
    The name of the enum context parameter that determines the action that is performed whenever a resource is requested in a public path that has been used for scanning views by faces views. See PathAction
    
    See Also:
    
    PathAction, Constant Field Values
  - FACES_VIEWS_DISPATCH_METHOD_PARAM_NAME
```
public static final String FACES_VIEWS_DISPATCH_METHOD_PARAM_NAME
```
    The name of the enum context parameter that determines the method used by FacesViews to invoke the FacesServlet. See FacesServletDispatchMethod.
    
    See Also:
    
    FacesServletDispatchMethod, Constant Field Values
  - FACES_VIEWS_FILTER_AFTER_DECLARED_FILTERS_PARAM_NAME
```
public static final String FACES_VIEWS_FILTER_AFTER_DECLARED_FILTERS_PARAM_NAME
```
    The name of the boolean context parameter via which the user can set whether the FacesViewsForwardingFilter should match before declared filters (false) or after declared filters (true).
    
    See Also:
    
    Constant Field Values
  - FACES_VIEWS_VIEW_HANDLER_MODE_PARAM_NAME
```
public static final String FACES_VIEWS_VIEW_HANDLER_MODE_PARAM_NAME
```
    The name of the enum context parameter via which the user can set whether the FacesViewsViewHandler should strip the extension from the parent view handler's outcome or construct the URL itself and only take the query parameters (if any) from the parent.
    
    See Also:
    
    ViewHandlerMode, Constant Field Values
  - FACES_VIEWS_ORIGINAL_SERVLET_PATH
```
public static final String FACES_VIEWS_ORIGINAL_SERVLET_PATH
```
    The name of the request attribute under which the original request servlet path is stored.
    
    See Also:
    
    Constant Field Values
  - FACES_VIEWS_ORIGINAL_PATH_INFO
```
public static final String FACES_VIEWS_ORIGINAL_PATH_INFO
```
    The name of the request attribute under which the original request path info is stored.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - registerForwardingFilter
```
public static void registerForwardingFilter(ServletContext servletContext)
```
    This will register the FacesViewsForwardingFilter. This is invoked by ApplicationInitializer.
    
    Parameters:
    
    servletContext - The involved servlet context.
  - addFacesServletMappings
```
public static void addFacesServletMappings(ServletContext servletContext)
```
    This will map the FacesServlet to extensions found during scanning in ApplicationInitializer. This is invoked by ApplicationListener, because the FacesServlet has to be available.
    
    Parameters:
    
    servletContext - The involved servlet context.
  - registerViewHander
```
public static void registerViewHander(ServletContext servletContext)
```
    Register a view handler that transforms a view id with extension back to an extensionless one. This is invoked by FacesViewsViewHandlerInstaller, because the Application has to be available.
    
    Parameters:
    
    servletContext - The involved servlet context.
  - isFacesViewsEnabled
```
public static boolean isFacesViewsEnabled(ServletContext servletContext)
```
    Returns whether FacesViews feature is enabled. That is, when the org.omnifaces.FACES_VIEWS_ENABLED context parameter value does not equal false.
    
    Parameters:
    
    servletContext - The involved servlet context.
    
    Returns:
    
    Whether FacesViews feature is enabled.
    
    Since:
    
    2.5
  - isMultiViewsEnabled
```
public static boolean isMultiViewsEnabled(ServletContext servletContext)
```
    Returns whether MultiViews feature is enabled. This is implicitly enabled when org.omnifaces.FACES_VIEWS_SCAN_PATHS context parameter value is suffixed with /*.
    
    Parameters:
    
    servletContext - The involved servlet context.
    
    Returns:
    
    Whether MultiViews feature is enabled.
    
    Since:
    
    2.5
  - stripWelcomeFilePrefix
```
public static String stripWelcomeFilePrefix(ServletContext servletContext,
                                            String resource)
```
    Strips any mapped welcome file prefix path from the given resource.
    
    Parameters:
    
    servletContext - The involved servlet context.
    
    resource - The resource.
    
    Returns:
    
    The resource without the welcome file prefix path, or as-is if it didn't start with this prefix.
    
    Since:
    
    2.5
  - stripFacesViewsPrefix
```
public static String stripFacesViewsPrefix(String resource)
```
    Strips any special '/WEB-INF/faces-views' prefix path from the given resource.
    
    Parameters:
    
    resource - The resource.
    
    Returns:
    
    The resource without the special prefix path, or as-is if it didn't start with this prefix.

Class FacesViews

Usage

Zero configuration

Minimal configuration

MultiViews configuration

Advanced configuration

PrettyFaces

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

WEB_INF_VIEWS

FACES_VIEWS_ENABLED_PARAM_NAME

FACES_VIEWS_SCAN_PATHS_PARAM_NAME

FACES_VIEWS_SCANNED_VIEWS_EXTENSIONLESS_PARAM_NAME

FACES_VIEWS_EXTENSION_ACTION_PARAM_NAME

FACES_VIEWS_PATH_ACTION_PARAM_NAME

FACES_VIEWS_DISPATCH_METHOD_PARAM_NAME

FACES_VIEWS_FILTER_AFTER_DECLARED_FILTERS_PARAM_NAME

FACES_VIEWS_VIEW_HANDLER_MODE_PARAM_NAME

FACES_VIEWS_ORIGINAL_SERVLET_PATH

FACES_VIEWS_ORIGINAL_PATH_INFO

Method Detail

registerForwardingFilter

addFacesServletMappings

registerViewHander

isFacesViewsEnabled

isMultiViewsEnabled

stripWelcomeFilePrefix

stripFacesViewsPrefix