Chapter 13. Using PrimeFaces Themes

PrimeFaces components are built with theming support based on the ThemeRoller CSS framework. At the time of writing this book, PrimeFaces provides 38 pre-designed community themes which are ready to use for free. We can also create our own themes using the online ThemeRoller tool and integrate them with PrimeFaces.

Our TechBuzz application will be developed with multiple themes support, and users can select their favorite theme and change to other themes at anytime.

In this chapter we will cover the following topics:

• Configuring and using themes

• Using stateless ThemeSwitcher

• Using stateful ThemeSwitcher

• Creating and using custom theme

Configuring and using themes

The PrimeFaces components come with a default theme support called aristo and doesn't require any explicit configuration. If you want to use other themes you need to add those themes dependencies and configure them explicitly.

PrimeFaces themes are bundled as JAR files and we can download them from PrimeFaces Themes Repository http://repository.primefaces.org/org/primefaces/themes/.

Currently PrimeFaces provides the following list of community themes, which are free to use:

If you are using the Maven build tool you can add the boostrap theme jar as a Maven dependency as follows:

<dependency>
  <groupId>org.primefaces.themes</groupId>
  <artifactId>bootstrap</artifactId>
  <version>1.0.10</version>
</dependency>

In addition to these individual theme jars, PrimeFaces provides the all-themes jar, which includes all the themes support. In Maven pom.xml you can configure the all-themes jar dependency as follows:

<dependency...

Using stateless ThemeSwitcher

The PrimeFaces ThemeSwitcher component provides the ability to change theme on the fly without page refresh. Usage of ThemeSwitcher is similar to the SelectOneMenu component.

Time for action – using the stateless ThemeSwitcher component

Let us see how we can change theme dynamically using the ThemeSwitcher component.

1. Create a <p:themeSwitcher> component by providing list of theme names as options:

   <p:themeSwitcher style="width:165px">  
     <f:selectItem itemLabel="Choose Theme" itemValue="" />  
     <f:selectItems value="#{userPreferences.themes}" />  
   </p:themeSwitcher>

2. Implement a managed bean method to return the list of all Primefaces supporting theme names:

   @ManagedBean
   @SessionScoped
   public class UserPreferences implements Serializable
   {
     private List<String> themes;
     public UserPreferences()
     {
       themes = new ArrayList<String>();  
       themes.add("afterdark");
   themes.add("afternoon");
   themes.add("afterwork");
   themes.add("aristo");
   themes.add("black-tie");
   themes.add("blitzer");
   themes.add("bluesky");
   themes.add("bootstrap");
       ...
       ...
   themes.add("ui-darkness");
   themes.add("ui-lightness");
   themes.add("vader...

Using stateful ThemeSwitcher

We have seen how to configure a theme in web.xml using a context parameter. Instead of configuring a static theme name, we can bind it to an EL expression, which resolves to theme name.

Time for action – applying a user-specific theme using stateful ThemeSwitcher

In this section we will learn how to use the ThemeSwitcher component to apply theme for entire application based on user preference, and how a user can dynamically switch themes:

1. Configure Primefaces theme name in web.xml using EL expression:

   <context-param>
     <param-name>primefaces.THEME</param-name>
     <param-value>#{userPreferences.selectedTheme}</param-value>
   </context-param>

   Here EL expression #{userPreferences.selectedTheme} resolves to a theme name.

2. Create ThemeSwitcher component using <p:themeSwitcher> with value="#{userPreferences.selectedTheme}" along with the AJAX event listener to update the user-preferred theme to the selected theme name on server side:

   <p:themeSwitcher value="#{userPreferences.selectedTheme}"  style="width:165px">  
     <f:selectItem itemLabel="Choose Theme" itemValue="" />  
     <f:selectItems value="#{userPreferences.themes}" />...

Creating and using a custom theme

In addition to the predesigned themes provided by PrimeFaces, you can also create your own themes using ThemeRoller online tool http://jqueryui.com/themeroller/. To use your custom theme you need to update the generated theme CSS file to the suite PrimeFaces infrastructure and package it as a JAR file.

For creating a new theme go to http://jqueryui.com/themeroller/ and update various CSS styles to match your needs. There are various types of UI widgets on the same page using the theme styles that are currently applied on the ThemeRoller tool, so you can see what the components looks like as you update the styles.

Instead of starting from scratch you can choose one of the existing themes in the Gallery tab and edit it:

Let us see how we can create a new theme named seablue.

Time for action – creating a new theme

In this section we will look at how we can create custom theme using the online ThemeRoller tool, and convert it into PrimeFaces theme library.

1. Using online ThemeRoller tool update the styles, click on the Download Theme button which will take you to the Download Builder screen.

2. Uncheck component Toggle All checkbox, enter primefaces-seablue in the Theme Folder Name input box and click on Download.

3. Extract the downloaded ZIP file and go into the CSS folder. You can see the following folder structure:

   primefaces-seablue
     - jquery-ui-{version}.custom.css
         -jquery-ui-{version}.custom.min.css
         -images/

4. Now rename jquery-ui-{version}.custom.css to theme.css.

5. Image references in the theme.css file must be converted to JSF resource loading expressions.

   For example, url(images/ui-bg_flat_75_ffffff_40x100.png) needs to be changed to url("#{resource['primefaces-seablue:images/ui-bg_flat_75_ffffff_40x100.png']}").

6. Package the theme files as JAR with the following...

Time for action – installing and configuring PrimeFaces extensions

Let us see how we can install PrimeFaces extensions and configure it.

1. Configure a primefaces-extensions.jar dependency in pom.xml:

   <dependency>
     <groupId>org.primefaces.extensions</groupId>
     <artifactId>primefaces-extensions</artifactId>
     <version>1.0.0</version>
   </dependency>

2. Add a primefaces-extensions namespace and use any of its components. Let us use tooltip component's autoShow feature:

   <!DOCTYPE html>
   <html xmlns="http://www.w3c.org/1999/xhtml"
   xmlns:h="http://java.sun.com/jsf/html"
   xmlns:p="http://primefaces.org/ui"
   xmlns:pe="http://primefaces.org/ui/extensions">
   <h:head>
   </h:head>
   <h:body>
     <h:form style="width: 800px; margin: 0 auto;">
       <h:panelGrid column="3">
         <h:outputLabel value="Name:" />
         <p:inputText id="name" value="" title="Enter your Name"/>
         <pe:tooltip for="name" autoShow="true"...

Summary

In this chapter, we have learned how to use PrimeFaces provided themes, and how to use ThemeSwitcher component to change themes dynamically. We have also learned how to create custom themes using ThemeRoller online tool and use it.

PrimeFaces is a rapidly growing open source JSF component suite, and providing more and more components for each release. So keep an eye on what is coming up next in the PrimeFaces ecosystem. For more information, visit http://www.primefaces.org/.

We wish you all the best and happy coding!