Using the Resource Framework with CSS Style Sheets

By: Derek Berube, Wildstar Technologies, LLC.
Last Update: December 31, 2011

Back in 2008, when I read Ryan Lubke's "JSF 2.0 New Feature Preview Series (Part 2.1): Resources", "JSF 2.0 New Feature Preview Series (Part 2.2): Resources", and "JSF 2.0 New Feature Preview Series (Part 2.3): Resources" articles, I was excited to learn about the new mechanisms for managing resources coming with the JavaServer Faces 2.0 specification.  This article guides web application developers with information on how to leverage the JSF 2.0 resource management framework in Cascading Style Sheet definitions.

Background

First and foremost, the 2.0 revision of the JavaServer Faces specification provides two standard locations for resources relative to the context root of your web application.
  • /resources
  • /META-INF/resources
Which of the locations you intend to use in your web application is really a matter of personal preference. The /resources directory is accessible to users of your web application whereas the /META-INF/resources directory is considered private and is only directly-accessible to your web application.

In developing the new resource management framework, the architects of the JSF 2.0 platform took inspiration from the convention over configuration aspects of some of the more popular web application frameworks available at the time. By doing this, they provide automatic localization and version management as long as developers adhere to the following structural pattern for the files in the /resources directory.

[localePrefix/][libraryName/][libraryVersion/]resourceName[/resourceVersion]

NOTE: The elements surrounded by brackets ( [ ] ) are considered optional.  Only the resourceName is required.

In keeping with the "ease-of-use" theme for JSF 2.0, a standardized expression language syntax is provided for accessing resources regardless of which directory in which they reside:

#{resource['libraryName/fileName']}

The resource object is explained in greater detail in Ryan Lubke's "JSF 2.0 New Feature Preview Series (Part 2.3): Resources" article.

Shortly after working with the resource management framework in my JSF 2 applications, I wondered how I could leverage this framework for images declared in my CSS stylesheets.  Ryan Lbuke's first article on the new resource management framework outlines the following URL pattern which will be used in the HTML generated by the framework.

<context-root>/javax.faces.resource/<resource-name>[?ln=<library-name>][&loc=<locale-prefix>][&v=<version>]

NOTE: The elements surrounded by brackets ( [ ] ) are considered optional.  Only the resource-name element is required.

By leveraging the notation of a Uniform Resource Locator prescribed in section "6.4 URL" of the "Cascading Style Sheets, Level 1" standard and incorporating the URL format shown above, we have the pattern shown below for identifying resources in our CSS files.

url('/javax.faces.resource/.jsf[?ln=][&loc=][&v=')

ParameterDescription
 lnThe name of the library which is a sub-directory found in either the /resources or /META-INF/resources directory relative to your web application's context root.  If the library is locale-specific, then the directory identified by the ln parameter will actually be a sub-directory found in a sub-directory corresponding to the two-character country-code identifying the locale.

For example, say you wanted to use a graphic image (background.png) that is in the images resource library as the background for a web page.  You would use the following URL:

url('/javax.faces.resource/background.png.jsf?ln=images');
 locIdentifies a specific local that should be used when the resource management framework returns the specified resource.  If this parameter is omitted, the default locale specified by the client will be used.

NOTE: The supported codes for countries are defined in the ISO 3166 standard.

Continuing with the example used from the ln parameter, say you wanted to use a locale-specific background image for France.  The following would be the URL used in your stylesheet.

url('/javax.faces.resource/background.png.jsf?ln=images&loc=FR');
 vIdentifies a specific version of a resource that should be used to satisfy the resource request.  If this parameter is omitted, the highest available of the identified resource will be returned.

In the context of our background.png image, the CSS file would contain the following line to identify version 1.1 of the image file:

url('/javax.faces.resource/background.png.jsf?ln=images&loc=FR&v=1_1');

NOTE: Web developers should be aware of the fact that per the Cascading Style Sheets, level 1 specification, the following characters should be escaped with a backslash.

CharacterEscaped Value
(\( 
 )\) 
 ,\, 
'\'
 "\" 

In addition, whitespace characters should also be escaped with a backslash.

Faces Servlet Configuration Consideration

In the URL example provided above, it is assumed that you have configured your web application to map the .jsf extension to the Faces Servlet (as shown below).

<servlet-mapping>

<servlet-name>Faces Servlet</servlet-name>

<url-pattern>*.jsf</url-pattern>

<url-pattern>/faces/*</url-pattern>

</servlet-mapping>

Should you elect to use some other file extension, you will have to replace .jsf in the example above with the extension defined in your servlet-mapping for the Faces servlet.

Putting Everything into Action

The goal for this article is to produce the web page depicted in the screenshot below using standard cascading style sheets and the new resource management capabilities provided by the JavaServer Faces 2.0 web application framework.  The image of Duke waving is a scaled down version of wave.png taken from the Duke Images archive found at http://duke.kenai.com/wave/index.html.  It has been loaded as the background for the <body> element in the HTML page.  The stylesheet tells the browser to place the waving Duke image in the top right corner of the web page.  It also tells the browser that the image should NOT be repeated.



The reference page shown above is publicly accessible at the http://jsf2gae.wildstartech.com/resourceManagerCSSExample/resourceManagerCSSExample.jsf URL.  The following is the contents of the resourceManagerCSSExample.jsf file.

<!DOCTYPE html 

     PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"

     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"

   xmlns:f="http://java.sun.com/jsf/core"

   xmlns:h="http://java.sun.com/jsf/html"

   xmlns:ui="http://java.sun.com/jsf/facelets">

   <h:head id="head">

      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

      <title>Resource Manager CSS Example</title>      

   </h:head>

   <h:body id="body">

      <h:outputStylesheet name="resourceManagerCSSExample.css" 

         library="resourceManagerCSSExample" 

         target="head" />

      <p>Example of using JSF 2.0 resource management framework with CSS.</p>      

   </h:body>

</html>


In the example page above, the following snippet of code is used to instruct the browser to load the resourceManagerCSSExample.css stylesheet.

<h:outputStylesheet name="resourceManagerCSSExample.css" 

         library="resourceManagerCSSExample" 

         target="head" />


The <h:outputStylesheet> tag is something Ryan Lubke talks about in his "JSF 2.0 New Feature Preview Series (Part 4) Resource Re-location" article.  The official JavaDoc for the <h:outputStylesheet> tag is also available.

The following is the complete content of the resourceManagerCSSExample.css file.

body {
background-image: url('/javax.faces.resource/wave.png.jsf?ln=resourceManagerCSSExample');
background-repeat: no-repeat;
background-position: right top;
}

The value used for the background-image style identifies a uniform resource locator (URL) that leverages the JSF 2.0 resource management framework to obtain the wave.png file from the /resources/resourceManagerCSSExample directory of the jsf2gae web application.

References

The following documents or web sites were referenced in the process of composing this article.
Comments