RichFaces Developer Guide
RichFaces framework
with a huge library of
rich components and
skinnability support
iii
1. Introduction ................................................................................................................. 1
2. Technical Requirements .............................................................................................. 3
2.1. Supported Java Versions .................................................................................... 3
2.2. Supported JavaServer Faces Implementations and Frameworks ............................ 3
2.3. Supported Servers .............................................................................................. 3
2.4. Supported Browsers ............................................................................................ 4
3. Getting Started with RichFaces ................................................................................... 5
3.1. Downloading the RichFaces ................................................................................ 5
3.2. Simple JSF application with RichFaces ................................................................ 5
3.2.1. Adding RichFaces libraries into the project ................................................ 5
3.2.2. Registering RichFaces in web.xml ............................................................. 5
3.2.3. Managed bean ......................................................................................... 8
3.2.4. Registering bean in faces-cofig.xml ........................................................... 8
3.2.5. RichFaces Greeter index.jsp ..................................................................... 9
3.3. Relevant Resources Links ................................................................................. 10
4. Settings for different environments ........................................................................... 11
4.1. Web Application Descriptor Parameters .............................................................. 11
4.2. Sun JSF RI ...................................................................................................... 14
4.3. Apache MyFaces .............................................................................................. 15
4.4. Facelets Support ............................................................................................... 15
4.5. JBoss Seam Support ........................................................................................ 16
4.6. Portlet Support .................................................................................................. 19
4.7. Sybase EAServer .............................................................................................. 19
4.8. Oracle AS/OC4J ............................................................................................... 20
5. Basic concepts of the RichFaces Framework ............................................................ 21
5.1. Introduction ....................................................................................................... 21
5.2. RichFaces Architecture Overview ....................................................................... 22
5.3. RichFaces Integral Parts ................................................................................... 25
5.4. Limitations and Rules ........................................................................................ 26
5.5. Ajax Request Optimization ................................................................................ 26
5.5.1. Re-Rendering ......................................................................................... 26
5.5.2. Queue and Traffic Flood Protection ......................................................... 29
5.5.3. Queue Principles .................................................................................... 30
5.5.4. Data Processing Options ........................................................................ 35
5.5.5. Action and Navigation ............................................................................ 36
5.5.6. JavaScript Interactions ............................................................................ 36
5.5.7. Iteration components Ajax attributes ........................................................ 38
5.5.8. Other useful attributes ............................................................................ 38
5.6. How To... ......................................................................................................... 39
5.6.1. Send an Ajax request ............................................................................. 39
5.6.2. Decide What to Send ............................................................................. 40
5.6.3. Decide What to Change ......................................................................... 40
5.6.4. Decide what to process .......................................................................... 41
5.7. Filter Configuration ............................................................................................ 41
RichFaces Developer Guide
iv
5.8. Scripts and Styles Load Strategy ....................................................................... 44
5.9. Request Errors and Session Expiration Handling ................................................ 45
5.9.1. Request Errors Handling ......................................................................... 45
5.9.2. Session Expired Handling ....................................................................... 46
5.10. Skinnability ..................................................................................................... 47
5.10.1. Why Skinnability ................................................................................... 47
5.10.2. Using Skinnability ................................................................................. 47
5.10.3. Example .............................................................................................. 48
5.10.4. Skin Parameters Tables in RichFaces ................................................... 49
5.10.5. Creating and Using Your Own Skin File ................................................. 51
5.10.6. Built-in Skinnability in RichFaces ........................................................... 51
5.10.7. Standard Controls Skinning ................................................................... 52
5.10.8. Client-side Script for Extended Skinning Support .................................... 62
5.10.9. XCSS File Format ................................................................................ 63
5.10.10. Plug-n-Skin ........................................................................................ 64
5.11. State Manager API .......................................................................................... 71
6. The RichFaces Components ...................................................................................... 77
6.1. < a4j:ajaxListener > ......................................................................................... 77
6.1.1. Description ............................................................................................. 77
6.1.2. Creating on a page ................................................................................ 77
6.1.3. Creating the Component Dynamically Using Java ..................................... 77
6.1.4. Key attributes and ways of usage ........................................................... 78
6.1.5. Relevant resources links ......................................................................... 79
6.2. < a4j:keepAlive > ............................................................................................. 79
6.2.1. Description ............................................................................................. 79
6.2.2. Using the tag on a Page ........................................................................ 79
6.2.3. Key attributes and ways of usage ........................................................... 80
6.2.4. Relevant resources links ......................................................................... 80
6.3. < a4j:actionparam > ......................................................................................... 81
6.3.1. Description ............................................................................................. 81
6.3.2. Creating on a page ................................................................................ 81
6.3.3. Creating the Component Dynamically Using Java ..................................... 82
6.3.4. Key attributes and ways of usage ........................................................... 82
6.3.5. Relevant resources links ......................................................................... 83
6.4. < a4j:commandButton > ................................................................................... 83
6.4.1. Description ............................................................................................. 83
6.4.2. Creating on a page ................................................................................ 87
6.4.3. Creating the Component Dynamically Using Java ..................................... 87
6.4.4. Key attributes and ways of usage ........................................................... 87
6.4.5. Relevant resources links ......................................................................... 89
6.5. < a4j:commandLink > ...................................................................................... 89
6.5.1. Description ............................................................................................. 89
6.5.2. Creating on a page ................................................................................ 94
6.5.3. Creating the Component Dynamically Using Java ..................................... 94
v
6.5.4. Key attributes and ways of usage ........................................................... 94
6.5.5. Relevant resources links ......................................................................... 95
6.6. < a4j:form > .................................................................................................... 95
6.6.1. Description ............................................................................................. 95
6.6.2. Creating on a page ................................................................................ 98
6.6.3. Creating the Component Dynamically Using Java ..................................... 99
6.6.4. Key attributes and ways of usage ........................................................... 99
6.6.5. Relevant resources links ....................................................................... 100
6.7. < a4j:htmlCommandLink > .............................................................................. 100
6.7.1. Description ........................................................................................... 100
6.7.2. Creating the Component with a Page Tag .............................................. 103
6.7.3. Creating the Component Dynamically Using Java ................................... 103
6.7.4. Key attributes and ways of usage .......................................................... 104
6.7.5. Relevant resources links ....................................................................... 104
6.8. < a4j:jsFunction > .......................................................................................... 104
6.8.1. Description ........................................................................................... 104
6.8.2. Creating on a page .............................................................................. 107
6.8.3. Creating the Component Dynamically Using Java ................................... 107
6.8.4. Key attributes and ways of usage .......................................................... 108
6.8.5. Relevant resources links ....................................................................... 108
6.9. < a4j:include > ............................................................................................... 109
6.9.1. Description ........................................................................................... 109
6.9.2. Creating on a page .............................................................................. 110
6.9.3. Creating the Component Dynamically Using Java ................................... 111
6.9.4. Relevant resources links ....................................................................... 111
6.10. < a4j:loadBundle > ....................................................................................... 112
6.10.1. Description ......................................................................................... 112
6.10.2. Creating on a page ............................................................................. 112
6.10.3. Creating the Component Dynamically Using Java ................................. 112
6.10.4. Key attributes and ways of usage ........................................................ 113
6.10.5. Relevant resources links ..................................................................... 113
6.11. < a4j:loadScript > ......................................................................................... 113
6.11.1. Description ......................................................................................... 113
6.11.2. Creating on a page ............................................................................. 114
6.11.3. Creating the Component Dynamically Using Java ................................. 114
6.11.4. Key attributes and ways of usage ........................................................ 114
6.11.5. Relevant resources links ..................................................................... 114
6.12. < a4j:loadStyle > .......................................................................................... 115
6.12.1. Description ......................................................................................... 115
6.12.2. Creating on a page ............................................................................. 115
6.12.3. Creating the Component Dynamically Using Java ................................. 115
6.12.4. Key attributes and ways of usage ........................................................ 116
6.12.5. Relevant resources links ..................................................................... 116
6.13. < a4j:log > ................................................................................................... 116