CSS URL Mapping
Motivation
Typical web applications often make use of Cascading Style Sheets for handling the appearance of web pages, and JSF applications are no exception. However, JSF has a resource handling system with well-defined rules for accessing resources. Therefore, any resources served through this system have to be accessed with correctly formatted URLs. CSS files usually contain 'url()' expressions to specify the location of images. If these images are also served through the JSF resource handling system, then the URLs in CSS files that access these images must be correctly formatted as well. When working in a development environment or when using third-party resources like the YUI library, it will be necessary, at some point, to modify all URL occurrences in CSS files to have the correct format for the JSF resource handling system, so that the referenced resources can be served in production environments. This tool does the job of parsing CSS files and mapping all occurrences of 'url()' expressions to the correct format to work with the JSF resource handling system.
Format
The JSF resource handling format is explained in detail in section 2.6 of the JSF 2.0 specification. Only the most important points are explained here. It is best to start by illustrating the format with a typical example.
A background image located in a different directory than the CSS file in question might be declared as follows:
url(../images/background.png)
This url would be mapped as follows:
url(#{resource['org.site.lib/images/background.png']})
This format can be broken down into three logical parts.
The first part is the resource declaration format, which is constant:
The second part is the name of the resource library in which the image will be located in a production environment.
The third part is the full path to the resource starting from the root directory of the resource library.
This is an important point, since the JSF resource handling system needs to work with canonical paths. It does not recognize relative paths containing of '/../'
Therefore, this tool also does the job of determining the canonical path from the resource library root directory. It is also important to note that the JSF specification also allows some other URL formats, but this tool only uses the format described above (i.e. libraryName/path/to/resource).
URLs starting with 'http://' or '#{resource' will not be modified since they reference external resources or are already in the correct format.
Usage
Again, it is better to start by illustrating a typical example. This tool might be invoked as follows:
> cssurlmapper --library-name myLibrary --root-dir ../css --output-dir ../out
The --library-name parameter is required and specifies the name of the resource library where the resource will be located in the production environment.
The --root-dir parameter specifies the directory name where this tool should start looking for files with css extension to parse. Alternatively, a single file to parse can be specified with the --file parameter. It is required to specify one of these two parameters. The --root-dir parameter takes precedence.
The --output-dir parameter is required and specifies the directory where the output files will be written. This directory will have the same structure as the directory specified with the --root-dir parameter. All output files will have the same name as the original files.
The --reference-dir parameter is optional and allows to specify a different starting point to build the full canonical path for the resources. If this parameter is not specified, the reference directory will be the same as the one specified with --root-dir, or the same directory containing the file specified with --file.
The --help parameter will print a brief description of the tool itself and of all parameters.
ACE CSS URL Mapping