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 xvi Introduction We have been involved with JSF and RichFaces for many years now, including teaching JSF and RichFaces courses for many years. From our experience, we have come to realize that many developers are using RichFaces and JSF without understanding the full potential of the technology. Without this understanding, developers can't fully utilize the framework. Of course, after a bit of trial and error, almost everyone gets their application to work in some form. However, developers often don’t understand why their particular application works. And, more importantly, developers get frustrated and grow to dislike the technology. That's an important reason we wrote this second edition of Practical RichFaces—to raise the level of understanding in the developer community so this frustration can be avoided and so that RichFaces and JSF can be appreciated for the great technologies they are. This book is entirely based on the new and improved JSF 2 and covers the new and greatly improved RichFaces 4. We cover all the most important concepts, features, tags, and components available in RichFaces that you need to know—all in one place. While the book doesn’t try to cover every single attribute for every single component, that’s not really necessary. However, with the solid understanding of core concepts, features, and tags that you will get from this book, we guarantee you will be able to use any RichFaces component. Who Should Read This Book The book is for anyone with a basic knowledge of JSF who wants to learn how to build Ajax-based applications with RichFaces. If you are completely new to JSF, we recommend picking up a book on JSF 2. Even if you have been using RichFaces 4 (or RichFaces 3), this book will fill in many of the gaps. We are sure you will say at least once in the course of reading this book, “I didn’t know that was possible with RichFaces!” or “I didn’t know I could do that!” 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 built-in Ajax support, Ajax polling, and Ajax status. At this stage, however, it’s more interesting to look at examples of components from the rich: tag library. In Figure 1-1, you can see a rich tab panel and calendar components. www.it-ebooks.info CHAPTER 1  THE BASICS 2 Figure 1-1. RichFaces tab panel and calendar (blueSky skin) If you are reading an electronic version of this book, then Figure 1-1 will appear in light blue color. By changing just one parameter, we can render the page in the ruby skin, as shown in Figure 1-2. Another difference in Figure 1-2 is that it is also showing an optional control to select time. Each component offers a large number of customization options. Figure 1-2. RichFaces tab panel and calendar with time selection (ruby skin) The tabs can be switched via Ajax, as well as previous/next month in the calendar. Let’s look at one more rich component, shown in Figure 1-3. It shows a rich inplace input component displayed three times. Inplace input renders initially as a label (first component); when clicked, it switches to an input (second component); and then back to a label when editing is done (third component). www.it-ebooks.info CHAPTER 1  THE BASICS 3 Figure 1-3. Rich inplace input component (shown in three modes) We hope you now get an idea of what RichFaces can do. Trust us, it can do a whole lot more. We will now take a brief detour to tell you a little bit about JSF. Why? Well, RichFaces is a JSF frameworks, it is based entirely on JSF so it’s important to know how the underlying framework works. What is JSF? Let’s start with the simplest definition. JSF is just a framework for building web applications. To be a 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 applications. From the beginning, JSF was designed to be extended. Through standards, JSF allows you to extend the framework with new features and more advanced functionality. You are getting new functionality, but you are doing it in a standard and accepted way. One area that benefits most from this is the rich UI component ecosystem, which includes RichFaces. This eco-system is not limited to UI components—custom converters, validators, view handlers, and other extensions are created as well. The Most Important JSF Features JSF offers a long list of features. However, since this is not a dedicated JSF book, we will briefly cover the three most important features: user interface components, events, and the new Ajax functionality in JSF 2. If you feel you need to review your JSF skills, we recommend the following two books: Core JavaServer Faces, Third Edition by David Geary and Cay Horstmann (Prentice Hall, 2010) and JavaServer Faces 2.0, The Complete Reference by Ed Burns and Chris Schalk (McGraw-Hill, 2009).  Tip Two really great places to start learning JSF are http://javaserverfaces.org and http://jsfcentral.com. User Interface Components UI components are the main feature of the JSF framework. JSF ships with about 30 ready-to-use user interface components. Usually referred to as standard components, they provide basic user interface widgets for input, output, commands (buttons and links), labels, and layout, as well as simple controls to display tabular data. A number of utility components such as loading styles, scripts, and HTML page sections (head, body) are available as well. All JSF web applications are built out of components. A JSF UI component is a server-side Java object capable of processing input, firing actions, and rendering content. Component hierarchy is what JSF deals with. And tags are used for building that component tree. A JSF component can be as simple as an input field or as sophisticated as a tabbed panel or tree. For example, the following tag represents an input component: <h:inputText value="#{order.amount}"/> This is an input component that is bound (connected) to some Java object. You would place this tag on a JSF page instead of directly writing HTML code. The component behind the tag knows how to generate all the necessary and correct HTML, CSS, and JavaScript. Tags represent the server-side UI components and are used to build the JSF component tree shown in Figure 1-4. Component Rendering 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 6 As you can see, usually you won’t be working with HTML markup directly. You will simply use components that render the entire necessary markup. A note on rendering other markup languages. In the early days of JSF, the idea that components can render different markup based on client device was an interesting one. At that time, the mobile devices available usually worked with markup languages such as XML or WML. Today the situation is very different. Most modern mobiles devices, such as smart phones and tablets, come with powerful browsers supporting all the latest HTML, JavaScript, and CSS features. In some cases, the browser on a mobile device is better than the one on a PC. This means that generation markup other than HTML is no longer as important or has simply faded with the availability of mobile phones and other devices that support HTML. This doesn’t mean that renderers no longer play an important role. Even though HTML is now supported on various devices, renderers still play a role in regards to the kind of markup (HTML) that is generated. With the explosion of mobile devices, we now have to develop applications for a large number of different screen sizes. There is only so much “content” (or real estate) that can fit on a mobile phone with a 3.5-inch screen, or a tablet with a 7-inch screen, or even on a large laptop screen. This is exactly where renderers can help. Based on the device, screen size, and even screen resolution, the renderers can provide different markup. Events JSF takes you beyond the request/response paradigm and provides a powerful event-based model. The UI components that you use to build the user interface are sending events (when activated or clicked) to the server (browser events such as click are mapped to server-side component events). Listeners then process the events. For example, clicking a button (which is a UI component) is an event that is processed by an appropriate listener. (The JSF event-based model offers an approach to UI development similar to other user interface frameworks such as Swing and Flex.) For instance, in the #{simpleBean.save} expression defined in an action attribute, save is a method inside simpleBean bean. It is usually referred to as a JSF action and will be invoked when the button is clicked: <h:commandButton value="Submit" action="#{simpleBean.save}"/> Before we continue, you need to be familiar with the JSF life-cycle phases shown in Figure 1-5 and 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 [...]... RichFaces 4 version Client-side validation is only available starting with RichFaces 4 Table 1-1 summarizes JSF and RichFaces version compatibility Table 1-1 JSF and RichFaces Compatibility Matrix JSF 1.1 RichFaces 3.1.x JSF 1.2 JSF 2 X RichFaces 3.3.2 X RichFaces 3.3.3 X RichFaces 4 X (basic support) X RichFaces s Component Tag Libraries RichFaces components are divided into two tag libraries: one tag library... org .richfaces richfaces- bom $ {richfaces. version} import pom … org .richfaces. ui richfaces- components-ui www.it-ebooks.info 13 CHAPTER 2 GETTING STARTED org .richfaces. core... -DarchetypeGroupId=org .richfaces. archetypes -DarchetypeArtifactId =richfaces- archetype-simpleapp -DarchetypeVersion= -DgroupId= -DartifactId= www.it-ebooks.info 15 CHAPTER 2 GETTING STARTED Listing 2-6 shows actual code for generating a RichFaces project Listing 2-6 Generating a RichFaces project mvn archetype:generate \ -DarchetypeGroupId=org .richfaces. archetypes \ -DarchetypeArtifactId =richfaces- archetype-simpleapp... both have first class Maven support Configuring RichFaces There is nothing you actually need to do to configure RichFaces If you look inside the web.xml file in the generated project, you will see no mention of a RichFaces filter Starting with RichFaces 4, you don’t need to register a filter in the web.xml file If RichFaces JARs are present in the project, RichFaces will be used Configuring a Skin The... 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... org .richfaces. core richfaces- core-impl For other build systems, such as Ant, just add the following JARs to your projects WEB-INF/lib directory: • richfaces- core-api-.jar • richfaces- core-impl-.jar • richfaces- components-api-.jar • richfaces- components-ui-.jar • sac-1.3.jar • cssparser-0.9.5.jar • google-guava-r08.jar... 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. .. Fast-forward to March 2007 JBoss and Exadel forged a partnership where Ajax4jsf and RichFaces would be under the JBoss umbrella and called JBoss Ajax4jsf and JBoss RichFaces RichFaces would also be open source and free In September 2007, JBoss and Exadel decided to recombine Ajax4jsf and RichFaces under the RichFaces name This made sense because both libraries were free and open source Having just... 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 net.sf.ehcache ehcache ... 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 org .richfaces. cdk annotations provided Creating a New Project with RichFaces The RichFaces project also contains several Maven . 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. 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