How to reference CSS / JS / image resource in Facelets template?

by

Introduction

The proper JSF 2.x way is using <h:outputStylesheet>, <h:outputScript> and <h:graphicImage> with a name referring the path relative to webapp’s /resources folder. This way you don’t need to worry about the context path as you would do in JSF 1.x. See also How to include CSS relative to context path in JSF 1.x?

Folder structure

Drop the CSS/JS/image files in /resources folder of the public webcontent as below (just create one if not already exist at the same level as /WEB-INF and /META-INF).

WebContent
 |-- resources
 |    |-- css
 |    |    |-- other.css
 |    |    `-- style.css
 |    |-- js
 |    |    `-- script.js
 |    `-- images
 |         |-- background.png
 |         |-- favicon.ico
 |         `-- logo.png
 |-- META-INF
 |    `-- MANIFEST.MF
 |-- WEB-INF
 |    |-- faces-config.xml
 |    `-- web.xml
 |-- page.xhtml
 :

In case of Maven, it should be in /main/webapp/resources and thus not /main/resources (those are for Java resources (properties/xml/text/config files) which must end up in runtime classpath, not in webcontent). See also Maven and JSF webapp structure, where exactly to put JSF resources.

Referencing in Facelets

Ultimately, those resources are available as below everywhere without the need to fiddle with relative paths:

<h:head>
    ...
    <h:outputStylesheet name="css/style.css" />
    <h:outputScript name="js/script.js" />
</h:head>
<h:body>
    ...
    <h:graphicImage name="images/logo.png" />
    ...
</h:body>

The name attribute must represent the full path relative to the /resources folder. It does not need to start with /. You do not need the library attribute as long as you aren’t developing a component library like PrimeFaces or a common module JAR file which is shared by multiple webapps.

You can reference the <h:outputStylesheet> anywhere, also in <ui:define> of template clients without the need for an additional <h:head>. It will via the <h:head> component of master template automatically end up in generated <head>. 

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

You can reference <h:outputScript> also anywhere, but it will by default end up in the HTML exactly there where you declared it. If you want it to end up in <head> via <h:head>, then add target="head" attribute. 

<ui:define name="...">
    <h:outputScript name="js/script.js" target="head" />
    ...
</ui:define>

Or, if you want it to end up at the end of <body> (right before </body>, so that e.g. window.onload and $(document).ready() etc isn’t necessary) via <h:body>, then add target="body" attribute.

<ui:define name="...">
    <h:outputScript name="js/script.js" target="body" />
    ...
</ui:define>

PrimeFaces HeadRenderer

In case you’re using PrimeFaces, its HeadRenderer will messup the default <h:head> script ordering as described above. You’re basically forced to force the order via PrimeFaces-specific <f:facet name="first|middle|last">, which may end up in messy and “untemplateable” code. You may want to turn off it as described in this answer.

Packaging in JAR

You can even package the resources in a JAR file. See also Structure for multiple JSF projects with shared code.

Referencing in EL

You can in EL use the #{resource} mapping to let JSF basically print a resource URL like /context/javax.faces.resource/folder/file.ext.xhtml?ln=library so that you could use it as e.g. CSS background image or favicon. Only requirement is that the CSS file itself should also be served as a JSF resource, otherwise EL expressions won’t evaluate. See also How to reference JSF image resource as CSS background image url.

.some {
    background-image: url("#{resource['images/background.png']}");
}

Here’s the @import example.

@import url("#{resource['css/other.css']}");

Here’s the favicon example. See also Add favicon to JSF project and reference it in <link>.

<link rel="shortcut icon" href="#{resource['images/favicon.ico']}" />

In case you’re using a SCSS compiler (e.g. Sass Compiler Plugin for Maven), keep in mind that the SCSS processor might interpret # as a special character. In that case you would need to escape it with \.

.some {
    background-image: url("\#{resource['images/background.png']}");
}

Referencing third-party CSS files

Third party CSS files loaded via <h:outputStylesheet> which in turn reference fonts and/or images may need to be altered to use #{resource} expressions as described in previous section, otherwise an UnmappedResourceHandler needs to be installed in order to be able to serve those using JSF. See also a.o. Bootsfaces page shows up in browser without any styling and How to use Font Awesome 4.x CSS file with JSF? Browser can’t find font files.

Hiding in /WEB-INF

If you intend to hide the resources from public access by moving the whole /resources folder into /WEB-INF, then you can since JSF 2.2 optionally change the webcontent-relative path via a new web.xml context parameter as follows:

<context-param>
    <param-name>javax.faces.WEBAPP_RESOURCES_DIRECTORY</param-name>
    <param-value>/WEB-INF/resources</param-value>
</context-param>

In older JSF versions this is not possible.

See also:

More Related Contents:

  1. Obtaining Facelets templates/files from an external filesystem or database
  2. JSTL in JSF2 Facelets… makes sense?
  3. JSF returns blank/unparsed page with plain/raw XHTML/XML/EL source instead of rendered HTML output
  4. How to include another XHTML in XHTML using JSF 2.0 Facelets?
  5. What is the JSF resource library for and how should it be used?
  6. Why do I need to nest a component with rendered=”#{some}” in another component when I want to ajax-update it?
  7. Which XHTML files do I need to put in /WEB-INF and which not?
  8. When using templating, where should I declare the ?
  9. Packaging Facelets files (templates, includes, composites) in a JAR
  10. How can I set id of a component/tag inside ui:repeat
  11. How to create a custom Facelets tag?
  12. Avoiding duplicate ids when reusing facelets compositions in the same naming container
  13. How to implement a dynamic list with a JSF 2.0 Composite Component?
  14. Error Parsing /page.xhtml: Error Traced[line: 42] The entity “nbsp” was referenced, but not declared
  15. Why is the getter called so many times by the rendered attribute?
  16. Does it matter whether place f:event inside f:metadata or not?
  17. Backing beans (@ManagedBean) or CDI Beans (@Named)?
  18. How to make a grid of JSF composite component?
  19. Understand Flash Scope in JSF2
  20. java.lang.NoClassDefFoundError: javax/servlet/jsp/jstl/core/Config
  21. Which XML namespace to use with JSF 2.2 and up
  22. Use enum in h:selectManyCheckbox
  23. java.lang.IllegalStateException:Could not find backup for factory javax.faces.application.ApplicationFactory
  24. Is there any easy way to preprocess and redirect GET requests?
  25. How to replace @ManagedBean / @ViewScope by CDI in JSF 2.0/2.1
  26. Does view scope bean survive Navigation JSF
  27. JSF 2 Global exception handling, navigation to error page not happening
  28. How do UISelectOne and UISelectMany components preselect defaults in f:selectItems
  29. Is Facelets page generated to Servlet as JSP generated to Servlet
  30. Skip required validation and invoke the application

Leave a Comment