PrimeFaces themes are bundled as JAR files. Community themes are free and available for download at the PrimeFaces repository (http://repository.primefaces.org/org/primefaces/themes). Each theme can be quickly previewed before download at PrimeFaces Theme Gallery (http://primefaces.org/themes) or tested in the PrimeFaces Showcase with an integrated theme switcher.
In this recipe, we will install and configure themes to use them in an JSF application. The steps to accomplish this task are straightforward.
If you are a Maven (http://maven.apache.org) user, ensure that you have Maven installed. Maven is a build and project management tool, which manages installation of all dependencies in an easy way. PrimeFaces is a Maven-based project and offers all artifacts, including themes, as Maven dependencies.
Maven users should define any desired theme artifact in their project's pom.xml
as follows:
<dependency> <groupId>org.primefaces.themes</groupId> <artifactId>cupertino</artifactId> <version>1.0.10</version> </dependency>
artifactId
is the name of the theme as defined at the Theme Gallery page. Also, make sure that you have the PrimeFaces repository in your pom.xml
:
<repository> <id>prime-repo</id> <name>PrimeFaces Maven Repository</name> <url>http://repository.primefaces.org</url> <layout>default</layout> </repository>
Non-Maven users should download the theme manually from the PrimeFaces repository and place it in the classpath of your application. You can repeat this step for all the themes you need.
Once you have included one or multiple themes, configure PrimeFaces to use them. Set the primefaces.THEME
context parameter in web.xml
(deployment descriptor) with its value as the name of the theme that you would like to use as default. Assuming you would like to use Home theme, then, the configuration is:
<context-param> <param-name>primefaces.THEME</param-name> <param-value>home</param-value> </context-param>
That's all. You don't need to manually include any CSS files on your pages or anything else. PrimeFaces will handle everything for you. In case you would like to make the theme dynamic, define an EL expression as the param
value. Assume that you have managed bean UserSettings
keeping the current theme name in a theme
variable. A proper configuration is as follows:
<context-param> <param-name>primefaces.THEME</param-name> <param-value>#{userSettings.theme}</param-value> </context-param>
This is a case where you have installed multiple themes and let users switch them as per a theme switcher. All community themes are also available in an "all-in-one" bundled JAR file that can be included with just one dependency:
<dependency> <groupId>org.primefaces.themes</groupId> <artifactId>all-themes</artifactId> <version>1.0.10</version> </dependency>
The PrimeFaces component library has a special implementation for the JSF standard head
component. PrimeFaces provides the HeadRenderer
class, which is responsible for rendering of the <h:head>
tag. HeadRenderer
automatically detects the current configured theme in web.xml
regardless of whether it is static or dynamic, via the managed bean and renders theme-related resources on the page. After that the page contains a link to theme.css
:
<link type="text/css" rel="stylesheet" href="/showcase/javax.faces.resource/theme.css.jsf?ln=primefaces-home"/>
Aristo is the built-in default theme of PrimeFaces. There is no separate JAR file for it; the theme is delivered with the core PrimeFaces JAR file itself. Therefore, you don't need to install it via Maven or have it extra in the classpath.
If you are using Apache Trinidad (http://myfaces.apache.org/trinidad) or JBoss RichFaces (http://jboss.org/richfaces), PrimeFaces Theme Gallery includes Trinidad's Casablanca and RichFaces' BlueSky themes. You can use them to make the PrimeFaces components look like the Trinidad or RichFaces themes during migration.