Module org.omnifaces
Package org.omnifaces.facesviews

Class FacesViews

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 Faces 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 https://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:

  • Field Details

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

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

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

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

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

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

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

    • FACES_VIEWS_LOWERCASED_REQUEST_URI_PARAM_NAME

      public static final String FACES_VIEWS_LOWERCASED_REQUEST_URI_PARAM_NAME
      The name of the boolean context parameter via which the user can set whether the request URI should only match the lowercased form of the file name. By default, a scanned view of for example /TitleCasedFileName.xhtml will listen to a request URI of /TitleCasedFileName, but when this setting is set to true, then it will instead listen to a lowercased request URI of /titlecasedfilename.
      Since:
      3.14
      See Also:

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

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

  • Method Details

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

    • registerViewHandler

      public static void registerViewHandler(ServletContext servletContext, Application application)
      Register a view handler that transforms a view id with extension back to an extensionless one. This is invoked by ApplicationProcessor, because the Application has to be available.
      Parameters:
      servletContext - The involved servlet context.
      application - The involved faces application.

    • 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

    • isMultiViewsEnabled

      public static boolean isMultiViewsEnabled(HttpServletRequest request)
      Returns whether MultiViews feature is enabled on given request.
      Parameters:
      request - The involved HTTP servlet request.
      Returns:
      Whether MultiViews feature is enabled on given request.
      Since:
      2.6

    • isMultiViewsEnabled

      public static boolean isMultiViewsEnabled(ServletContext servletContext, String resource)
      Returns whether MultiViews feature is enabled on the given resource.
      Parameters:
      servletContext - The involved servlet context.
      resource - The resource.
      Returns:
      Whether MultiViews feature is enabled on the given resource.
      Since:
      3.6

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