public class UnmappedResourceHandler
extends ResourceHandlerWrapper

The UnmappedResourceHandler allows the developer to map JSF resources on an URL pattern of /javax.faces.resource/* 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. Given the following folder structure,

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

And the following CSS file reference (note: resource libraries are not supported by the UnmappedResourceHandler! this is a technical limitation):

 <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']}");
 }
 

Configuration

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.