JBoss RichFaces 3.3

Table of Contents

JBoss RichFaces 3.3

Credits

About the Author

About the Reviewer

Preface

What this book covers

Who this book is for

Conventions

Reader feedback

Customer support

Errata

Piracy

Questions

1. What is RichFaces?

An overview of RichFaces

A bit of history

The Ajax framework

Ajax Action Components

Ajax Containers

Ajax placeholders

Ajax validators

RichFaces components overview

RichFaces skinnability overview

Summary

2. Getting Ready

Creating a RichFaces JSF project the simple way

Seam-gen

Download and install seam-gen

Generating a project using seam-gen

Update RichFaces libraries in a seam-gen generated project

Overview of the project structure

Incremental hot deployment

Seam and Facelets support

Adding RichFaces manually to your existing JSF project

Downloading RichFaces

Basic configuration

Where to put the libraries

Registering RichFaces

Facelets support

IDEs

Eclipse/JBoss Tools

Where to download and how to install it

JBoss Developer Studio

Importing a seam-gen generated project into Eclipse

IntelliJ Idea

Where to download and how to install it

Summary

3. First Steps

A simple contact manager

Creating the new project

Templating and Facelets

Modifying the created project

The model

The managed bean

Making it a managed bean

The Insert new contact form

The main box

The form fields

Using RichFaces message and messages components instead of the standard ones

Validating our field in a simple way

Adding Ajax to standard JSF components: a4j:support

Calendar field

Simple layout components: rich:separator and rich:spacer

Ajax command buttons: a4j:commandButton

Ajax command links: a4j:commandLink

The contact list

Re-rendering the contact list after adding a new contact

Adding the delete button

Summary

4. The Application

What we are going to develop?

Features

Groups manager

File uploads and notes

Simple search

User skin

Multilanguage

The database: E-R diagram

Importing the database

Creating the project

The class diagram

Some modification to the entities

Editing the template page

The menu page

The login page

The home page

Summary

5. Making the Application Structure

Skinnability and dynamic skin change

Selecting the application skin

User-selected application skin

Passing application parameters using components.xml

Making skin selection user-dependent

Standard controls skinning

XCSS and Plug-n-Skin

Adding built-in plug'n'skin skins

Some examples

Internationalization

Configuration

Internationalize strings

User-selected language

Persist the selected locale using a cookie

Menu bar using rich:toolBar component

Making the login work

User registration

Creating the page structure

Creating the support bean

Creating the form fields and action buttons

Adding the validation rules

Adding the sign up link to the menu bar

Validating the password against another Rewrite password field

Making your own validators

Using a captcha

Resetting the captcha

Automatic login after registration

Sending the confirmation emails

Screenshot

Reset password box

Forgot username box

URL rewriting: making it simple and powerful

Summary

6. Making the Contacts List and Detail

The main layout

Ajax placeholders

The groups box

The contacts list

Differences between h:dataTable and rich:dataTable

Data pagination

Adding the column headers

Columns and column groups

Out-of-the-box filtering and sorting

The bottom toolbar

The backing bean

The contact detail

The support bean

Selecting the contact from the contacts list

Adding a new contact

Viewing contact detail

Editing contact detail

The button toolbar

The ajaxSingle and the process attributes

More Ajax!

Ajax containers

Data iteration using RichFaces

Data pagination with data iteration components

Addresses management

Some screenshots

Summary

7. Finishing the Application

Taking a note of every contact

A richer editor

Let's group our contacts

Listing, adding, and removing groups

Other features of the rich:toolTip component

Adding and editing groups

The adding/editing form

Adding contacts to a group using the drag 'n' drop

Removing contacts from a group using drag'n'drop

Attaching files

Creating the wizard

The file review step

Creating the modal panel

Control components without JavaScript

Inserting the wizard inside the modal panel

Finishing the file upload feature

Summary

8. Skin Customization

Skinnability

Customize skin parameters

Edit a basic skin

Using CSS

Redefine the skin-inserted CSS classes

Specify our specific CSS classes

Using skins with non-skinnable components

Standard controls skinning

XCSS

Summary

9. Creating a New plug 'n' skin

Installing Maven

Creating the new skin

Customizing the new skin

Packaging and deploying the new skin

Summary

10. Advanced Techniques

Poll

Creating images dynamically

Push

Creating a RichFaces JavaScript function

Partial update of data iteration components

RichFaces component binding in JBoss Seam / JBoss Application Server environment

Moving all the libraries to the EAR

A simple binding example

The tree component

State saving

Action listeners

Controlling the session expiration

Summary

11. Component Development Kit

Configuring the environment

Installing Maven

Configuring

Creating the project

Generating the template

Testing the template

Creating the component

Component configuration

Component resources

Component renderer

Testing the new component

Summary

A. RichFaces Components Overview

Ajax sup0port

a4j:ajaxListener

a4j:actionparam

a4j:commandButton

a4j:commandLink

a4j:form

a4j:htmlCommandLink

a4j:jsFunction

a4j:poll

a4j:push

a4j:region

a4j:status

a4j:support

Resources/beans handling

a4j:keepAlive

a4j:loadBundle

a4j:loadScript

a4j:loadStyle

Ajax Validators

rich:ajaxValidator

rich:graphValidator

rich:beanValidator

Ajax output

a4j:include

a4j:mediaOutput

a4j:outputPanel

Ajax miscellaneous

a4j:log

a4j:page

a4j:portlet

Data iteration

a4j:repeat

rich:columns

rich:columnGroup

rich:column

rich:dataGrid

rich:dataList

rich:dataOrderedList

rich:dataDefinitionList

rich:dataFilterSlider

rich:datascroller

rich:dataTable

rich:subTable

rich:extendedDataTable

rich:scrollableDataTable

Drag-and-drop support

rich:dndParam

rich:dragIndicator

rich:dragSupport

rich:dropSupport

rich:dragListener

rich:dropListener

Rich Menu

rich:contextMenu

rich:dropDownMenu

rich:menuGroup

rich:menuItem

rich:menuSeparator

Rich trees

rich:tree

rich:treeNode

rich:changeExpandListener

rich:nodeSelectListener

rich:recursiveTreeNodesAdaptor

rich:treeNodesAdaptor

Rich output

rich:modalPanel

rich:paint2D

rich:panel

rich:panelBar

rich:panelBarItem

rich:panelMenu

rich:panelMenuGroup

rich:panelMenuItem

rich:progressBar

rich:separator

rich:simpleTogglePanel

rich:spacer

rich:tabPanel

rich:tab

rich:togglePanel

rich:toggleControl

rich:toolBar

rich:toolBarGroup

rich:toolTip

Rich input

rich:calendar

rich:comboBox

rich:fileUpload

rich:inplaceInput

rich:inplaceSelect

rich:inputNumberSlider

rich:inputNumberSpinner

rich:suggestionbox

Rich Selects

rich:listShuttle

rich:orderingList

rich:pickList

Rich miscellaneous

rich:componentControl

rich:effect

rich:gmap

rich:virtualEarth

rich:hotKey

rich:insert

rich:jQuery

rich:message

rich:messages

JSF 2 and RichFaces 4

RichFaces 3.3.X

JSF 2.0

RichFaces 4.X

Index

JBoss RichFaces 3.3

Demetrio Filocamo

JBoss RichFaces 3.3

Copyright © 2009 Packt Publishing

All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews.

Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the author, nor Packt Publishing, and its dealers and distributors will be held liable for any damages caused or alleged to be caused directly or indirectly by this book.

Packt Publishing has endeavored to provide trademark information about all of the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information.

First published: November 2009

Production Reference: 1231009

Published by Packt Publishing Ltd.

32 Lincoln Road

Olton

Birmingham, B27 6PA, UK.

ISBN 978-1-847196-88-0

www.packtpub.com

Cover Image by Filippo (<[email protected]>)

Credits

Author

Demetrio Filocamo

Reviewer

Allan Lykke Christensen

Acquisition Editor

Sarah Cullington

Development Editor

Swapna V. Verlekar

Technical Editor

Charumathi Sankaran

Copy Editor

Sanchari Mukherjee

Indexers

Rekha Nair

Monica Ajmera

Editorial Team Leader

Gagandeep Singh

Project Team Leader

Lata Basantani

Project Coordinator

Srimoyee Ghoshal

Proofreader

Lynda Sliwoski

Graphics

Nilesh R. Mohite

Production Coordinators

Adline Swetha Jesuthas

Dolly Dasilva

Cover Work

Adline Swetha Jesuthas

About the Author

Demetrio Filocamo is a computer science engineer with more than 10 years of experience with both Desktop and web applications development. He works as a consultant in London and collaborates with some companies and universities in Italy. Demetrio has been developing Enterprise Java Applications using open source solutions for the last five years.

About the Reviewer

Allan Lykke Christensen is the vice-president of Danish ICT Management, an international consulting firm with its focus on ICT in developing economies. He is responsible for daily management of teams in Uganda, Bangladesh, and Denmark. In his daily work, he is also responsible for project planning, initiating, and overall implementation. He has been developing and implementing IT projects for more than 10 years. His expertise covers a wide range—he has developed workflow systems, information systems, e-learning tools, knowledge management systems, and websites. He has worked as a team leader on several major European Commission-financed ICT projects in various developing economies. He has co-authored The Definitive Guide to Apache MyFaces and Facelets (Apress, 2008) and made countless presentations and training sessions on programming-related topics around the world.

To my grandfather Demetrio, my family and Maria Chiara.

Preface

JBoss RichFaces is a rich component library for JavaServer Faces and an AJAX framework that allows easy integration of Ajax capabilities into complex business applications. Do you wish to eliminate the time involved in writing JavaScript code and managing JavaScript-compatibility between browsers to build an Ajax web application quickly?

This book goes beyond the documentation to teach you how to do that. It will show you how to get the most out of JBoss RichFaces by explaining the key components and how you can use them to enhance your applications. Most importantly, you will learn how to integrate Ajax into your applications without using JavaScript, but only standard JSF components. You will learn how to create and customize your own components and add them to your new or existing applications.

First, the book introduces you to JBoss RichFaces and its components. It uses many examples of Ajax components which, among others, include: Calendar, Data Table, ToolTip, ToolBar, Menu, RichEditor, and Drag 'n' Drop. All these components will help you create the web site you always imagined. Key aspects of the RichFaces framework such as the Ajax framework, skinnability, and Component Development Kit (CDK) will help you customize the look of your web application. As you progress through the book, you will see a sample application that shows you how to build an advanced contact manager. You're also going to be amazed to know about the advanced topics you will learn such as developing new components, new skins, optimizing a web application, inserting components dynamically using Java instead of XHTML, and using JavaScript to manage components. This book is more than a reference with component example code: it's a manual that will guide you, step by step, through the development of a real Ajax JSF web application.

What this book covers

Chapter 1: What is RichFaces covers the aims of the RichFaces framework, its components, and what you can do by using it in a web application.

Chapter 2: Getting Ready explains how to configure your environment by creating a simple project using the seam-gen tool, adding support to Seam and Facelets, and the manual configuration for the RichFaces libraries. We will understand the IDE that we can use while developing with the framework.

In Chapter 3: First Steps, you will learn to build Ajax applications by developing a simple example, the basics of RichFaces step by step, from creating the project to editing the code, using very important components and their Ajax properties.

Chapter 4: The Application covers how to create the basics of our project by having a look at the side technologies we might know, in order to build good applications. It will cover templating with Facelets, JBoss Seam authentication, and customization of the entities.

Chapter 5: Making the Application Structure explains us how to create the login and registration system of the website. We'll look at all the features that a real application might have.

In Chapter 6: Making the Contacts List and Detail, we will develop the core feature of our application—contact management. We'll learn about Ajax interaction and containers, and about new Ajax components that RichFaces offers.

Chapter 7: Finishing the Application explains how to finish building the application using the RichFaces components, and about customizing them.

In Chapter 8: Skin Customization, we'll see all the powerful customization capabilities that the RichFaces framework offers.

Chapter 9: Creating a New plug 'n' skin covers how to create, customize, and package and deploy a new pluggable skin.

Chapter 10: Advanced Techniques explains you how to use and implement pushing, partial updates, and session expiration handling in order to develop advanced applications.

In Chapter 11: Component Development Kit, we'll see how to start a project in order to develop a simple JSF Ajax component in a simple and effective way using the features the CDK offers.

Appendix: RichFaces Components Overview covers a list of all the components of RichFaces with their functionalities.

Who this book is for

This book targets Java Developers who want to enhance their JSF applications by adding AJAX, but without having to use JavaScript. If you want to learn how to use the wide set of AJAX components that you find in the RichFaces framework, this book is for you.

You are expected to have basic knowledge of JSF, but no previous experience with AJAX is necessary.

Conventions

In this book, you will find a number of styles of text that distinguish between different kinds of information. Here are some examples of these styles, and an explanation of their meaning.

Code words in text are shown as follows: Notice that the myNewSkin.skin.properties file contains the properties of the skin.

A block of code is set as follows:

    Float ratingValue =

        (Float) component.getAttributes().get(value);

    variables.setVariable(ratingValue, ratingValue);

]]>

When we wish to draw your attention to a particular part of a code block, the relevant lines or items are set in bold:

org.richfaces.renderkit.html.CustomizeableGradient>

    valign value=middle />

    gradientHeight

                value=22px />

    baseColor

                skin=myNewProperty />

    gradientColor

                skin=headerGradientColor />

Any command-line input or output is written as follows:

mvn install

New terms and important words are shown in bold. Words that you see on the screen, in menus or dialog boxes for example, appear in the text like this: clicking the Next button moves you to the next screen.

Note

Warnings or important notes appear in a box like this.

Tip

Tips and tricks appear like this.

Reader feedback

Feedback from our readers is always welcome. Let us know what you think about this book—what you liked or may have disliked. Reader feedback is important for us to develop titles that you really get the most out of.

To send us general feedback, simply send an email to <[email protected]>, and mention the book title via the subject of your message.

If there is a book that you need and would like to see us publish, please send us a note in the SUGGEST A TITLE form on www.packtpub.com or email .

If there is a topic that you have expertise in and you are interested in either writing or contributing to a book on, see our author guide on www.packtpub.com/authors.

Customer support

Now that you are the proud owner of a Packt book, we have a number of things to help you to get the most from your purchase.

Note

Downloading the example code for the book

Visit http://www.packtpub.com/files/code/6880_Code.zip to directly download the example code

The downloadable files contain instructions on how to use them.

Errata

Although we have taken every care to ensure the accuracy of our content, mistakes do happen. If you find a mistake in one of our books—maybe a mistake in the text or the code—we would be grateful if you would report this to us. By doing so, you can save other readers from frustration, and help us to improve subsequent versions of this book. If you find any errata, please report them by visiting http://www.packtpub.com/support, selecting your book, clicking on the let us know link, and entering the details of your errata. Once your errata are verified, your submission will be accepted and the errata added to any list of existing errata. Any existing errata can be viewed by selecting your title from http://www.packtpub.com/support.

Piracy

Piracy of copyright material on the Internet is an ongoing problem across all media. At Packt, we take the protection of our copyright and licenses very seriously. If you come across any illegal copies of our works, in any form, on the Internet, please provide us with the location address or web site name immediately so that we can pursue a remedy.

Please contact us at <[email protected]> with a link to the suspected pirated material.

We appreciate your help in protecting our authors, and our ability to bring you valuable content.

Questions

You can contact us at <[email protected]> if you are having a problem with any aspect of the book, and we will do our best to address it.

Chapter 1. What is RichFaces?

In this chapter, we are going to learn about the RichFaces project and how it can help us develop better Ajax web applications faster.

First, we'll go through a bit of the story of its birth and growth. Thereafter, we'll learn how it works (in general), which components are inside its framework, and what we can do with them. Finally, we'll explain some advanced techniques and start looking at the CDK (Component Development Kit) with a simple example.

An overview of RichFaces

RichFaces is a very useful open source framework that allows you to add Ajax capability to your JSF application (using the standard JSF components) without the need to write JavaScript code and manage JavaScript compatibility between browsers. It is integrated with the JSF lifecycle and other standard JSF features such as validation, conversion, and resource management.

Moreover, RichFaces offers the very powerful skinnability. This customizes the look and feel of your JSF applications. You can define different color schemes to create your custom skins or use the predefined ones. Also, you can manage the predefined CSS styles (or add your own ones) to change the appearance of UI library components in a simple and consistent way (you can even use XCSS to dynamically customize the CSS styles). The skinnability feature of RichFaces can apply skins to standard HTML elements such as input, select, textarea, fieldset, and so on.

RichFaces provides two sets of component libraries:

Core Ajax: The Core library contains components that are useful to ajaxize JSF pages and standard JSF components. It is very simple to define Ajax areas and to invoke Ajax requests in order to update those areas (we'll see how this is done very soon). Also, it provides a component to generate binary resources on the fly (for example, code-generated images, pdf files, csv files, and so on).

UI: The RichFaces UI library is a set of advanced JSF Ajax components used to add rich user interface features to your applications. The components support Ajax out of the box and perfectly integrate with the Core library. Also, they fully support skins and can be completely adapted according to the users' needs.

Another feature included in the RichFaces framework is the Component Development Kit (CDK)—the set of tools used for UI library creation that can be used to make new components with built-in Ajax and skinnability support.

Other extras are the Facelets support, the possibility to create components from Java code (with documented API), the JavaScript API of components to interact with them from the client side (if you want to use JavaScript), and last but not least, the very strong community support.

As you can see, RichFaces has a lot of very powerful features that can help you with rich application development. In the following