PrimeFaces theme setup and new theme definition

PrimeFacesPrimeFaces is using ThemeRoller framework from jQuery, and it comes with a lot of pre-defined themes that you can preview and download from Primefaces theme gallery. This tutorial will provide details of how can you handle with applying a pre-defined  theme and also creating a new one.

Part 1: Applying a PrimeFaces theme

 Setting up and configuring PrimeFaces library

PrimeFaces is an open source UI component library with one JAR file for JSF (JavaServer Faces) based application, which can be easily integrated into your project by getting the specific artifact.

For the purpose of this tutorial, we are using Maven as a build and project management tool, which manages installation of all dependencies. For more information about installing Maven, please visit http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html.

With Maven installed, lets create our sample web project using the corresponding Maven archetype.  For more information about how to create a JSF project with Maven please visit http://www.javaserverfaces.org/get-started .

In the next step we will setup and configure PrimeFaces library by adding the following repository and dependency to project POM file:

primefaces_repository

primefaces_dependency

For non Maven users, you can download the PrimeFaces library from http://primefaces.org/downloads and add the downloaded jar to your project classpath.

Create JSF view page and the Managed Bean

For this tutorial I have chosen PickList from http://primefaces.org/showcase/  to demonstrate how the theme is applied to this component. Feel free to choose something else if you want.

Our JSF view page should have the following structure:

jsf_page

The corresponding Managed Bean :

PickListView.java 

managed_bean

Define a new theme

Defining a theme for your project is just as easy as PrimeFaces library setup. PrimeFaces is a Maven-based project and it offers all artifacts, including themes, as Maven dependencies. So the first step that we have to take is to define a theme as a Maven dependency into our POM file. Navigate to PrimeFaces Theme Gallery  page (http://primefaces.org/themes.html) and choose the one you like. For our sample project I have chosen Cupertino theme.

Now let’s add the theme as dependency to our project:

cupertino_dependency

The artifactId is the name of the theme as defined at the Theme Gallery page.

Non-Maven users should download the theme manually from PrimeFaces repository (http://repository.primefaces.org/org/primefaces/themes/ ) and place it in the classpath of the project.

The last step that we have to take is to define the primefaces.THEME context parameter in web.xml :

context_param_theme

If everything was done as mentioned you will be able to see that Cupertino Theme has been applied to the PickList :

picklist_cupertino_theme

picklist_cupertino_theme2

Part 2: Create a new theme

In this part of tutorial we will create a custom theme and apply it to the previously created project.

Create the JAR project that contains our custom theme

As specified also in the beginning of this tutorial, PrimeFaces is powered by the ThemeRoller CSS framework (http://jqueryui.com/themeroller/), so for the purpose of showing how to setup a custom theme to your project,  choose on that is available in ThemeRoller home page.

Select Gallery tab chose one and then click Edit.  Feel free to make any changes then click Download theme button.

Select theme

choose_theme_roller

Download theme

download_theme_roller

Let’s create now a new project that will contain the custom theme. Choose maven-archetype-quickstart  to generate our JAR project.

Inside src define the following hierarchy of folders:

custome_theme_project

Inside primesfaces-custom folder will be added the corresponding css styles and resources for our theme. There are same steps to take in order to migrate the downloaded theme files from ThemeRoller to the PrimeFaces theme infrastructure.

Extract the downloaded packge and you will find a jquery-ui-{version}.custom.css file and a folder images . Rename the .css file to theme.css  and move it inside primefaces-custom folder together with the folder images.

The last change that we should make before installing the jar file into local repository is to modify the images references from theme.css  file in order to be understood by  the JSF resource loading mechanism. Please replace

url(“images/ui-[image-name].png”) 

with

url(“#{resource[‘primefaces-custom:images/ui-[image-name].png’]}”) 

The final structure for our JAR project should look like

theme_project_jar

Install the project into the local Maven repository, add the theme project as a dependency to your JSF project and define the primefaces.THEME context parameter to web.xml file :

context_param_theme2

If everything was performed correctly you will be able to see that the defined theme is applied to PickList component :picklist_custom_theme

picklist_custom_theme2

 

Leave a Reply

Your email address will not be published. Required fields are marked *

one × 1 =