www.it-ebooks.info
CHAPTER 9: Super Jumper: A 2D OpenGL ES Game
488
For your convenience Apress has placed some of the front
matter material after the index. Please use the Bookmarks
and Contents at a Glance links to access them.
www.it-ebooks.info
iv
Contents at a Glance
Contents v
About the Authors xiii
About the Technical Reviewer xiv
Acknowledgments xv
Introduction xvi
Chapter 1: The Basics 1
Chapter 2: Getting Started 13
Chapter 3: a4j:* Tags, Features and Concepts 43
Chapter 4: Getting Started with Rich Components 85
Chapter 5: Rich Input and Select Components 95
Chapter 6: Rich Panel and Output Components 133
Chapter 7: Rich Data Iteration Components 175
Chapter 8: Rich Menu Components 245
Chapter 9: Rich Tree Components 265
Chapter 10: Rich Drag-and-Drop Components 287
Chapter 11: Rich Validation 305
Chapter 12: Rich Components JavaScript API, Client Functions, and
Using jQuery 317
Chapter 13: Skins 333
Chapter 14: RichFaces CDK: Building Custom Components 355
Index 385
www.it-ebooks.info

www.it-ebooks.info
C H A P T E R 1

  

1

The Basics
Welcome to Practical RichFaces, second edition. In your hands (or on your computer/phone/tablet),
you’ve got everything you need to start developing cool and rich Ajax applications with JSF and
RichFaces. In this first chapter, we will give you a short overview of JavaServer Faces (JSF), as RichFaces
is a framework for JSF. Although we do assume that you have some knowledge of JSF, don’t worry—even
if you are just starting, we made sure the material and all the examples in this book are very easy to
understand. Once we cover JSF, we will discuss RichFaces: its features and the history behind it, how it
got started and where it is today. Lastly, we will share two stories to help you keep an open mind when
using JSF, as well as some tips on working with a server-side framework. The stories are from our
personal experiences and should help you become a better JSF and RichFaces developer.
Tell Me About RichFaces First!
You bought this book to learn about RichFaces, so we are going to squeeze in this short section so you
don’t have to wait. We will then do quick overview of JSF, and go back to telling you more about
RichFaces in more detail. You probably think of RichFaces as a rich component library (and that’s fine).
But, is it also much more. Rich components are just one of the main features that RichFaces offers.
RichFaces is a rich framework for JSF and offers rich and Ajax components in two tag libraries (a4j: and
rich:), a Skins feature, a client-side validation extension based on JSR-303 Bean Validation, and CDK
(Component Development Kit).
Of course you get many other features, which we will cover throughout the book, such as advanced
rendering features, event handling options, and Ajax client queue optimization. The components are
something you can “feel and touch,” so let us give you a quick example of what kind of components
RichFaces offers.
The a4j: tag library offers many core or foundation components, such as buttons and links with

little bit more specific, we are building a browser-based or HTML application, no plug-ins involved. You
are probably thinking, there are at least a couple dozen other frameworks that would fit this description.
JSF has a number of features that makes it different than other frameworks. Let’s review them.
JSF Application Is Built Out of UI Components
JSF is a Java framework for building browser-based user interfaces (UIs) out of reusable components.
The emphasis in JSF is on UI components. When working with UI components, you won’t deal with
HTML markup directly because JSF and other rich components will provide all the necessary UI widgets
to build the application. However, HTML tags still play an important role in the layout of the page.
Within the components themselves, renderers (Java classes for generating HTML) are responsible for
producing the appropriate markup. Because you are building web applications and the client is basically
the browser, the markup needed is HTML (although it can be anything like WML, SGL, or even XML) so
the components’ renderers will generate the HTML markup that will be sent to the client (browser).
JSF Is a Standard
JSF is a part of the Java 6 (and 5) Enterprise Edition (Java EE) platform. This means that a bunch of
companies and individuals got together and agreed on how the framework should work. The debate
whether standards are good or bad is beyond the scope of this book but at least the framework was
designed by more than just one entity.
JSF Has Two Main Versions
Today there are two JSF versions: version 1.2 is a part of the Java EE 5 platform and JSF 2 is a part of the
Java EE 6 platform.
JSF Has Two Main Implementations
Because JSF is a specification, today there are two main implementations. The first is Mojarra, a
reference implementation from Oracle. The other is MyFaces from Apache. A great place to learn more
about JSF is JavaServerFaces.org (www.javaserverfaces.org).
www.it-ebooks.info
CHAPTER 1  THE BASICS

4
JSF Is Very Extendable
The extensibility feature is probably most responsible for making JSF a popular tool for building web

The JSF framework separates a component from the way it is presented (encoding) and the way input is
processed (decoding). The appearance of the component can be easily varied for the type of display
device available (for example, a mobile phone). For this book, you’ll work only with the HTML rendering
kit that JSF provides out of the box.
www.it-ebooks.info
CHAPTER 1  THE BASICS

5
The following list demonstrates some of the features renderers provide:
• Rendering can be done by the component itself or delegated to a special renderer
class.
• Rendering markup such as WML and XML, in addition to HTML.
• Standard JSF components come with an HTML 4.0.1 rendering kit.
Figure 1-4 shows how all this fits together.

Figure 1-4. Tags represent server-side components. Server-side components render markup (HTML) at the
end of the JSF request.
Let’s walk through the numbered parts of this figure.
1. This is a JSF page that consists of JSF tags. When the page is processed by JSF,
these tags create JSF UI components (Java classes) shown in the second part of
the figure.
2. This is the JSF UI component tree that represents the components defined on
the JSF page. The component tree goes through a sophisticated life cycle
where various things happen, such as conversion and validation. At the end,
JSF will ask each component renderer to render markup.
3. The panel on the left is the generated HTML code and the panel on the right
shows what users see in the browser. This is just the standard HTML 4.0.1 version.
www.it-ebooks.info
CHAPTER 1  THE BASICS


need to understand what each phase does. We will be using this same diagram to show RichFaces
concepts. Make sure you understand what each phase does and what happens to the flow in case of a
conversion/validation error or when using the immediate="true" attribute. Understanding the life cycle
can also help with debugging your JSF applications with phase listeners. You will be using a phase
listener later in this book. In case you need to brush up on JSF phases, this article at Javabeat
(www.javabeat.net/articles/54-request-processing-lifecycle-phases-in-jsf-1.html) is a good place
to do that.
www.it-ebooks.info
CHAPTER 1  THE BASICS

7

Figure 1-5. JSF life cycle
Ajax
When JSF 1.x was developed, it didn’t have any Ajax features simply because Ajax didn’t exist as we know
it today. Luckily in 2006 RichFaces came along and made it very easy to add Ajax functionality to existing
or new JSF applications. For example, if you had a standard input text component like the following:
<h:inputText value="#{order.amount}"/>
To send an Ajax request based on some event was very easy with RichFaces. All you had to do is add
the <a4j:support> tag, specify the event to fire the Ajax request, and specify which components to re-
render, as follows:
<h:inputText value="#{order.amount}">
<a4j:support event="onkeyup" reRender="id1"/>
</h:inputText/>
<h:outputText value="#{order.total}" id="id1"/>
When JSF EG (Expert Group) started working on JSF version 2, they introduced basic Ajax support
into the specification. The Ajax behavior <f:ajax> in JSF 2 is closely based on the popular RichFaces 3
<a4j:support> tag. Taking the above example, adding Ajax support in JSF 2 is done like this:
www.it-ebooks.info
CHAPTER 1  THE BASICS

• Skins
• Client-side and object validation extension for Bean Validation (JSR 303)
• CDK (Component Development Kit)
Besides these main parts, RichFaces extends the standard JSF 2 Ajax request queue, and adds
various rendering optimization attributes that we will cover in this book. A RichFaces application can
also be deployed in the cloud, to places such as GAE (Google Apps Engine), Amazon EC2, and
CloudBees, and OpenShift. RichFaces not only extends JSF, it makes JSF richer. In fact, you can’t use
RichFaces without JSF. You use RichFaces with either the Mojarra JSF (Oracle RI) implementation or the
MyFaces implementation. RichFaces simply provides ready-to-use Ajax components (and other
features) to enable building Ajax-based applications. Another way to look at it as extra JSF components
beyond what standard JSF provides. These components provide all the necessary JavaScript, so you
almost never have to work with JavaScript directly.
www.it-ebooks.info
CHAPTER 1  THE BASICS

9
 Note Whenever we mention RichFaces, we always refer to RichFaces version 4. RichFaces 3.x is based on
JSF 1.2. RichFaces 3.3.3 supports JSF 1.2 and has very basic support for JSF 2. This version was introduced for
projects that needed to be deployed on a Java EE 6 application server, which shipped with JSF 2 when RichFaces
4 wasn’t yet available. Everything in this book is based on RichFaces 4 version. Client-side validation is only avail-
able starting with RichFaces 4.
Table 1-1 summarizes JSF and RichFaces version compatibility.
Table 1-1. JSF and RichFaces Compatibility Matrix
JSF 1.1 JSF 1.2 JSF 2
RichFaces 3.1.x X
RichFaces 3.3.2 X
RichFaces 3.3.3 X X (basic support)
RichFaces 4 X
RichFaces’s Component Tag Libraries
RichFaces components are divided into two tag libraries: one tag library is called a4j:, and the other is

Another part of the framework is the Component Development Kit (CDK). The CDK includes various
Maven archetypes, a code generation facility, descriptors and tests generation facility, and a templating
facility that allows the creation of renderer classes using only page code. These features enable a
component developer to avoid the routine process of component creation. The CDK greatly simplifies
and speeds up rich component development with built-in Ajax support. This edition of the book now
includes CDK coverage. CDK is covered in Chapter 13.
Using RichFaces with CDI and Dependency Injection
Contexts and Dependency Injection, or CDI (JSR 299), and Dependency Injection for Java (JSR 330) are
both part of the Java EE 6 platform. Both provide services and components to make it simpler to develop
enterprise Java applications. Although JSF 2 now provides a simpler way to configure beans with
annotations, using CDI beans instead of JSF beans gives a lot more flexibility and power to the developer
by providing a unified programming model. JSF 2 works with CDI Beans out of the box. As RichFaces 4 is
based on JSF 2, CDI can be used with any RichFaces 4 components as well. So that we don’t introduce
another layer (which is really outside the scope of this book), examples in this book will use standard JSF
beans. In all examples, JSF beans can be easily replaced with CDI beans.
RichFaces: A Historical Perspective
If you search for RichFaces, eventually you will see a reference to Ajax4jsf. This section provides a brief
history of Ajax4jsf and how it became part of RichFaces. Ajax4jsf has its roots in RichFaces. The Ajax4jsf
framework was created and designed by Alexander Smirnov. In early 2005, he was looking to add a
“hot” new technology along with the associated experience to his résumé. Roughly at the same time,
Jesse James Garrett was establishing the concept of Ajax. Meanwhile, JSF was starting to pick up steam.
Alexander figured, why not just merge the two so it would be easy to have Ajax functionality within a
JSF application?
He started the project on SourceForge.net, called it Telamon (taken from the Shakespearean play,
Antony and Cleopatra), and Ajax4jsf was born. In the fall of that same year, Smirnov joined Exadel, a
software engineering company, and continued to develop the framework. Smirnov’s goal was to create a
tool that was easy to use, would add client-side richness to pure server-side JSF technology, and could be
used with any existing JSF component libraries.
The first version of what would become Ajax4jsf was released in March 2006. It wasn’t quite a stand-
alone thing yet. Rather, it was part of a product called Exadel RichFaces. Later in the same year,

Before we end this chapter, we would like to offer some advice from our personal experience that
will help you become a better JSF and RichFaces developer.
Understanding That JSF Application Is Running on the Server
Based on our experience teaching JSF, it is sometimes difficult for people who are new to JSF to grasp the
idea behind the JSF component tree and how it relates to what they see in the browser. It’s important to
keep in mind that JSF is a server-side framework (thus the name JavaServer Faces). This means the
application is running on the server. This also means that any event processing will be done on the
server. Now, how does this all fit with what you see in the browser? The browser is basically a user-
readable view of the tree. It’s just a mirror image of the tree, but in a format (the browser) you can
understand. When building a JSF application, it might help to think you are always working with the JSF
component tree. Anything you change or invoke is always on the component tree, and the browser is
just a client for displaying pages.
You might be wondering, but what about Ajax? In the context of JSF, when using rich components,
they will render all the necessary JavaScript to send an Ajax request from the browser to the server. When
the request is done, JSF will render some components from the component tree and send that response
back to the browser. Upon receiving the response, JavaScript in the browser will do a DOM update (or
partial page update). Even though we now have rich components, Ajax JSF requests are still sent to the
server. To give you a little head start, there are also what’s called client-side events. These events happen
on the browser, such as expanding or collapsing a panel. In such case no request is sent to the server. We
will cover them in more detail later in the book.
www.it-ebooks.info
CHAPTER 1  THE BASICS

12
When Starting with JSF, Keep an Open Mind
It’s not difficult to find forums, blog posts, and other resources from people who are just starting with
JSF and are dissatisfied with the framework. You must remember that most people who are starting with
JSF are coming from JSP, Struts, or a similar homegrown framework. When they start evaluating JSF,
they bring the same style and development approach to JSF that they used with JSP and Struts. This is
where all the problems start.

Adding RichFaces to an Existing JSF 2 Project
Not to tie you to any specific IDE (integrated development environment), but we will use Apache
Maven to set up a project. Since RichFaces is built on top of JSF 2, its installation is as easy as adding a
few JARs to your project. Configure your repositories following the Maven Getting Started Guide located
on the JBoss Community web site at
Then, simply add Listing 2-1 to your projects pom.xml. Complete Maven guide can be found at:

Listing 2-1. Add this to your projects pom.xml
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.richfaces</groupId>
<artifactId>richfaces-bom</artifactId>
<version>${richfaces.version}</version>
<scope>import</scope>
<type>pom</type>
</dependency>
</dependencies>
</dependencyManagement>
…
<dependency>
<groupId>org.richfaces.ui</groupId>
<artifactId>richfaces-components-ui</artifactId>
www.it-ebooks.info
CHAPTER 2  GETTING STARTED

14
</dependency>
<dependency>
<groupId>org.richfaces.core</groupId>

</dependency>
www.it-ebooks.info
CHAPTER 2  GETTING STARTED

15
 Note
validation-api will be brought in transitively with hibernate-validator.
If deploying to a Java EE 6 server, then these libraries are not needed with the application because
they are included in the server. It’s still a good idea to include the dependency, but change the scope to
provided in order to use during the application build.
Caching Dependencies
For optimal performance it’s recommended to add one of the following caching frameworks to the
application classpath: Ehcache, JBoss Cache, or OSCache. When you create a new RichFaces project
with the RichFaces Maven archetype, Ehcache dependency is present in the pom.xml file, as shown in
Listing 2-3.
Listing 2-3. Create a new RichFaces project with the RichFaces Maven archetype
<dependency>
<groupId>net.sf.ehcache</groupId>
<artifactId>ehcache</artifactId>
</dependency>
CDK (Component Development Kit) Annotations Dependencies
Listing 2-4 shows compile time dependency. It is only needed if you are creating or accessing RichFaces
components instances in your application actions or listeners in order to define CDK annotations.
Listing 2-4. Shows compile time dependency
<dependency>
<groupId>org.richfaces.cdk</groupId>
<artifactId>annotations</artifactId>
<scope>provided</scope>
</dependency>
Creating a New Project with RichFaces

The project comes with a simple one-page application. Let’s deploy and run the project to make
sure everything works. If you open the readme.txt file, you will see the commands to build the
application for either a Tomcat or a JBoss 6 server.
 Tip If you want to try the latest snapshot version, change the version to 4.0.1-SNAPSHOT or 4.1.0-SNAPSHOT.
The Tomcat command is as follows:
mvn clean package
The following is a Tomcat and JBoss 6 command:
mvn clean package -P release
As you can see, creating a new RichFaces 4 project is very simple and you can easily open it in any
IDE that supports importing a Maven-based project. Even though it’s possible to use plain Eclipse (we
recommend Eclipse for Java EE Developer) there is one IDE that has the best RichFaces 4 support out
there, and that’s JBoss Tools or JBoss Developer Studio.
JBoss Tools is an open source and free set of plug-ins for Eclipse, which provides wizards, advanced
source and visual tools for building JSF 2 and RichFaces 4 applications. Additional features include
Seam, CDI, JPA, and Hibernate tools. You can download JBoss Tools from www.jboss.org/tools. As of
writing of this book, you would want to download JBoss Tools version 3.2 for Eclipse 3.6 (or the latest
version 3.3 for Eclipse 3.7).
You will also find instructions on how to install JBoss Tools. It’s rather simple: you will need to
download the latest supported Eclipse for Java EE developers and then point to the JBoss Tools plug-ins
URL in the Eclipse Install Software screen. Finally, you will need a servlet container such as Tomcat to
deploy the application. We recommend Tomcat 7.
If you would rather install everything from one file (Eclipse, JBoss Tools), then you can choose JBoss
Developer Studio. You can download JBoss Developer Studio from www.jboss.com/products/devstudio/.

www.it-ebooks.info
CHAPTER 2  GETTING STARTED

17
Once you set up Eclipse or Eclipse with JBoss Tools, there are two ways to import the Maven project
into Eclipse. One method is to execute the following command inside the project root folder:

• classic
www.it-ebooks.info
CHAPTER 2  GETTING STARTED
18
• deepMarine
• NULL
Ajax in JSF 2
JSF 2 comes with basic Ajax functionality built in. If you have used RichFaces 3, then you will see that JSF
2 Ajax was greatly inspired by the popular RichFaces <a4j:support> tag. You will see that the concepts
are the same, with a few things changed, such as attribute names. If you are new to RichFaces, don’t
worry, in this chapter we will cover everything from the beginning.
Ajax in JSF 2 comes in a form <f:ajax> behavior. Notice that we call it a behavior instead of a
component. A behavior is a new concept in JSF 2. A behavior in JSF 2 is a client-side behavior
(functionality) that is added to a component. Let’s see how to use the standard Ajax functionality in JSF 2
before we get to RichFaces.
When working with Ajax in the context of JSF, you need to keep three things in mind: First, how to
send an Ajax request; second, what to process on the server (partial view processing); and third, what to
render (partial view rendering).
Sending an Ajax Request
Sending an Ajax request is pretty straight forward: you really just have one option and that’s using
<f:ajax> behavior. This behavior is always attached to another UI component on a page; it’s never used
by itself. Listing 2-9 shows an example.
Listing 2-9. Sending an Ajax Request
<h:inputText value="#{bean.text}">
<f:ajax />
</h:inputText>
That’s pretty simple, right? We just added the ability to fire an Ajax request when the value inside the
input field changes. The Ajax request is fired from the client (browser) and always on some browser
event, such as click, change, and so forth. To be more precise, it can be any event supported by the
parent UI component. Components represent HTML elements in the browser, so it’s all the events that

look like in Listing 2-11 and work exactly the same way.
Listing 2-11. Specify the change event
<h:inputText value="#{bean.text}">
<f:ajax event="change"/>
</h:inputText>
Or we could use a different event, as shown in Listing 2-12.
Listing 2-12. Changing the default event
<h:inputText value="#{bean.text}">
<f:ajax event="keyup"/>
</h:inputText>
 Note If you are familiar with RichFaces 3, you specify the event with on [eventName], for example onchange.
In JSF 2 and RichFaces 4, you only specify the actual action: keyup.
If we were using a button, it would look like in Listing 2-13.
Listing 2-13. Example button
<h:commandButton value="Save">
<f:ajax/>
</h:commandButton>
We are not specifying the event, as it will default to click. If we wanted to specify a different event,
we would use the event attribute shown in Listing 2-14.
www.it-ebooks.info
CHAPTER 2  GETTING STARTED

20
Listing 2-14. Event attribute
<h:commandButton value="Save">
<f:ajax event="mouseover"/>
</h:commandButton>
Now that we covered the basics of firing an Ajax request, let’s add a very important part: partial
view rendering.
Partial View Rendering

render=":form2:text".
In the earlier example, we set render to one component. We can also decide to render more than
one component. In this case, we would just list the ids of all components, space separated, as follows:
<f:ajax event="keyup" render="id1 id2 id3"/>
In case you don’t want to list every single component, it’s possible to render just the parent
container, such as <h:panelGrid>. In this case, all its children components will also be rendered, as
shown in Listing 2-16.
Listing 2-16. Rendering all components inside a panel
<h:commandButton value="Save">
<f:ajax event="click" render="out"/>
</h:commandButton>
…
<h:panelGrid id="out">
<h:outputText />
<h:outputText />
</h:panelGrid>
In addition to the component id, render can also be set to a number of predefined values, as shown
in Table 2-3.
Table 2-3. Render attribute predefined values
Value Description
@all Render all the components in a view.
@none Render no components in view (this is also the default value if render is not specified).
@this Render only the component that fired the Ajax request.
@form Render all components inside the form.
id One or more ids of components to be rendered.
EL EL expression that resolves to ids from a Collection of strings.
Before we move on to partial view processing, there is one more thing we want to tell you. You will
hear people use the terms partial page update and partial view rendering interchangeably. That’s
absolutely fine, but it’s worth pointing out how they relate in the context of JSF.
www.it-ebooks.info