We sometimes need to create our own themes instead of using the predefined ones. Web applications should often feature a company-specific look and feel, which is constant and preset by company-wide style guides. Creating new themes is easy with PrimeFaces because it is powered by the ThemeRoller CSS Framework (http://jqueryui.com/themeroller). ThemeRoller provides a powerful and easy-to-use online visual tool.
In this recipe, we will systematically show all the required steps to create a new theme.
To gain first-hand experience of the ThemeRoller online visual tool, go to the ThemeRoller home page, explore the available theme's Gallery, and play with the CSS properties to see changes for jQuery widgets embedded on the page. All CSS changes will be applied on the fly.
The simplest way to make our own theme is to modify one of the existing PrimeFaces themes. Choose one from the PrimeFaces Theme Gallery (http://primefaces.org/themes), which is close to your needs. All the themes are downloadable JAR files. The JAR structure is listed here (example for the Home theme):
- jar
- META-INF
- resources
- primefaces-home
- theme.css
- images
- ...Assume that our new theme has the name funny. We can now create the following structure in a web project below the resources folder:
- war
- resources
- primefaces-funny
- theme.css
- images
- ...Or create quite a new JAR project for the new theme as follows:
- jar
- META-INF
- resources
- primefaces-funny
- theme.css
- images
- ...The second way is preferred because it would be conforming to the PrimeFaces theme convention. JAR files can be shared across multiple web applications by adding them to the classpath. The last step consists of modifying theme.css according to our needs. Knowledge of CSS selectors is necessary.
If no predefined theme matches our requirements, we should use the ThemeRoller online tool. We have to select one of the existing themes (the Gallery tab) and edit it (the Roll Your Own tab). A click on the Download theme button accomplishes the work.
Next, we need to migrate the downloaded theme files from ThemeRoller to the PrimeFaces theme infrastructure. The migration steps are straightforward.
- The theme package that we have downloaded will have a CSS file
jquery-ui-{version}.custom.cssand a folderimages. Extract the package and rename the CSS file astheme.css. - Image references in the
theme.cssfile must be converted to JSF expressions, which can be understood by the JSF resource loading mechanism. An example for the original CSS file would be as follows:url("images/ui-bg_highlight-hard_100_f9f9f9.png")This should be converted to the following:
url("#{resource['primefaces-funny:images/ui-bg_highlight-hard_100_f9f9f9.png']}") - Create a JAR theme project with the structure shown in this section.
- Once the JAR file is in the classpath, we can use it as per the configuration in
web.xml.<context-param> <param-name>primefaces.THEME</param-name> <param-value>funny</param-value> </context-param>
JSF 2 has a built-in facility for serving resources. The JSF implementation looks for resources in two locations and in the following order:
/resources: This location represents resources in the web application itself/META-INF/resources: This location represents resources on the classpath
The syntax for image references in CSS files is #{resource[...]}; it activates this facility and allows to load resources from JAR files.
The PrimeFaces' renderer implementation for the <h:head> tag automatically detects the current configured theme in web.xml and renders theme-related resources on the page.
There is also a third-party Theme Converter application where you can upload your custom theme (zip file) created with ThemeRoller (https://themeroller.osnode.com/themeroller). The application will generate a JAR file for you. This is the easiest way to create your custom themes without requiring knowledge of CSS.