org.omnifaces.resourcehandler

Class UnmappedResourceHandler

java.lang.Object

javax.faces.application.ResourceHandler

javax.faces.application.ResourceHandlerWrapper

org.omnifaces.resourcehandler.DefaultResourceHandler

org.omnifaces.resourcehandler.UnmappedResourceHandler

All Implemented Interfaces:

FacesWrapper<ResourceHandler>

public class UnmappedResourceHandler
extends DefaultResourceHandler

This ResourceHandler implementation allows the developer to map JSF resources on an URL pattern of /javax.faces.resource/* (basically, the value of ResourceHandler.RESOURCE_IDENTIFIER) without the need for an additional FacesServlet prefix or suffix URL pattern in the default produced resource URLs, such as /javax.faces.resource/faces/css/style.css or /javax.faces.resource/css/style.css.xhtml. This resource handler will produce unmapped URLs like /javax.faces.resource/css/style.css. This has the major advantage that the developer don't need the #{resource} EL expression anymore in order to properly reference relative URLs to images in CSS files.

So, given the following folder structure,

 WebContent
  `-- resources
       `-- css
            |-- images
            |    `-- background.png
            `-- style.css
 

And the following CSS file reference (note: the library is not supported by the UnmappedResourceHandler! this is a technical limitation, just exclusively use name):

 <h:outputStylesheet name="css/style.css" />
 

you can in css/style.css just use:

 body {
     background: url("images/background.png");
 }
 

instead of

 body {
     background: url("#{resource['css/images/background.png']}");
 }
 

This has in turn the advantage that you don't need to modify the background image or font face URLs in CSS files from 3rd party libraries such as Twitter Bootstrap, FontAwesome, etcetera.

Installation

To get it to run, this handler needs be registered as follows in faces-config.xml:

 <application>
     <resource-handler>org.omnifaces.resourcehandler.UnmappedResourceHandler</resource-handler>
 </application>
 

And the FacesServlet needs to have an additional mapping /javax.faces.resource/* in web.xml. For example, assuming that you've already a mapping on *.xhtml:

 <servlet-mapping>
     <servlet-name>facesServlet</servlet-name>
     <url-pattern>*.xhtml</url-pattern>
     <url-pattern>/javax.faces.resource/*</url-pattern>
 </servlet-mapping>
 

CombinedResourceHandler

If you're also using the CombinedResourceHandler or any other custom resource handler, then you need to ensure that this is in faces-config.xml declared before the UnmappedResourceHandler. Thus, like so:

 <application>
     <resource-handler>org.omnifaces.resourcehandler.CombinedResourceHandler</resource-handler>
     <resource-handler>org.omnifaces.resourcehandler.UnmappedResourceHandler</resource-handler>
 </application>
 

Otherwise the combined resource handler will still produce mapped URLs. In essence, the one which is later registered wraps the previously registered one.

Since:

1.4

Author:

Bauke Scholtz

See Also:

DefaultResource, DefaultResourceHandler

Field Summary

Fields inherited from class javax.faces.application.ResourceHandler

LOCALE_PREFIX, RESOURCE_CONTRACT_XML, RESOURCE_EXCLUDES_DEFAULT_VALUE, RESOURCE_EXCLUDES_PARAM_NAME, RESOURCE_IDENTIFIER, WEBAPP_CONTRACTS_DIRECTORY_PARAM_NAME, WEBAPP_RESOURCES_DIRECTORY_PARAM_NAME

Constructor Summary

Constructors

Constructor and Description
UnmappedResourceHandler(ResourceHandler wrapped) Creates a new instance of this unmapped resource handler which wraps the given resource handler.

Method Summary

Modifier and Type	Method and Description
Resource	createResource(String resourceName, String libraryName, String contentType) Delegate to createResource(String, String, String) of the wrapped resource handler.
void	handleResourceRequest(FacesContext context)
boolean	isResourceRequest(FacesContext context) Returns true if ExternalContext.getRequestServletPath() equals ResourceHandler.RESOURCE_IDENTIFIER.

Methods inherited from class org.omnifaces.resourcehandler.DefaultResourceHandler

createResource, createResource, getWrapped

Methods inherited from class javax.faces.application.ResourceHandlerWrapper

createResourceFromId, createViewResource, getRendererTypeForResourceName, isResourceURL, libraryExists

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UnmappedResourceHandler

public UnmappedResourceHandler(ResourceHandler wrapped)

Creates a new instance of this unmapped resource handler which wraps the given resource handler.

Parameters:

wrapped - The resource handler to be wrapped.

Method Detail

createResource

public Resource createResource(String resourceName,
                               String libraryName,
                               String contentType)

Delegate to createResource(String, String, String) of the wrapped resource handler. If it returns non-null, then return an unmapped resource.

Overrides:

createResource in class DefaultResourceHandler

isResourceRequest

public boolean isResourceRequest(FacesContext context)

Returns true if ExternalContext.getRequestServletPath() equals ResourceHandler.RESOURCE_IDENTIFIER.

Overrides:

isResourceRequest in class ResourceHandlerWrapper

handleResourceRequest

public void handleResourceRequest(FacesContext context)
                           throws IOException

Overrides:

handleResourceRequest in class ResourceHandlerWrapper

Throws:

IOException