Web UI Developer’s Guide For Oracle Application Development Framework

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 1140 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Oracle® Fusion Middleware
Web User Interface Developer’s Guide for Oracle Application
Development Framework
11g Release 2 (11.1.2.1.0)
E16181-02
September 2011
Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development
Framework 11g Release 2 (11.1.2.1.0)
E16181-02
Copyright © 2011, Oracle and/or its affiliates. All rights reserved.
Primary Authors: Robin Whitmore (lead), Walter Egan, Ralph Gordon, Peter Jew, Himanshu Marathe,
Kathryn Munn, Michele Whittaker
Contributing Author: Poh Lee Tan and Odile Sullivan-Tarazi
Contributors: ADF Faces development team, Frank Nimphius, Laura Akel, Katia Obradovic-Sarkic
This software and related documentation are provided under a license agreement containing restrictions on
use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your
license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license,
transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse
engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is
prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If
you find any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it
on behalf of the U.S. Government, the following notice is applicable:
U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data
delivered to U.S. Government customers are "commercial computer software" or "commercial technical data"
pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As
such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and
license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of
the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software
License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065.
This software or hardware is developed for general use in a variety of information management
applications. It is not developed or intended for use in any inherently dangerous applications, including
applications that may create a risk of personal injury. If you use this software or hardware in dangerous
applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other
measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages
caused by use of this software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of
their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks
are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD,
Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced
Micro Devices. UNIX is a registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information on content, products,
and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly
disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle
Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your
access to or use of third-party content, products, or services.
iii
Contents
Preface ............................................................................................................................................................ xxvii
Audience.................................................................................................................................................. xxvii
Documentation Accessibility................................................................................................................ xxvii
Related Documents ................................................................................................................................ xxvii
Conventions ........................................................................................................................................... xxviii
What's New in This Guide for Release 11.1.2.1.0 .................................................................. xxix
Part I Getting Started with ADF Faces
1 Introduction to ADF Faces
1.1 About Oracle ADF Faces ........................................................................................................... 1-1
1.2 ADF Faces Framework............................................................................................................... 1-1
1.3 ADF Faces Components............................................................................................................. 1-4
2 ADF Faces Demo Application
2.1 About the ADF Faces Demonstration Application................................................................ 2-1
2.2 Downloading and Installing the ADF Faces Demo Application ...................................... 2-10
3 Getting Started with ADF Faces and JDeveloper
3.1 About Developing Declaratively in JDeveloper..................................................................... 3-1
3.2 Creating an Application Workspace........................................................................................ 3-2
3.2.1 How to Create an ADF Faces Application Workspace .................................................. 3-2
3.2.2 What Happens When You Create an Application Workspace..................................... 3-3
3.3 Defining Page Flows................................................................................................................... 3-4
3.3.1 How to Define a Page Flow................................................................................................ 3-5
3.3.2 What Happens When You Use the Diagrammer to Create a Page Flow .................... 3-6
3.4 Creating a View Page ................................................................................................................. 3-6
3.4.1 How to Create JSF Pages .................................................................................................... 3-9
3.4.2 What Happens When You Create a JSF Page.................................................................. 3-9
3.4.3 What You May Need to Know About Updating Your Application to Use the Facelets
Engine 3-14
3.4.4 What You May Need to Know About Automatic Component Binding .................. 3-15
3.4.5 How to Add ADF Faces Components to JSF Pages..................................................... 3-19
iv
3.4.6 What Happens When You Add Components to a Page............................................. 3-21
3.4.7 How to Set Component Attributes................................................................................. 3-22
3.4.8 What Happens When You Use the Property Inspector .............................................. 3-24
3.5 Creating EL Expressions......................................................................................................... 3-24
3.5.1 How to Create an EL Expression.................................................................................... 3-25
3.5.2 How to Use the EL Format Tags..................................................................................... 3-27
3.5.3 How to Use EL Expressions Within Managed Beans.................................................. 3-28
3.6 Creating and Using Managed Beans..................................................................................... 3-29
3.6.1 How to Create a Managed Bean in JDeveloper............................................................ 3-29
3.6.2 What Happens When You Use JDeveloper to Create a Managed Bean................... 3-31
3.6.3 What You May Need to Know About Component Bindings and Managed Beans 3-31
3.7 Viewing ADF Faces Javadoc .................................................................................................. 3-32
3.7.1 How to View ADF Faces Source Code and Javadoc ................................................... 3-32
Part II Understanding ADF Faces Architecture
4 Using ADF Faces Client-Side Architecture
4.1 About Using ADF Faces Architecture...................................................................................... 4-1
4.2 Listening for Client Events ........................................................................................................ 4-3
4.2.1 How to Listen for Client Events ........................................................................................ 4-3
4.3 Adding JavaScript to a Page...................................................................................................... 4-4
4.3.1 How to Use Inline JavaScript............................................................................................. 4-4
4.3.2 How to Import JavaScript Libraries.................................................................................. 4-5
4.3.3 What You May Need to Know About Accessing Client Event Sources...................... 4-6
4.4 Instantiating Client-Side Components..................................................................................... 4-6
4.4.1 How to Configure a Component to for a Client-Side Instance..................................... 4-6
4.4.2 What Happens When You Set clientComponent to true............................................... 4-7
4.5 Locating a Client Component on a Page ................................................................................. 4-7
4.5.1 What You May Need to Know About Finding Components in Naming Containers .......
4-8
4.6 Accessing Component Properties on the Client..................................................................... 4-9
4.6.1 How to Set Property Values on the Client .................................................................... 4-13
4.6.2 What You May Need to Know About Setting Properties on the Client................... 4-14
4.6.3 How to Unsecure the disabled Property....................................................................... 4-17
4.6.4 What Happens at Runtime: How Client Properties Are Set on the Client............... 4-18
4.7 Using Bonus Attributes for Client-Side Components ........................................................ 4-18
4.7.1 How to Create Bonus Attributes .................................................................................... 4-18
4.7.2 What You May Need to Know About Marshalling Bonus Attributes...................... 4-19
4.8 Understanding Rendering and Visibility............................................................................. 4-19
4.8.1 How to Set Visibility Using JavaScript.......................................................................... 4-21
4.8.2 What You May Need to Know About Visible and the isShowing Function............ 4-22
4.9 JavaScript Library Partitioning .............................................................................................. 4-22
4.9.1 How to Create a JavaScript Feature ............................................................................... 4-23
4.9.2 How to Create JavaScript Partitions .............................................................................. 4-24
4.9.3 What Happens at Runtime: JavaScript Partitioning.................................................... 4-26
v
5 Using the JSF Lifecycle with ADF Faces
5.1 About Using the JSF Lifecycle and ADF Faces....................................................................... 5-1
5.2 Using the Immediate Attribute................................................................................................. 5-4
5.2.1 How to Use the Immediate Attribute ............................................................................... 5-9
5.3 Using the Optimized Lifecycle.................................................................................................. 5-9
5.3.1 What You May Need to Know About Using the Immediate Attribute and the
Optimized Lifecycle 5-10
5.3.2 What You May Need to Know About Using an LOV Component and the Optimized
Lifecycle 5-11
5.4 Using the Client-Side Lifecycle.............................................................................................. 5-14
5.5 Using Subforms to Create Sections on a Page ..................................................................... 5-15
5.6 Object Scope Lifecycles ........................................................................................................... 5-15
5.7 Passing Values Between Pages .............................................................................................. 5-17
5.7.1 How to Use the pageFlowScope Scope Within Java Code ......................................... 5-18
5.7.2 How to Use the pageFlowScope Scope Without Writing Java Code........................ 5-19
5.7.3 What Happens at Runtime: How Values are Passed .................................................. 5-20
6 Handling Events
6.1 About Events and Event Handling .......................................................................................... 6-1
6.1.1 Events and Partial Page Rendering................................................................................... 6-2
6.1.2 Client-Side Event Model..................................................................................................... 6-3
6.2 Using ADF Faces Server Events................................................................................................ 6-3
6.2.1 How to Handle Server-Side Events .................................................................................. 6-5
6.3 Using JavaScript for ADF Faces Client Events ....................................................................... 6-6
6.3.1 How to Use Client-Side Events....................................................................................... 6-10
6.3.2 How to Return the Original Source of the Event......................................................... 6-12
6.3.3 How to Use Client-Side Attributes for an Event.......................................................... 6-13
6.3.4 How to Block UI Input During Event Execution ......................................................... 6-13
6.3.5 How to Prevent Events from Propagating to the Server ............................................ 6-14
6.3.6 How to Indicate No Response is Expected................................................................... 6-14
6.3.7 What Happens at Runtime: How Client-Side Events Work ...................................... 6-15
6.3.8 What You May Need to Know About Using Naming Containers............................ 6-15
6.4 Sending Custom Events from the Client to the Server....................................................... 6-16
6.4.1 How to Send Custom Events from the Client to the Server....................................... 6-17
6.4.2 What Happens at Runtime: How Client and Server Listeners Work Together ...... 6-18
6.4.3 What You May Need to Know About Marshalling and Unmarshalling Data........ 6-19
6.5 Executing a Script Within an Event Response..................................................................... 6-21
6.6 Using ADF Faces Client Behavior Tags................................................................................ 6-22
6.6.1 How to Use the scrollComponentIntoViewBehavior Tag.......................................... 6-23
6.7 Using Polling Events to Update Pages ................................................................................. 6-24
6.7.1 How to Use the Poll Component.................................................................................... 6-25
7 Validating and Converting Input
7.1 About ADF Faces Converters and Validators ........................................................................ 7-1
7.1.1 ADF Faces Converters and Validators Use Cases and Examples................................. 7-2
7.1.2 Additional Functionality for ADF Faces Converters and Validators .......................... 7-2
vi
7.2 Conversion, Validation, and the JSF Lifecycle........................................................................ 7-2
7.3 Adding Conversion .................................................................................................................... 7-3
7.3.1 How to Add a Converter.................................................................................................... 7-4
7.3.2 How to Set Attributes on a Converter .............................................................................. 7-5
7.3.3 What Happens at Runtime................................................................................................. 7-6
7.4 Creating Custom JSF Converters.............................................................................................. 7-6
7.4.1 How to Create a Custom JSF Converter........................................................................... 7-6
7.4.2 What Happens When You Use a Custom Converter .................................................. 7-10
7.5 Adding Validation ................................................................................................................... 7-10
7.5.1 How to Add Validation ................................................................................................... 7-11
7.5.1.1 Adding ADF Faces Validation................................................................................. 7-11
7.5.1.2 Using Validation Attributes..................................................................................... 7-11
7.5.1.3 Using ADF Faces Validators .................................................................................... 7-12
7.5.2 What Happens at Runtime.............................................................................................. 7-13
7.5.3 What You May Need to Know About Multiple Validators........................................ 7-13
7.6 Creating Custom JSF Validation............................................................................................ 7-14
7.6.1 How to Create a Backing Bean Validation Method..................................................... 7-14
7.6.2 What Happens When You Create a Backing Bean Validation Method.................... 7-15
7.6.3 How to Create a Custom JSF Validator......................................................................... 7-15
7.6.4 What Happens When You Use a Custom JSF Validator............................................. 7-17
8 Rerendering Partial Page Content
8.1 About Partial Page Rendering .................................................................................................. 8-1
8.2 Enabling Partial Page Rendering Declaratively ..................................................................... 8-2
8.2.1 How to Enable Partial Page Rendering ............................................................................ 8-4
8.2.2 What You May Need to Know About Using the Browser Back Button...................... 8-6
8.2.3 What You May Need to Know About PPR and Screen Readers .................................. 8-6
8.3 Enabling Partial Page Rendering Programmatically............................................................. 8-6
8.3.1 How to Enable Partial Page Rendering Programmatically ........................................... 8-6
8.4 Using Partial Page Navigation.................................................................................................. 8-7
8.4.1 How to Use Partial Page Navigation................................................................................ 8-8
8.4.2 What You May Need to Know About PPR Navigation................................................. 8-8
Part III Creating Your Layout
9 Organizing Content on Web Pages
9.1 About Organizing Content on Web Pages.............................................................................. 9-1
9.1.1 Additional Functionality for Layout Components......................................................... 9-4
9.2 Starting to Lay Out a Page......................................................................................................... 9-5
9.2.1 Geometry Management and Component Stretching ..................................................... 9-6
9.2.2 Nesting Components Inside Components That Allow Stretching............................... 9-8
9.2.3 Using Quick Start Layouts .............................................................................................. 9-10
9.2.4 Tips for Using Geometry-Managed Components ....................................................... 9-11
9.2.5 How to Configure the document Tag............................................................................ 9-12
9.3 Arranging Contents to Stretch Across a Page...................................................................... 9-15
9.3.1 How to Use the panelStretchLayout Component........................................................ 9-16
vii
9.3.2 What You May Need to Know About Geometry Management and the
panelStretchLayout Component 9-19
9.4 Using Splitters to Create Resizable Panes ............................................................................ 9-20
9.4.1 How to Use the panelSplitter Component.................................................................... 9-21
9.4.2 What You May Need to Know About Geometry Management and the panelSplitter
Component 9-25
9.5 Arranging Page Contents in Predefined Fixed Areas ........................................................ 9-26
9.5.1 How to Use the panelBorderLayout Component to Arrange Page Contents in
Predefined Fixed Areas 9-27
9.6 Arranging Content in Forms.................................................................................................. 9-28
9.6.1 How to Use the panelFormLayout Component........................................................... 9-30
9.6.2 What You May Need to Know About Using the group Component with the
panelFormLayout Component 9-34
9.7 Arranging Contents in a Dashboard..................................................................................... 9-38
9.7.1 How to Use the panelDashboard Component ............................................................. 9-41
9.7.2 What You May Need to Know About Geometry Management and the panelDashboard
Component 9-44
9.8 Displaying and Hiding Contents Dynamically................................................................... 9-44
9.8.1 How to Use the showDetail Component ...................................................................... 9-49
9.8.2 How to Use the showDetailHeader Component ......................................................... 9-50
9.8.3 How to Use the panelBox Component .......................................................................... 9-53
9.8.4 What You May Need to Know About Disclosure Events........................................... 9-54
9.9 Displaying or Hiding Contents in Accordion Panels and Tabbed Panels....................... 9-56
9.9.1 How to Use the panelAccordion Component .............................................................. 9-60
9.9.2 How to Use the panelTabbed Component.................................................................... 9-62
9.9.3 How to Use the showDetailItem Component to Display Content in panelAccordion or
panelTabbed Components 9-63
9.9.4 What You May Need to Know About Geometry Management and the showDetailItem
Component 9-67
9.9.5 What You May Need to Know About showDetailItem Disclosure Events ............. 9-68
9.10 Displaying Items in a Static Box ............................................................................................ 9-69
9.10.1 How to Use the panelHeader Component.................................................................... 9-72
9.10.2 How to Use the decorativeBox Component ................................................................. 9-74
9.10.3 What You May Need to Know About Geometry Management and the decorativeBox
Component 9-75
9.11 Displaying a Bulleted List in One or More Columns ......................................................... 9-76
9.11.1 How to Use the panelList Component .......................................................................... 9-77
9.11.2 What You May Need to Know About Creating a List Hierarchy ............................. 9-78
9.12 Grouping Related Items.......................................................................................................... 9-79
9.12.1 How to Use the panelGroupLayout Component......................................................... 9-81
9.12.2 What You May Need to Know About Geometry Management and the
panelGroupLayout Component 9-83
9.13 Separating Content Using Blank Space or Lines................................................................. 9-83
9.13.1 How to Use the spacer Component ............................................................................... 9-84
9.13.2 How to Use the Separator Component.......................................................................... 9-85
10 Creating and Reusing Fragments, Page Templates, and Components
10.1 About Reusable Content......................................................................................................... 10-1
viii
10.1.1 Reusable Components Use Cases and Examples......................................................... 10-3
10.1.2 Additional Functionality for Reusable Components................................................... 10-4
10.2 Common Functionality in Reusable Components.............................................................. 10-4
10.2.1 Page in Request Scope...................................................................................................... 10-4
10.2.2 Access to Child Components for Customization......................................................... 10-4
10.3 Using Page Fragments............................................................................................................. 10-4
10.3.1 How to Create a Page Fragment..................................................................................... 10-7
10.3.2 What Happens When You Create a Page Fragment.................................................... 10-8
10.3.3 How to Use a Page Fragment in a JSF Page.................................................................. 10-9
10.3.3.1 Adding a Page Fragment Using the Component Palette..................................... 10-9
10.3.3.2 Adding a Page Fragment Using the Application Navigator............................... 10-9
10.3.4 What Happens at Runtime: Resolving Page Fragments........................................... 10-10
10.4 Using Page Templates........................................................................................................... 10-10
10.4.1 How to Create a Page Template ................................................................................... 10-14
10.4.2 What Happens When You Create a Page Template.................................................. 10-18
10.4.3 How to Create JSF Pages Based on Page Templates.................................................. 10-18
10.4.4 What Happens When You Use a Template to Create a Page................................... 10-20
10.4.5 What Happens at Runtime: How Page Templates Are Resolved ........................... 10-21
10.4.6 What You May Need to Know About Page Templates and Naming Containers. 10-22
10.5 Using Declarative Components........................................................................................... 10-22
10.5.1 How to Create a Declarative Component ................................................................... 10-25
10.5.2 What Happens When You Create a Declarative Component.................................. 10-29
10.5.3 How to Deploy Declarative Components................................................................... 10-31
10.5.4 How to Use Declarative Components in JSF Pages................................................... 10-31
10.5.5 What Happens When You Use a Declarative Component on a JSF Page.............. 10-33
10.5.6 What Happens at Runtime............................................................................................ 10-34
10.6 Adding Resources to Pages .................................................................................................. 10-34
10.6.1 How to Add Resources to Page Templates and Declarative Components............ 10-35
10.6.2 What Happens at Runtime: Adding Resources to the Document Header............. 10-35
Part IV Using Common ADF Faces Components
11 Using Input Components and Defining Forms
11.1 About Input Components and Forms................................................................................... 11-1
11.1.1 Input Component Use Cases and Examples................................................................. 11-3
11.1.2 Additional Functionality for Input Components and Forms..................................... 11-5
11.2 Defining Forms......................................................................................................................... 11-6
11.2.1 How to Add a Form to a Page ........................................................................................ 11-7
11.2.2 How to Add a Subform to a Page................................................................................... 11-8
11.2.3 How to Add a Reset Button to a Form .......................................................................... 11-8
11.3 Using the inputText Component........................................................................................... 11-9
11.3.1 How to Add an inputText Component ....................................................................... 11-10
11.3.2 How to Add the Ability to Insert Text into an inputText Component................... 11-13
11.4 Using the Input Number Components............................................................................... 11-14
11.4.1 How to Add an inputNumberSlider or an inputRangeSlider Component ........... 11-15
11.4.2 How to Add an inputNumberSpinbox Component.................................................. 11-16
11.5 Using Color and Date Choosers .......................................................................................... 11-17
ix
11.5.1 How to Add an inputColor Component..................................................................... 11-18
11.5.2 How to Add an InputDate Component ...................................................................... 11-20
11.5.3 What You May Need to Know About Selecting Time Zones Without the inputDate
Component 11-21
11.6 Using Selection Components ............................................................................................... 11-22
11.6.1 How to Use Selection Components.............................................................................. 11-26
11.6.2 What You May Need to Know About the contentDelivery Attribute on the
SelectManyChoice Component 11-29
11.7 Using Shuttle Components................................................................................................... 11-30
11.7.1 How to Add a selectManyShuttle or selectOrderShuttle Component.................... 11-31
11.7.2 What You May Need to Know About Using a Client Listener for Selection Events ........
11-33
11.8 Using the richTextEditor Component................................................................................. 11-34
11.8.1 How to Add a richTextEditor Component ................................................................. 11-36
11.8.2 How to Add the Ability to Insert Text into a richTextEditor Component............. 11-37
11.8.3 How to Customize the Toolbar..................................................................................... 11-38
11.9 Using File Upload .................................................................................................................. 11-40
11.9.1 How to Use the inputFile Component......................................................................... 11-43
11.9.2 What You May Need to Know About Temporary File Storage............................... 11-43
12 Using Tables and Trees
12.1 About Tables, Trees, and Tree Tables .................................................................................. 12-1
12.1.1 Table and Tree Use Cases and Examples...................................................................... 12-2
12.1.2 Additional Functionality for Tables and Trees............................................................. 12-4
12.2 Common Functionality in Tables and Trees........................................................................ 12-5
12.2.1 Displaying Data in Rows and Nodes............................................................................. 12-5
12.2.2 Content Delivery............................................................................................................... 12-5
12.2.3 Row Selection .................................................................................................................... 12-7
12.2.4 Editing Data in Tables, Trees, and Tree Tables ............................................................ 12-8
12.2.5 Using Popup Dialogs in Tables, Trees, and Tree Tables........................................... 12-10
12.2.6 Accessing Client Table, Tree, and Tree Table Components..................................... 12-12
12.2.7 Geometry Management and Table, Tree, and Tree Table Components................. 12-12
12.3 Using the Table Component................................................................................................. 12-14
12.3.1 Columns and Column Data .......................................................................................... 12-16
12.3.2 Formatting Tables........................................................................................................... 12-16
12.3.3 Formatting Columns ...................................................................................................... 12-18
12.3.4 How to Display a Table on a Page ............................................................................... 12-19
12.3.5 What Happens When You Add a Table to a Page..................................................... 12-27
12.3.6 What Happens at Runtime: Data Delivery ................................................................. 12-28
12.3.7 What You May Need to Know About Programmatically Enabling Sorting for Table
Columns 12-29
12.3.8 What You May Need to Know About Performing an Action on Selected Rows in
Tables 12-29
12.3.9 What You May Need to Know About Dynamically Determining Values for Selection
Components in Tables 12-30
12.4 Adding Hidden Capabilities to a Table.............................................................................. 12-31
12.4.1 How to Use the detailStamp Facet ............................................................................... 12-33
x
12.4.2 What Happens at Runtime: Disclosing Row Data..................................................... 12-34
12.5 Enabling Filtering in Tables.................................................................................................. 12-34
12.5.1 How to Add Filtering to a Table................................................................................... 12-35
12.6 Displaying Data in Trees....................................................................................................... 12-36
12.6.1 How to Display Data in Trees....................................................................................... 12-39
12.6.2 What Happens When You Add a Tree to a Page....................................................... 12-42
12.6.3 What Happens at Runtime: Tree Component Events............................................... 12-42
12.6.4 What You May Need to Know About Programmatically Expanding and Collapsing
Nodes 12-43
12.6.5 What You May Need to Know About Programmatically Selecting Nodes........... 12-45
12.7 Displaying Data in Tree Tables............................................................................................ 12-45
12.7.1 How to Display Data in a Tree Table........................................................................... 12-47
12.8 Passing a Row as a Value...................................................................................................... 12-47
12.9 Displaying Table Menus, Toolbars, and Status Bars ........................................................ 12-48
12.9.1 How to Add a panelCollection with a Table, Tree, or Tree Table........................... 12-50
12.10 Exporting Data from Table, Tree, or Tree Table................................................................ 12-52
12.10.1 How to Export Table, Tree, or Tree Table Data to an External Format.................. 12-53
12.10.2 What Happens at Runtime: How Row Selection Affects the Exported Data ........ 12-55
12.11 Accessing Selected Values on the Client from Components That Use Stamping ........ 12-55
12.11.1 How to Access Values from a Selection in Stamped Components.......................... 12-55
12.11.2 What You May Need to Know About Accessing Selected Values.......................... 12-58
13 Using List-of-Values Components
13.1 About List-of-Values Components........................................................................................ 13-1
13.1.1 Additional Functionality for List-of-Values Components.......................................... 13-7
13.2 Creating the ListOfValues Data Model................................................................................. 13-8
13.2.1 How to Create the ListOfValues Data Model............................................................... 13-9
13.3 Using the inputListOfValues Component.......................................................................... 13-10
13.3.1 How to Use the InputListOfValues Component........................................................ 13-10
13.4 Using the InputComboboxListOfValues Component...................................................... 13-12
13.4.1 How to Use the InputComboboxListOfValues Component .................................... 13-13
14 Using Query Components
14.1 About Query Components ..................................................................................................... 14-1
14.1.1 Query Component Use Cases and Examples ............................................................... 14-3
14.1.2 Additional Functionality for the Query Components................................................. 14-3
14.2 Creating the Query Data Model ............................................................................................ 14-4
14.2.1 How to Create the Query Data Model......................................................................... 14-10
14.3 Using the quickQuery Component ..................................................................................... 14-11
14.3.1 How to Add the quickQuery Component Using a Model ....................................... 14-12
14.3.2 How to Use a quickQuery Component Without a Model........................................ 14-13
14.3.3 What Happens at Runtime: How the Framework Renders the quickQuery Component
and Executes the Search 14-14
14.4 Using the query Component................................................................................................ 14-15
14.4.1 How to Add the Query Component............................................................................ 14-18
xi
15 Using Popup Dialogs, Menus, and Windows
15.1 About Popup Dialogs, Menus, and Windows..................................................................... 15-1
15.1.1 Popup Dialogs, Menus, Windows Use Cases and Examples..................................... 15-3
15.1.2 Additional Functionality for Popup Dialogs, Menus, and Windows....................... 15-4
15.2 Declaratively Creating Popups.............................................................................................. 15-4
15.2.1 How to Create a Dialog.................................................................................................... 15-7
15.2.2 How to Create a Panel Window ................................................................................... 15-11
15.2.3 How to Create a Context Menu.................................................................................... 15-13
15.2.4 How to Create a Note Window .................................................................................... 15-14
15.2.5 What Happens at Runtime: Popup Component Events ........................................... 15-16
15.2.6 What You May Need to Know About Dialog Events................................................ 15-18
15.3 Declaratively Invoking a Popup.......................................................................................... 15-19
15.3.1 How to Declaratively Invoke a Popup Using the af:showPopupBehavior Tag.... 15-19
15.3.2 What Happens When You Use af:showPopupBehavior Tag to Invoke a Popup . 15-20
15.4 Programmatically Invoking a Popup.................................................................................. 15-21
15.4.1 How to Programmatically Invoke a Popup................................................................ 15-22
15.4.2 What Happens When You Programmatically Invoke a Popup............................... 15-23
15.5 Displaying Contextual Information in Popups ................................................................. 15-23
15.5.1 How to Create Contextual Information....................................................................... 15-24
15.6 Controlling the Automatic Cancellation of Inline Popups .............................................. 15-25
15.6.1 How to Disable the Automatic Cancellation of an Inline Popup ............................ 15-26
15.6.2 What Happens When You Disable the Automatic Cancellation of an Inline Popup........
15-26
15.7 Resetting Input Fields in a Popup ....................................................................................... 15-27
15.7.1 How to Reset the Input Fields in a Popup.................................................................. 15-27
15.7.2 What Happens When You Configure a Popup to Reset Its Input Fields ............... 15-28
16 Using Menus, Toolbars, and Toolboxes
16.1 About Menus, Toolbars, and Toolboxes............................................................................... 16-1
16.1.1 Menu Components Use Cases and Examples .............................................................. 16-2
16.1.2 Additional Functionality for Menu and Toolbar Components.................................. 16-4
16.2 Using Menus in a Menu Bar................................................................................................... 16-4
16.2.1 How to Create and Use Menus in a Menu Bar............................................................. 16-9
16.3 Using Toolbars ....................................................................................................................... 16-16
16.3.1 How to Create and Use Toolbars ................................................................................. 16-18
16.3.2 What Happens at Runtime: How the Size of Menu Bars and Toolbars are Determined..
16-22
16.3.3 What You May Need to Know About Toolbars......................................................... 16-23
17 Using a Calendar Component
17.1 About Creating a Calendar Component............................................................................... 17-1
17.1.1 Calendar Use Cases and Examples................................................................................ 17-4
17.1.2 Additional Functionality for the Calendar ................................................................... 17-4
17.2 Creating the Calendar ............................................................................................................. 17-5
17.2.1 Calendar Classes............................................................................................................... 17-6
17.2.2 How to Create a Calendar ............................................................................................... 17-6
xii
17.3 Configuring the Calendar Component................................................................................. 17-7
17.3.1 How to Configure the Calendar Component............................................................... 17-7
17.3.2 What Happens at Runtime: Calendar Events and PPR ............................................ 17-10
17.4 Adding Functionality Using Popup Components ............................................................ 17-11
17.4.1 How to Add Functionality Using Popup Components ............................................ 17-12
17.5 Customizing the Toolbar ...................................................................................................... 17-14
17.5.1 How to Customize the Toolbar..................................................................................... 17-14
17.6 Styling the Calendar .............................................................................................................. 17-16
17.6.1 How to Style Activities .................................................................................................. 17-17
17.6.2 What Happens at Runtime: Activity Styling .............................................................. 17-19
17.6.3 How to Customize Dates............................................................................................... 17-19
18 Using Output Components
18.1 About Output Text, Image, Icon, and Media Components............................................... 18-1
18.1.1 Output Components Use Case and Examples ............................................................. 18-2
18.1.2 Additional Functionality for Output Components...................................................... 18-4
18.2 Displaying Output Text and Formatted Output Text ........................................................ 18-4
18.2.1 How to Display Output Text .......................................................................................... 18-6
18.2.2 What You May Need to Know About Allowed Format and Character Codes in the
outputFormatted Component 18-7
18.3 Displaying Icons....................................................................................................................... 18-8
18.3.1 How to Display Icons....................................................................................................... 18-8
18.4 Displaying Images ................................................................................................................... 18-9
18.4.1 How to Display Images ................................................................................................... 18-9
18.5 Using Images as Links............................................................................................................. 18-9
18.5.1 How to Use Images as Links......................................................................................... 18-10
18.6 Displaying Images in a Carousel......................................................................................... 18-10
18.6.1 How to Create a Carousel.............................................................................................. 18-14
18.6.2 What You May Need to Know About the Carousel Component and Different Browsers
18-19
18.7 Displaying Application Status Using Icons ....................................................................... 18-20
18.8 Playing Video and Audio Clips........................................................................................... 18-21
18.8.1 How to Allow Playing of Audio and Video Clips..................................................... 18-21
19 Displaying Tips, Messages, and Help
19.1 About Displaying Tips and Messages .................................................................................. 19-1
19.1.1 Messaging Components Use Cases and Examples...................................................... 19-5
19.1.2 Additional Functionality for Message Components ................................................... 19-9
19.2 Displaying Tips for Components .......................................................................................... 19-9
19.2.1 How to Display Tips for Components........................................................................... 19-9
19.3 Displaying Hints and Error Messages for Validation and Conversion ......................... 19-10
19.3.1 How to Define Custom Validator and Converter Messages for a Component Instance..
19-11
19.3.2 How to Define Custom Validator and Converter Messages for All Instances of a
Component 19-13
19.3.3 How to Display Component Messages Inline............................................................ 19-13
19.3.4 How to Display Global Messages Inline ..................................................................... 19-14
xiii
19.4 Grouping Components with a Single Label and Message............................................... 19-15
19.4.1 How to Group Components with a Single Label and Message............................... 19-16
19.5 Displaying Help for Components ....................................................................................... 19-17
19.5.1 How to Create Resource Bundle-Based Help............................................................. 19-20
19.5.2 How to Create XLIFF-Based Help................................................................................ 19-22
19.5.3 How to Create Managed Bean Help ............................................................................ 19-24
19.5.4 How to Use JavaScript to Launch an External Help Window ................................. 19-27
19.5.5 How to Create a Java Class Help Provider................................................................. 19-28
19.5.6 How to Access Help Content from a UI Component................................................ 19-29
19.5.7 What You May Need to Know About Combining Different Message Types ....... 19-30
20 Working with Navigation Components
20.1 About Navigation Components............................................................................................. 20-1
20.1.1 Navigation Components Use Cases and Examples..................................................... 20-2
20.1.2 Additional Functionality for Navigation Components............................................... 20-5
20.2 Common Functionality in Navigation Components .......................................................... 20-6
20.3 Using Buttons and Links for Navigation.............................................................................. 20-6
20.3.1 How to Use Command Buttons and Command Links............................................... 20-8
20.3.2 How to Use Go Buttons and Go Links ........................................................................ 20-10
20.3.3 What You May Need to Know About Using Partial Page Navigation................... 20-11
20.4 Configuring a Browser’s Context Menu for Command Links........................................ 20-12
20.4.1 How to Configure a Browser’s Context Menu for Command Links ...................... 20-12
20.4.2 What Happens When You Configure a Browser’s Context Menu for Command Links..
20-13
20.5 Using Buttons or Links to Invoke Functionality ............................................................... 20-13
20.5.1 How to Use a Command Component to Download Files........................................ 20-14
20.5.2 How to Use a Command Component to Reset Input Fields.................................... 20-16
20.6 Using Navigation Items for a Page Hierarchy................................................................... 20-17
20.6.1 How to Create Navigation Cases for a Page Hierarchy............................................ 20-20
20.7 Using a Menu Model to Create a Page Hierarchy............................................................. 20-22
20.7.1 How to Create the Menu Model Metadata ................................................................. 20-23
20.7.2 What Happens When You Use the Create ADF Menu Model Wizard .................. 20-30
20.7.3 How to Bind the navigationPane Component to the Menu Model ........................ 20-32
20.7.4 How to Use the breadCrumbs Component with a Menu Model............................ 20-36
20.7.5 How to Use the menuBar Component with a Menu Model .................................... 20-37
20.7.6 What Happens at Runtime............................................................................................ 20-39
20.7.7 What You May Need to Know About Using Custom Attributes............................ 20-41
20.8 Creating a Simple Navigational Hierarchy........................................................................ 20-43
20.8.1 How to Create a Simple Page Hierarchy..................................................................... 20-44
20.8.2 How to Use the breadCrumbs Component ................................................................ 20-48
20.8.3 What You May Need to Know About Removing Navigation Tabs........................ 20-50
20.9 Using Train Components to Create Navigation Items for a Multistep Process ........... 20-51
20.9.1 How to Create the Train Model.................................................................................... 20-54
20.9.2 How to Configure Managed Beans for the Train Model .......................................... 20-57
20.9.3 How to Bind to the Train Model in JSF Pages............................................................ 20-61
Part V Using ADF Data Visualization Components
xiv
21 Introduction to ADF Data Visualization Components
21.1 About ADF Data Visualization Components ...................................................................... 21-1
21.1.1 Graph Component Use Cases and Examples............................................................... 21-1
21.1.2 Gauge Component Use Cases and Examples............................................................... 21-4
21.1.3 Pivot Table Use Cases and Examples ............................................................................ 21-6
21.1.4 Geographic Map Use Cases and Examples................................................................... 21-6
21.1.5 Thematic Map Component Use Cases and Examples................................................. 21-7
21.1.6 Gantt Chart Component Use Cases and Examples ..................................................... 21-8
21.1.7 Hierarchy Viewer Component Use Cases and Examples........................................... 21-9
21.1.8 Additional Functionality for Data Visualization Components................................ 21-10
21.2 Common Functionality in Data Visualization Components ........................................... 21-11
21.2.1 Content Delivery............................................................................................................. 21-11
21.2.2 Automatic Partial Page Rendering (PPR).................................................................... 21-12
21.2.3 Image Formats for Graph and Gauge Components .................................................. 21-13
21.2.4 Embedded Fonts for Graph and Gauge Components............................................... 21-13
21.2.5 Graph and Gauge Context Menus ............................................................................... 21-14
21.2.6 Screen Reader Support .................................................................................................. 21-15
21.2.7 Text Resources from Application Resource Bundles ................................................ 21-15
21.3 Providing Data for ADF Data Visualization Components .............................................. 21-16
22 Using Graph Components
22.1 About the Graph Component ................................................................................................ 22-1
22.1.1 End User and Presentation Features.............................................................................. 22-2
22.1.1.1 Graph Layout ............................................................................................................. 22-2
22.1.1.2 Sizing ........................................................................................................................... 22-2
22.1.1.3 Data Marker Selection............................................................................................... 22-2
22.1.1.4 Context Menus........................................................................................................... 22-2
22.1.1.5 Reference Areas/Line and Alerts............................................................................ 22-3
22.1.1.6 Hide and Show Series ............................................................................................... 22-3
22.1.1.7 Drilling ........................................................................................................................ 22-4
22.1.1.8 Annotations ................................................................................................................ 22-4
22.1.1.9 Popup Support........................................................................................................... 22-5
22.1.1.10 Time Selector.............................................................................................................. 22-5
22.1.1.11 Bi-directional Support............................................................................................... 22-6
22.1.1.12 Drag and Drop ........................................................................................................... 22-6
22.1.1.13 Screen Reader Support.............................................................................................. 22-6
22.1.2 Graph Component Use Cases and Examples............................................................... 22-7
22.1.3 Additional Functionality for Graph Components ..................................................... 22-16
22.2 Using the Graph Component............................................................................................... 22-17
22.2.1 Graph Type Data Requirements................................................................................... 22-17
22.2.2 Configuring Graphs ....................................................................................................... 22-21
22.2.3 How to Add a Graph to a Page..................................................................................... 22-26
22.2.4 What Happens When You Add a Graph to a Page ................................................... 22-28
22.2.5 How to Create a Graph Using Tabular Data ............................................................. 22-29
22.2.6 What You May Need to Know About Flash and PNG Image Formats.................. 22-30
22.2.7 Editing Graphs in the Visual Editor and Property Inspector................................... 22-31
22.3 Customizing Graph Display Elements ............................................................................... 22-32
xv
22.3.1 Changing Graph Size and Style ................................................................................... 22-32
22.3.1.1 How to Specify the Size of a Graph at Initial Display........................................ 22-33
22.3.1.2 How to Provide for Dynamic Resizing of a Graph ............................................ 22-33
22.3.1.3 How to Use a Specific Style Sheet for a Graph.................................................... 22-33
22.3.2 Changing Graph Background, Plot Area, and Title .................................................. 22-34
22.3.2.1 How to Customize the Background and Plot Area of a Graph ........................ 22-34
22.3.2.2 How to Specify Titles and Footnotes in a Graph ................................................ 22-35
22.3.3 How to Customize Graph Axes and Labels................................................................ 22-35
22.3.3.1 How to Specify the Title, Appearance, and Scaling of an Axis ........................ 22-36
22.3.3.2 How to Specify Scrolling on an Axis .................................................................... 22-37
22.3.3.3 How to Control the Appearance of Tick Marks and Labels on an Axis.......... 22-37
22.3.3.4 How to Format Numbers on an Axis ................................................................... 22-38
22.3.3.5 How to Set Minimum and Maximum Values on a Data Axis .......................... 22-39
22.3.4 Customizing Graph Legends........................................................................................ 22-39
22.3.5 Customizing Tooltips in Graphs .................................................................................. 22-40
22.4 Formatting Graph Text, Colors, and Data Values............................................................. 22-41
22.4.1 Formatting Text in Graphs ............................................................................................ 22-41
22.4.1.1 How to Globally Set Graph Font Using a Skin ................................................... 22-42
22.4.2 Specifying Transparent Colors for Parts of a Graph ................................................. 22-44
22.4.3 Using Gradient Special Effects in Graphs................................................................... 22-44
22.4.3.1 How to Add Gradient Special Effects to a Graph............................................... 22-45
22.4.3.2 What Happens When You Add a Gradient Special Effect to a Graph ............ 22-46
22.4.4 Formatting Data Values in Graphs .............................................................................. 22-46
22.4.4.1 How to Format Categorical Data Values ............................................................. 22-46
22.4.4.2 How to Format Numerical Data Values............................................................... 22-47
22.4.4.3 What You May Need to Know About Automatic Scaling and Precision........ 22-49
22.5 Customizing the Appearance of Series and Groups of Data........................................... 22-49
22.5.1 Changing the Color, Style, and Display of Graph Data Values............................... 22-49
22.5.1.1 How to Specify the Color and Style for Individual Series Items...................... 22-50
22.5.1.2 How to Control the Number of Different Colors Used for Series Items......... 22-50
22.5.1.3 How to Enable Hiding and Showing Series Items ............................................. 22-51
22.5.2 Changing the Appearance of Pie Graphs.................................................................... 22-51
22.5.2.1 How to Customize the Overall Appearance of Pie Graphs .............................. 22-51
22.5.2.2 How to Customize an Exploding Pie Slice .......................................................... 22-51
22.5.3 Changing the Appearance of Lines in Graphs ........................................................... 22-52
22.5.3.1 How to Display Either Data Lines or Markers in Graphs ................................. 22-52
22.5.3.2 How to Change the Appearance of Lines in a Graph Series............................. 22-53
22.5.4 Customizing Pareto Graphs.......................................................................................... 22-53
22.5.5 Customizing Scatter Graph Series Marker Data Values ........................................... 22-53
22.5.6 Customizing Graph Marker Shapes............................................................................. 22-54
22.5.7 Adding Reference Lines or Areas to Graphs.............................................................. 22-56
22.5.7.1 How to Create Reference Lines or Areas During Design.................................. 22-56
22.5.7.2 What Happens When You Create Reference Lines or Areas During Design. 22-57
22.5.7.3 How to Create Reference Lines or Areas Dynamically...................................... 22-58
22.6 Animating Graphs ................................................................................................................. 22-58
22.6.1 How to Configure Graph Components to Display Active Data.............................. 22-59
22.6.2 How to Specify Animation Effects for Graphs........................................................... 22-59
xvi
22.7 Adding Interactive Features to Graphs .............................................................................. 22-60
22.7.1 Providing Interactive Capability for Graphs.............................................................. 22-61
22.7.1.1 How to Provide Marker and Legend Dimming.................................................. 22-61
22.7.1.2 How to React to Changes in the Zoom and Scroll Levels.................................. 22-61
22.7.2 Providing an Interactive Time Axis for Graphs......................................................... 22-62
22.7.2.1 How to Define a Relative Range of Time Data for Display............................... 22-62
22.7.2.2 How to Define an Explicit Range of Time Data for Display ............................. 22-62
22.7.3 Adding Alerts and Annotations to Graphs................................................................. 22-63
22.7.4 Creating Drillable Graphs ............................................................................................. 22-64
22.7.5 How to Add Drag and Drop to Graphs ...................................................................... 22-65
22.7.6 How to Add Popups to Graphs.................................................................................... 22-67
22.7.7 How to Configure Graph Context Menus................................................................... 22-69
23 Using Gauge Components
23.1 About the Gauge Component................................................................................................ 23-1
23.1.1 End User and Presentation Features of Gauge Components..................................... 23-1
23.1.2 Gauge Component Use Cases and Examples............................................................... 23-2
23.1.3 Additional Functionality of Gauge Components......................................................... 23-5
23.2 Using the Gauge Component................................................................................................. 23-5
23.2.1 Configuring Gauges ......................................................................................................... 23-6
23.2.2 How to Add a Gauge to a Page ...................................................................................... 23-7
23.2.3 What Happens When You Add a Gauge to a Page................................................... 23-10
23.2.4 How to Create a Gauge Using Tabular Data ............................................................. 23-11
23.2.5 What You May Need to Know About Flash and PNG Image Formats.................. 23-13
23.2.6 Using Gauges in Tables.................................................................................................. 23-14
23.3 Configuring Gauge Display Elements................................................................................ 23-15
23.3.1 How to Configure Gauge Thresholds.......................................................................... 23-15
23.3.2 How to Customize Gauge Labels................................................................................. 23-16
23.3.3 How to Customize Gauge Indicators and Tick Marks.............................................. 23-17
23.3.4 How to Specify the Layout of Gauges in a Gauge Set............................................... 23-20
23.3.5 What You May Need to Know About Configuring Gauge Set Display................. 23-21
23.4 Formatting Gauge Style Elements....................................................................................... 23-21
23.4.1 How to Change Gauge Size and Apply CSS Styles................................................... 23-21
23.4.2 Specifying Transparency for Gauge Elements ........................................................... 23-22
23.4.3 How to Format Gauge Text and Use Text Resources................................................ 23-22
23.5 Formatting Numeric Data Values in Gauges..................................................................... 23-24
23.5.1 How to Format Numeric Data Values in Gauges...................................................... 23-24
23.5.2 What You May Need to Know About Automatic Scaling and Precision............... 23-25
23.6 Adding Gauge Special Effects and Animation.................................................................. 23-25
23.6.1 How to Add Gradient Special Effects to a Gauge...................................................... 23-25
23.6.2 What Happens When You Add a Gradient Special Effect to a Gauge ................... 23-27
23.6.3 How to Add Interactivity to Gauges ........................................................................... 23-27
23.6.4 Animating Gauges.......................................................................................................... 23-29
23.6.5 How to Specify Animation Effects for Gauges........................................................... 23-30
23.6.6 How to Configure Gauges to Display Active Data ................................................... 23-30
23.7 Using Custom Shapes for Gauges ....................................................................................... 23-31
23.7.1 How to Use Prebuilt Custom Shapes Styles ............................................................... 23-31
xvii
23.7.2 How to Use a Custom Shapes Graphic File................................................................ 23-32
23.7.3 What You May Need to Know About Supported SVG Features ............................ 23-35
24 Using Pivot Table Components
24.1 About the Pivot Table Component........................................................................................ 24-1
24.1.1 End User and Presentation Features of Pivot Table Components ............................ 24-1
24.1.1.1 Pivot Filter Bar ........................................................................................................... 24-2
24.1.1.2 Pivoting....................................................................................................................... 24-2
24.1.1.3 Editing Data Cells...................................................................................................... 24-3
24.1.1.4 Sorting ......................................................................................................................... 24-4
24.1.1.5 Drilling ........................................................................................................................ 24-4
24.1.1.6 On Demand Data Scrolling ...................................................................................... 24-5
24.1.1.7 Sizing ........................................................................................................................... 24-5
24.1.2 Pivot Table and Pivot Filter Bar Component Use Cases and Examples................... 24-6
24.1.3 Additional Functionality for the Pivot Table Component.......................................... 24-9
24.2 Using the Pivot Table Component ...................................................................................... 24-10
24.2.1 Configuring Pivot Tables............................................................................................... 24-10
24.2.2 How to Add a Pivot Table to a Page............................................................................ 24-12
24.2.3 What Happens When You Add a Pivot Table to a Page........................................... 24-14
24.3 Using Stamping in Pivot Tables........................................................................................... 24-14
24.3.1 How to Configure Header and Data Cells as Stamps............................................... 24-15
24.3.2 What You May Need to Know About Using var and varStatus Properties .......... 24-19
24.4 Using a Pivot Filter Bar with a Pivot Table........................................................................ 24-22
24.4.1 How to Associate a Pivot Filter Bar with a Pivot Table ............................................ 24-23
24.5 Customizing Pivot Table Cell Content ............................................................................... 24-24
24.5.1 How to Create a CellFormat Object for a Data Cell................................................... 24-24
24.5.2 How to Change Cell Format ......................................................................................... 24-25
24.5.3 How to Create Stoplight and Conditional Formatting in a Pivot Table ................ 24-27
24.6 Using Selection in Pivot Tables............................................................................................ 24-28
24.7 Updating Pivot Tables with Partial Page Rendering........................................................ 24-28
24.8 How to Export from a Pivot Table ...................................................................................... 24-29
25 Using Map Components
25.1 About Map Components ........................................................................................................ 25-1
25.1.1 End User and Presentation Features of Maps .............................................................. 25-1
25.1.1.1 Geographic Map End User and Presentation Features........................................ 25-2
25.1.1.2 Thematic Map End User and Presentation Features............................................ 25-5
25.1.2 Map Component Use Cases and Examples .................................................................. 25-7
25.1.3 Additional Functionality for Map Components .......................................................... 25-9
25.2 Using the Geographic Map Component............................................................................. 25-10
25.2.1 Configuring Geographic Map Components............................................................... 25-11
25.2.2 How to Add a Geographic Map to a Page.................................................................. 25-12
25.2.3 What Happens When You Add a Geographic Map to a Page................................. 25-15
25.3 Customizing Geographic Map Display Attributes........................................................... 25-16
25.3.1 How to Adjust the Map Size......................................................................................... 25-16
25.3.2 How to Specify Strategy for Map Zoom Control....................................................... 25-16
xviii
25.3.3 How to Customize and Use Map Selections............................................................... 25-17
25.3.4 How to Customize the Map Legend............................................................................ 25-19
25.4 Customizing Geographic Map Themes.............................................................................. 25-21
25.4.1 How to Customize Zoom Levels for a Theme............................................................ 25-21
25.4.2 How to Customize the Labels of a Map Theme......................................................... 25-21
25.4.3 How to Customize Color Map Themes....................................................................... 25-22
25.4.4 How to Customize Point Images in a Point Theme................................................... 25-23
25.4.5 What Happens When You Customize the Point Images in a Map ......................... 25-24
25.4.6 How to Customize the Bars in a Bar Graph Theme................................................... 25-24
25.4.7 What Happens When You Customize the Bars in a Map Bar Graph Theme ........ 25-25
25.4.8 How to Customize the Slices in a Pie Graph Theme................................................. 25-25
25.4.9 What Happens When You Customize the Slices in a Map Pie Graph Theme....... 25-26
25.5 Adding a Toolbar to a Geographic Map............................................................................. 25-27
25.5.1 How to Add a Toolbar to a Map .................................................................................. 25-27
25.5.2 What Happens When You Add a Toolbar to a Map ................................................. 25-28
25.6 Using Thematic Map Components...................................................................................... 25-28
25.6.1 Configuring Thematic Maps ......................................................................................... 25-28
25.6.2 What You May Need to Know About Prebuilt Base Maps ...................................... 25-33
25.6.3 Using the Layer Browser ............................................................................................... 25-33
25.6.4 How to Add a Thematic Map to a Page ...................................................................... 25-34
25.6.5 What Happens When You Add a Thematic Map to a Page..................................... 25-38
25.6.6 What You May Need to Know About Flash and PNG Image Formats.................. 25-38
25.7 Customizing Thematic Map Display Attributes ............................................................... 25-39
25.7.1 How to Customize Thematic Map Labels................................................................... 25-39
25.7.2 How to Configure Tooltips to Display Data............................................................... 25-41
25.7.3 How to Format Numeric Data Values in Area and Marker Labels......................... 25-41
25.8 Adding Interactivity to Thematic Maps ............................................................................. 25-42
25.8.1 How to Configure Selection and Action Events in Thematic Maps........................ 25-42
25.8.2 How to Add Popups to Thematic Map Areas and Markers .................................... 25-44
25.8.3 How to Configure Animation Effects.......................................................................... 25-48
25.8.4 How to Add Drag and Drop to Thematic Map Components.................................. 25-49
26 Using Gantt Chart Components
26.1 About Gantt Chart Components............................................................................................ 26-1
26.1.1 End User and Presentation Features.............................................................................. 26-2
26.1.1.1 Scrolling, Zooming, and Panning............................................................................ 26-2
26.1.1.2 Selection ...................................................................................................................... 26-2
26.1.1.3 How to Navigate to a Specific Date in a Gantt Chart- Navigation and Display.........
26-2
26.1.1.4 How to Control the Visibility of Columns in the Table Region.......................... 26-2
26.1.1.5 Navigating in a Gantt Chart..................................................................................... 26-3
26.1.1.6 How to Display Data in a Hierarchical List or a Flat List.................................... 26-3
26.1.1.7 How to Change the Gantt Chart Time Scale ......................................................... 26-3
26.1.1.8 Server-Side Events..................................................................................................... 26-4
26.1.2 Gantt Chart Component Use Cases and Examples ..................................................... 26-4
26.1.3 Additional Functionality for Gantt Chart Components.............................................. 26-7
26.2 Using Gantt Chart Components ........................................................................................... 26-8
xix
26.2.1 Data for a Project Gantt Chart......................................................................................... 26-8
26.2.2 Data for a Resource Utilization Gantt Chart................................................................. 26-9
26.2.3 Data for a Scheduling Gantt Chart............................................................................... 26-10
26.2.4 Gantt Chart Tasks ........................................................................................................... 26-11
26.2.5 Configuring Gantt Charts.............................................................................................. 26-12
26.2.6 How to Add a Gantt Chart to a Page........................................................................... 26-14
26.2.7 What Happens When You Add a Gantt Chart to a Page.......................................... 26-16
26.3 Customizing Gantt Chart Legends, Toolbars, and Context Menus ............................... 26-17
26.3.1 How to Customize a Gantt Chart Legend................................................................... 26-17
26.3.2 Customizing Gantt Chart Toolbars.............................................................................. 26-18
26.3.3 Customizing Gantt Chart Context Menus .................................................................. 26-19
26.4 Working with Gantt Chart Tasks and Resources.............................................................. 26-20
26.4.1 How to Create a New Task Type ................................................................................. 26-20
26.4.2 How to Specify Custom Data Filters............................................................................ 26-21
26.4.3 How to Add a Double-Click Event to a Task Bar ...................................................... 26-22
26.5 Specifying Nonworking Days, Read-Only Features, and Time Axes............................ 26-22
26.5.1 Identifying Nonworking Days in a Gantt Chart........................................................ 26-22
26.5.1.1 How to Specify Weekdays as Nonworking Days............................................... 26-23
26.5.1.2 How to Identify Specific Dates as Nonworking Days ....................................... 26-23
26.5.2 How to Apply Read-Only Values to Gantt Chart Features...................................... 26-24
26.5.3 Customizing the Time Axis of a Gantt Chart ............................................................. 26-24
26.5.3.1 How to Create and Use a Custom Time Axis...................................................... 26-25
26.6 Printing a Gantt Chart........................................................................................................... 26-26
26.6.1 Print Options ................................................................................................................... 26-26
26.6.2 Action Listener to Handle the Print Event.................................................................. 26-27
26.7 Using Gantt Charts as a Drop Target or Drag Source...................................................... 26-28
27 Using Hierarchy Viewer Components
27.1 About Hierarchy Viewer Components................................................................................. 27-1
27.1.1 End User and Presentation Features.............................................................................. 27-1
27.1.1.1 Layouts........................................................................................................................ 27-1
27.1.1.2 Navigation .................................................................................................................. 27-3
27.1.1.3 Tilt Panning ................................................................................................................ 27-4
27.1.1.4 Control Panel.............................................................................................................. 27-4
27.1.1.5 Printing........................................................................................................................ 27-6
27.1.1.6 Bi-directional Support............................................................................................... 27-6
27.1.1.7 Disable Features......................................................................................................... 27-6
27.1.1.8 State Management ..................................................................................................... 27-7
27.1.2 Hierarchy Viewer Use Cases and Examples................................................................. 27-7
27.1.3 Additional Functionality for Hierarchy Viewer Components................................... 27-7
27.2 Using Hierarchy Viewer Components.................................................................................. 27-8
27.2.1 Configuring Hierarchy Viewer Components ............................................................... 27-8
27.2.2 How to Add a Hierarchy Viewer to a Page .................................................................. 27-9
27.2.3 What Happens When You Add a Hierarchy Viewer to a Page............................... 27-12
27.2.4 What You May Need to Know About How HTML Rendering............................... 27-14
27.3 Managing Nodes in a Hierarchy Viewer............................................................................ 27-14
27.3.1 How to Specify Node Content...................................................................................... 27-16
xx
27.3.2 How to Configure the Controls on a Node................................................................. 27-18
27.3.3 How to Specify a Node Definition for an Accessor................................................... 27-19
27.3.4 How to Associate a Node Definition with a Particular Set of Data Rows.............. 27-19
27.3.5 How to Specify Ancestor Levels for an Anchor Node.............................................. 27-20
27.4 Using Panel Cards.................................................................................................................. 27-20
27.4.1 How to Create a Panel Card.......................................................................................... 27-21
27.4.2 What Happens at Runtime When a Panel Card Component Is Rendered ............ 27-21
27.5 Configuring Navigation in a Hierarchy Viewer................................................................ 27-22
27.5.1 How to Configure Upward Navigation in a Hierarchy Viewer.............................. 27-22
27.5.2 How to Configure Same-Level Navigation in a Hierarchy Viewer ........................ 27-22
27.5.3 What Happens When You Configure Same-Level Navigation in a Hierarchy Viewer....
27-23
27.6 Customizing the Appearance of a Hierarchy Viewer ...................................................... 27-23
27.6.1 How to Adjust the Size of a Hierarchy Viewer.......................................................... 27-24
27.6.2 How to Include Images in a Hierarchy Viewer.......................................................... 27-24
27.6.3 How to Configure the Display of the Control Panel ................................................. 27-24
27.6.4 How to Configure the Display of Links and Labels .................................................. 27-25
27.7 Adding Interactivity to a Hierarchy Viewer Component................................................ 27-26
27.7.1 How to Configure Node Selection Action .................................................................. 27-26
27.7.2 How to Configure a Hierarchy Viewer to Invoke a Popup Window ..................... 27-26
27.7.3 How to Configure a Hierarchy View Node to Invoke a Menu................................ 27-28
27.8 Adding Search to a Hierarchy Viewer................................................................................ 27-28
27.8.1 How to Configure Searching in a Hierarchy Viewer ................................................ 27-29
27.8.2 What You May Need to Know About Configuring Search in a Hierarchy Viewer...........
27-31
Part VI Completing Your View
28 Customizing the Appearance Using Styles and Skins
28.1 About Customizing the Appearance Using Styles and Skins ........................................... 28-1
28.1.1 Customizing the Appearance Use Cases and Examples............................................. 28-3
28.1.2 Additional Functionality for Customizing the Appearance ..................................... 28-3
28.2 Changing the Style Properties of a Component ................................................................. 28-4
28.2.1 How to Set an Inline Style ............................................................................................... 28-4
28.2.2 How to Set a Style Class................................................................................................... 28-6
28.3 Enabling End Users to Change an Application’s ADF Skin ............................................. 28-6
28.3.1 How to Enable End Users Change an Application's ADF Skin................................. 28-7
28.3.2 What Happens at Runtime: Changing an Application's ADF Skin ......................... 28-8
29 Internationalizing and Localizing Pages
29.1 About Internationalizing and Localizing ADF Faces Pages.............................................. 29-1
29.1.1 Internationalizing and Localizing Pages Use Cases and Examples.......................... 29-2
29.1.2 Additional Functionality for Internationalizing and Localizing Pages.................... 29-3
29.2 Using Automatic Resource Bundle Integration in JDeveloper ......................................... 29-4
29.2.1 How to Set Resource Bundle Options............................................................................ 29-5
29.2.2 What Happens When You Set Resource Bundle Options .......................................... 29-6
29.2.3 How to Create an Entry in a JDeveloper-Generated Resource Bundle .................... 29-7
xxi
29.2.4 What Happens When You Create an Entry in a JDeveloper-Generated Resource
Bundle 29-8
29.3 Manually Defining Resource Bundles and Locales ............................................................ 29-8
29.3.1 How to Define the Base Resource Bundle..................................................................... 29-9
29.3.2 How to Edit a Resource Bundle File ............................................................................ 29-12
29.3.3 How to Register Locales and Resource Bundles in Your Application.................... 29-14
29.3.4 How to Use Resource Bundles in Your Application ................................................. 29-15
29.3.5 What You May Need to Know About ADF Skins and Control Hints.................... 29-16
29.3.6 What You May Need to Know About Overriding a Resource Bundle in a Customizable
Application 29-16
29.4 Configuring Pages for an End User to Specify Locale at Runtime................................. 29-17
29.4.1 How to Configure a Page for an End User to Specify Locale................................... 29-17
29.4.2 What Happens When You Configure a Page to Specify Locale .............................. 29-18
29.4.3 What Happens at Runtime When an End User Specifies a Locale.......................... 29-19
29.5 Configuring Optional ADF Faces Localization Properties.............................................. 29-19
29.5.1 How to Configure Optional Localization Properties ................................................ 29-20
30 Developing Accessible ADF Faces Pages
30.1 About Accessibility Support In ADF Faces.......................................................................... 30-1
30.1.1 ADF Faces Accessibility Support Use Cases and Examples....................................... 30-2
30.1.2 Additional Information for Accessibility Support in ADF Pages.............................. 30-2
30.2 Configuring Accessibility Support In ADF Faces ............................................................... 30-3
30.2.1 Accessibility Support Guidelines at Sign-In ................................................................. 30-3
30.2.2 How to Configure Accessibility Support in trinidad-config.xml .............................. 30-5
30.3 Specifying Component-Level Accessibility Properties ...................................................... 30-6
30.3.1 ADF Faces Component Accessibility Guidelines......................................................... 30-6
30.3.2 Using ADF Faces Table Components in Screen Reader Mode ................................ 30-11
30.3.3 Data Visualization Components Accessibility Guidelines....................................... 30-11
30.3.4 How to Define Access Keys for an ADF Faces Component..................................... 30-13
30.3.5 How to Define Localized Labels and Access Keys .................................................... 30-14
30.4 Creating Accessible Pages .................................................................................................... 30-15
30.4.1 How to Use Partial Page Rendering ............................................................................ 30-17
30.4.2 How to Use Scripting ..................................................................................................... 30-17
30.4.3 How to Use Styles........................................................................................................... 30-20
30.4.4 How to Use Page Structures and Navigation............................................................. 30-20
30.4.5 How to Use Images and Tables .................................................................................... 30-22
30.4.6 How to Use WAI-ARIA Landmark Regions .............................................................. 30-23
30.5 Running Accessibility Audit Rules ..................................................................................... 30-23
30.5.1 How to Create and Run an Audit Profile.................................................................... 30-23
31 Creating Custom ADF Faces Components
31.1 About Custom ADF Faces Components............................................................................... 31-1
31.1.1 Developing a Custom Component with JDeveloper................................................... 31-2
31.1.2 An Example Custom Component .................................................................................. 31-5
31.2 Setting Up the Workspace and Starter Files......................................................................... 31-9
31.2.1 How to Set Up the JDeveloper Custom Component Environment ........................ 31-10
xxii
31.2.2 How to Add a Faces Configuration File...................................................................... 31-12
31.2.3 How to Add a MyFaces Trinidad Skins Configuration File..................................... 31-12
31.2.4 How to Add a Cascading Style Sheet .......................................................................... 31-13
31.2.5 How to Add a Resource Kit Loader ............................................................................ 31-13
31.2.6 How to Add a JavaServer Pages Tag Library Descriptor File ................................. 31-14
31.2.7 How to Add a JavaScript Library Feature Configuration File................................. 31-14
31.2.8 How to Add a Facelets Tag Library Configuration File............................................ 31-15
31.3 Developing for the Client-Side............................................................................................. 31-16
31.3.1 How to Create a JavaScript File for a Component..................................................... 31-17
31.3.2 How to Create a Javascript File for an Event.............................................................. 31-18
31.3.3 How to Create a JavaScript File for a Peer.................................................................. 31-18
31.3.4 How to Add a Custom Component to a JavaScript Library Feature Configuration File .
31-20
31.4 Developing for the Server-Side............................................................................................ 31-20
31.4.1 How to Create a Class for an Event Listener.............................................................. 31-21
31.4.2 How to Create a Class for an Event ............................................................................. 31-22
31.4.3 Creating the Component ............................................................................................... 31-24
31.4.4 How to Create a Class for a Component..................................................................... 31-25
31.4.5 How to Add the Component to the faces-config.xml File........................................ 31-28
31.4.6 How to Create a Class for a Resource Bundle............................................................ 31-29
31.4.7 How to Create a Class for a Renderer.......................................................................... 31-31
31.4.8 How to Add the Renderer to the faces-config.xml File............................................. 31-32
31.4.9 How to Create JSP Tag Properties................................................................................ 31-33
31.4.10 How to Configure the Tag Library Descriptor........................................................... 31-35
31.4.11 How to Create a Resource Loader................................................................................ 31-36
31.4.12 How to Create a MyFaces Trinidad Cascading Style Sheet ..................................... 31-38
31.5 Deploying a Component Library......................................................................................... 31-40
31.5.1 How to Deploy a Component Library......................................................................... 31-40
31.6 Adding the Custom Component to an Application ......................................................... 31-40
31.6.1 How to Configure the Web Deployment Descriptor................................................. 31-41
31.6.2 How to Enable JavaScript Logging and Assertions................................................... 31-41
31.6.3 How to Add a Custom Component to JSF Pages....................................................... 31-42
31.6.4 What You May Need to Know About Using the tagPane Custom Component... 31-43
32 Allowing User Customization on JSF Pages
32.1 About User Customization..................................................................................................... 32-1
32.1.1 User Customization Use Cases and Examples............................................................. 32-5
32.2 Implementing Session Change Persistence.......................................................................... 32-6
32.2.1 How to Implement Session Change Persistence.......................................................... 32-6
32.2.2 What Happens When You Configure Your Application to Use Change Persistence .......
32-6
32.2.3 What Happens at Runtime: How Changes are Persisted........................................... 32-6
32.2.4 What You May Need to Know About Using Change Persistence on Templates and
Regions 32-7
33 Adding Drag and Drop Functionality
33.1 About Drag and Drop Functionality..................................................................................... 33-1
xxiii
33.1.1 Additional Functionality for Drag and Drop ............................................................... 33-4
33.2 Adding Drag and Drop Functionality for Attributes......................................................... 33-4
33.3 Adding Drag and Drop Functionality for Objects .............................................................. 33-5
33.3.1 How to Add Drag and Drop Functionality for a Single Object................................. 33-6
33.3.2 What Happens at Runtime.............................................................................................. 33-8
33.3.3 What You May Need to Know About Using the ClientDropListener...................... 33-9
33.4 Adding Drag and Drop Functionality for Collections ..................................................... 33-10
33.4.1 How to Add Drag and Drop Functionality for Collections...................................... 33-10
33.4.2 What You May Need to Know About the dragDropEndListener........................... 33-12
33.5 Adding Drag and Drop Functionality for Components .................................................. 33-13
33.5.1 How to Add Drag and Drop Functionality for Components................................... 33-13
33.6 Adding Drag and Drop Functionality Into and Out of a panelDashboard Component..........
33-15
33.6.1 How to Add Drag and Drop Functionality Into a panelDashboard Component. 33-16
33.6.2 How to Add Drag and Drop Functionality Out of a panelDashboard Component..........
33-18
33.7 Adding Drag and Drop Functionality to a Calendar ....................................................... 33-20
33.7.1 How to Add Drag and Drop Functionality to a Calendar........................................ 33-20
33.7.2 What You May Need to Know About Dragging and Dropping in a Calendar..... 33-22
33.8 Adding Drag and Drop Functionality for DVT Graphs................................................... 33-22
33.8.1 How to Add Drag and Drop Functionality for a DVT Graph.................................. 33-22
33.9 Adding Drag and Drop Functionality for DVT Gantt Charts......................................... 33-24
33.9.1 How to Add Drag and Drop Functionality for a DVT Component........................ 33-25
34 Using Different Output Modes
34.1 About Using Different Output Modes.................................................................................. 34-1
34.1.1 Output Mode Use Cases.................................................................................................. 34-2
34.2 Displaying a Page for Print..................................................................................................... 34-4
34.2.1 How to Use the showPrintablePageBehavior Tag....................................................... 34-4
34.3 Creating Emailable Pages ....................................................................................................... 34-5
34.3.1 How to Create an Emailable Page.................................................................................. 34-6
34.3.2 How to Test the Rendering of a Page in an Email Client............................................ 34-6
34.3.3 What Happens at Runtime: How ADF Faces Converts JSF Pages to Emailable Pages.....
34-7
35 Using the Active Data Service with an Asynchronous Backend
35.1 About the Active Data Service............................................................................................... 35-1
35.1.1 Active Data Service Use Cases and Examples.............................................................. 35-2
35.2 Process Overview for Using Active Data Service ............................................................... 35-2
35.3 Implement the ActiveModel Interface in a Managed Bean............................................... 35-3
35.3.1 What You May Need to Know About Read Consistency........................................... 35-6
35.4 Pass the Event Into the Active Data Service......................................................................... 35-6
35.5 Register the Data Update Event Listener ............................................................................. 35-7
35.6 Configure the ADF Component to Display Active Data ................................................... 35-8
Part VII Appendixes
xxiv
A ADF Faces Configuration
A.1 About Configuring ADF Faces ................................................................................................ A-1
A.2 Configuration in web.xml......................................................................................................... A-1
A.2.1 How to Configure for JSF and ADF Faces in web.xml.................................................. A-2
A.2.2 What You May Need to Know About Required Elements in web.xml...................... A-3
A.2.3 What You May Need to Know About ADF Faces Context Parameters in web.xml. A-4
A.2.3.1 State Saving .................................................................................................................. A-4
A.2.3.2 Debugging .................................................................................................................... A-5
A.2.3.3 File Uploading.............................................................................................................. A-6
A.2.3.4 Resource Debug Mode................................................................................................ A-6
A.2.3.5 User Customization..................................................................................................... A-6
A.2.3.6 Enabling the Application for Real User Experience Insight.................................. A-6
A.2.3.7 Assertions ..................................................................................................................... A-7
A.2.3.8 Profiling......................................................................................................................... A-7
A.2.3.9 Dialog Prefix................................................................................................................. A-7
A.2.3.10 Compression for CSS Class Names........................................................................... A-7
A.2.3.11 Control Caching When You Have Multiple ADF Skins in an Application ........ A-8
A.2.3.12 Test Automation .......................................................................................................... A-8
A.2.3.13 UIViewRoot Caching .................................................................................................. A-8
A.2.3.14 Themes and Tonal Styles............................................................................................ A-8
A.2.3.15 Partial Page Rendering ............................................................................................... A-8
A.2.3.16 Partial Page Navigation.............................................................................................. A-9
A.2.3.17 JavaScript Partitioning................................................................................................ A-9
A.2.3.18 Framebusting ............................................................................................................... A-9
A.2.3.19 Suppressing Auto-Generated Component IDs ..................................................... A-11
A.2.3.20 ADF Faces Caching Filter......................................................................................... A-11
A.2.3.21 Configuring Native Browser Context Menus for Command Links................... A-12
A.2.3.22 Session Timeout Warning ........................................................................................ A-12
A.2.3.23 JSP Tag Execution in HTTP Streaming................................................................... A-13
A.2.4 What You May Need to Know About Other Context Parameters in web.xml ....... A-13
A.3 Configuration in faces-config.xml......................................................................................... A-14
A.3.1 How to Configure for ADF Faces in faces-config.xml................................................. A-14
A.4 Configuration in adf-config.xml............................................................................................ A-15
A.4.1 How to Configure ADF Faces in adf-config.xml.......................................................... A-15
A.4.2 Defining Caching Rules for ADF Faces Caching Filter............................................... A-16
A.4.3 Configuring Flash as Component Output Format....................................................... A-17
A.5 Configuration in adf-settings.xml ......................................................................................... A-18
A.5.1 How to Configure for ADF Faces in adf-settings.xml................................................. A-18
A.5.2 What You May Need to Know About Elements in adf-settings.xml........................ A-19
A.5.2.1 Help System ............................................................................................................... A-19
A.5.2.2 Caching Rules............................................................................................................. A-19
A.6 Configuration in trinidad-config.xml ................................................................................... A-20
A.6.1 How to Configure ADF Faces Features in trinidad-config.xml................................. A-21
A.6.2 What You May Need to Know About Elements in trinidad-config.xml.................. A-22
A.6.2.1 Animation Enabled ................................................................................................... A-22
A.6.2.2 Skin Family................................................................................................................. A-22
A.6.2.3 Time Zone and Year.................................................................................................. A-23
xxv
A.6.2.4 Enhanced Debugging Output.................................................................................. A-23
A.6.2.5 Page Accessibility Level ........................................................................................... A-23
A.6.2.6 Language Reading Direction ................................................................................... A-24
A.6.2.7 Currency Code and Separators for Number Groups and Decimal Points........ A-24
A.6.2.8 Formatting Dates and Numbers Locale ................................................................. A-25
A.6.2.9 Output Mode.............................................................................................................. A-25
A.6.2.10 Number of Active PageFlowScope Instances........................................................ A-25
A.6.2.11 File Uploading............................................................................................................ A-25
A.6.2.12 Custom File Uploaded Processor............................................................................ A-26
A.6.2.13 Client-Side Validation and Conversion.................................................................. A-26
A.6.3 What You May Need to Know About Configuring a System Property................... A-26
A.7 Configuration in trinidad-skins.xml ..................................................................................... A-27
A.8 Using the RequestContext EL Implicit Object ..................................................................... A-27
A.9 Performance Tuning................................................................................................................ A-29
B Message Keys for Converter and Validator Messages
B.1 About ADF Faces Default Messages....................................................................................... B-1
B.2 Message Keys and Setter Methods.......................................................................................... B-2
B.3 Converter and Validator Message Keys and Setter Methods.............................................. B-2
B.3.1 af:convertColor.................................................................................................................... B-2
B.3.2 af:convertDateTime ............................................................................................................ B-2
B.3.3 af:convertNumber............................................................................................................... B-3
B.3.4 af:validateByteLength ........................................................................................................ B-4
B.3.5 af:validateDateRestriction ................................................................................................. B-5
B.3.6 af:validateDateTimeRange................................................................................................ B-5
B.3.7 af:validateDoubleRange..................................................................................................... B-6
B.3.8 af:validateLength ................................................................................................................ B-7
B.3.9 af:validateRegExp............................................................................................................... B-8
C Keyboard Shortcuts
C.1 About Keyboard Shortcuts....................................................................................................... C-1
C.2 Tab Traversal .............................................................................................................................. C-1
C.2.1 Tab Traversal Sequence on a Page ................................................................................... C-2
C.2.2 Tab Traversal Sequence in a Table................................................................................... C-2
C.3 Shortcut Keys.............................................................................................................................. C-4
C.3.1 Accelerator Keys ................................................................................................................. C-4
C.3.2 Access Keys.......................................................................................................................... C-5
C.3.3 Shortcut Keys for Common Components ....................................................................... C-8
C.3.4 Shortcut Keys for Screen Reader Mode........................................................................... C-9
C.3.5 Shortcut Keys for Rich Text Editor Component............................................................. C-9
C.3.6 Shortcut Keys for Table, Tree, and Tree Table Components...................................... C-10
C.3.7 Shortcut Keys for Table, Tree, and Tree Table Components in Screen Reader Mode.......
C-12
C.3.8 Shortcut Keys for Data Visualization Components..................................................... C-13
C.3.9 Shortcut Keys for Calendar Component ....................................................................... C-18
C.3.10 Shortcut Keys for Calendar Component in Screen Reader Mode ............................. C-20
xxvi
C.4 Default Cursor or Focus Placement....................................................................................... C-21
C.5 The Enter Key ........................................................................................................................... C-21
D Quick Start Layout Themes
E Code Samples
E.1 Samples for Chapter 4, "Using ADF Faces Client-Side Architecture"................................ E-1
E.1.1 The adf-js-partitions.xml File............................................................................................ E-1
E.2 Samples for Chapter 31, "Creating Custom ADF Faces Components" .............................. E-8
E.2.1 Event Code for JavaScript.................................................................................................. E-8
E.2.2 Example Tag Library Descriptor File Code .................................................................... E-9
xxvii
Preface
Welcome to Web User Interface Developer's Guide for Oracle Application Development
Framework!
Audience
This document is intended for developers who need to create the view layer of a web
application using the rich functionality of ADF Faces components.
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle
Accessibility Program website at
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
Access to Oracle Support
Oracle customers have access to electronic support through My Oracle Support. For
information, visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are
hearing impaired.
Related Documents
For more information, see the following related documents:
Oracle Fusion Middleware Skin Editor User's Guide for Oracle Application Development
Framework
Oracle Fusion Middleware User Guide for Oracle JDeveloper
Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework
Oracle Fusion Middleware Java EE Developer's Guide for Oracle Application
Development Framework
Oracle Fusion Middleware Administrators Guide for Oracle Application Development
Framework
Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application
Development Framework
xxviii
Oracle Fusion Middleware Mobile Browser Client Developer's Guide for Oracle
Application Development Framework
Oracle Fusion Middleware Java API Reference for Oracle ADF Faces
Oracle Fusion Middleware Java API Reference for Oracle ADF Faces Client JavaScript
Oracle Fusion Middleware Java API Reference for Oracle ADF Data Visualization
Components
Oracle Fusion Middleware Tag Reference for Oracle ADF Faces
Oracle Fusion Middleware Data Visualization Tools Tag Reference for Oracle ADF Faces
Oracle Fusion Middleware Tag Reference for Oracle ADF Faces Skin Selectors
Oracle Fusion Middleware Data Visualization Tools Tag Reference for Oracle ADF Skin
Selectors
Oracle JDeveloper 11g Release Notes, included with your JDeveloper 11g installation,
and on Oracle Technology Network
Conventions
The following text conventions are used in this document:
Convention Meaning
boldface Boldface type indicates graphical user interface elements associated
with an action, or terms defined in text or the glossary.
italic Italic type indicates book titles, emphasis, or placeholder variables for
which you supply particular values.
monospace Monospace type indicates commands within a paragraph, URLs, code
in examples, text that appears on the screen, or text that you enter.
xxix
What's New in This Guide for Release
11.1.2.1.0
For Release 11.1.2.1.0, this guide has been updated in several ways. The following table
lists the sections that have been added or changed.
For changes made to Oracle JDeveloper and Oracle Application Development
Framework (Oracle ADF) for this release, see the What’s New page on the Oracle
Technology Network at
http://www.oracle.com/technetwork/developer-tools/jdev/documenta
tion/index.html.
Sections Changes Made
Chapter 10 Creating and Reusing Fragments,
Page Templates, and Components
Section 10.4, "Using Page Templates" Section revised to describe ability to nest
templates.
Chapter 23 Using Gauge Components
Section 23.3.3, "How to Customize Gauge
Indicators and Tick Marks" Section revised to add a missing link to
content for formatting numerical values.
Chapter 29 Internationalizing and Localizing
Pages
Section 29.3.6, "What You May Need to Know
About Overriding a Resource Bundle in a
Customizable Application"
Section added to describe how you can
configure your resource bundles to be
customizable.
Chapter 20 Developing Accessible ADF Faces
Pages
Section 30.2, "Configuring Accessibility Support In
ADF Faces" Section revised to correct content.
xxx
Part I
Part I Getting Started with ADF Faces
Part I contains the following chapters:
Chapter 1, "Introduction to ADF Faces"
Chapter 2, "ADF Faces Demo Application"
Chapter 3, "Getting Started with ADF Faces and JDeveloper"
1
Introduction to ADF Faces 1-1
1 Introduction to ADF Faces
This chapter introduces ADF Faces, providing an overview of the framework
functionality and each of the different component types found in the library.
This chapter includes the following sections:
Section 1.1, "About Oracle ADF Faces"
Section 1.2, "ADF Faces Framework"
Section 1.3, "ADF Faces Components"
1.1 About Oracle ADF Faces
Oracle ADF Faces is a set of over 150 Ajax-enabled JavaServer Faces (JSF) components
as well as a complete framework, all built on top of the JSF 2.0 standard. In its
beginnings, ADF Faces was a first-generation set of JSF components, and has since
been donated to the Apache Software Foundation. That set is now known as Apache
MyFaces Trinidad (currently available through the Apache Software Foundation), and
remains as the foundation of today’s ADF Faces.
With ADF Faces and JSF 2.0, you can implement Ajax-based applications relatively
easily with a minimal amount of hand-coded JavaScript. For example, you can easily
build a stock trader's dashboard application that allows a stock analyst to use drag and
drop to add new stock symbols to a table view, which then gets updated by the server
model using an advanced push technology. To close new deals, the stock trader could
navigate through the process of purchasing new stocks for a client, without having to
leave the actual page. Much of this functionality can be implemented declaratively
using Oracle JDeveloper, a full-featured development environment with built-in
support for ADF Faces components, allowing you to quickly and easily build the view
layer of your web application.
1.2 ADF Faces Framework
ADF Faces framework offers complete rich functionality, including the following;
Note: Because ADF Faces adheres to the standards of the JSF
technology, this guide is mostly concerned with content that is in
addition to, or different from, JSF standards. Therefore, it is
recommended that you have a basic understanding of how JSF works
before beginning to develop with ADF Faces. To learn more about JSF,
see
http://www.oracle.com/technetwork/java/javaee/javase
rverfaces-139869.html.
ADF Faces Framework
1-2 Web User Interface Developer's Guide for Oracle Application Development Framework
Built to the JSF 2.0 specification
ADF Faces supports JSF 2.0, including Facelets. Several of the new JavaServer
Faces 2.0 features have parallel functionality in ADF Faces. To understand the new
functionality introduced in JSF 2.0 and the functional overlap that exists between
ADF Faces and JSF 2.0, see the JavaServer Faces 2.0 Overview and Adoption Roadmap
in Oracle ADF Faces and Oracle JDeveloper 11g whitepaper on OTN.
Large set of fully featured rich components
The library provides over 150 Rich Internet Application (RIA) components,
including geometry-managed layout components, text and selection components,
sortable and hierarchical data tables and trees, menus, in-page dialogs, and
general controls. For more information, see Section 1.3, "ADF Faces Components."
Widespread Ajax support
Many ADF Faces components have ajax-style functionality implemented natively.
For example, the ADF Faces table component lets you scroll through the table, sort
the table by clicking a column header, mark a row or several rows for selection,
and even expand specific rows in the table, all without requiring the page to be
submitted to the server, and with no coding needed. In ADF Faces, this
functionality is implemented as partial page rendering (PPR). For more information,
see Chapter 8, "Rerendering Partial Page Content."
Limited need for developers to write JavaScript
ADF Faces hides much of the complex JavaScript from you. Instead, you
declaratively control how components function. You can implement a rich,
functional, attractive Web UI using ADF Faces in a declarative way that does not
require the use of any JavaScript at all.
That said, there may be cases when you do want to add your own functionality to
ADF Faces, and you can easily do that using the client-side component and event
framework. For more information, see Chapter 4, "Using ADF Faces Client-Side
Architecture."
Enhanced lifecycle on both server and client
ADF Faces extends the standard JSF 2.0 page request lifecycle. Examples include a
client-side value lifecycle, a subform component that allows you to create
independent submittable regions on a page without needing multiple forms, and
an optimized lifecycle that can limit the parts of the page submitted for processing.
For more information, see Chapter 5, "Using the JSF Lifecycle with ADF Faces."
Event handling
ADF Faces adheres to standard JSF event handling techniques, as well as offering
complete a client-side event model. For more information about events, see
Chapter 6, "Handling Events."
Partial page navigation
ADF Faces applications can use PPR for navigation, which eliminates the need to
repeatedly load JavaScript libraries and stylesheets when navigating between
pages. For more information, see Section 8.4, "Using Partial Page Navigation."
Client-side validation, conversion, and messaging
ADF Faces validators can operate on both the client and server side. Client-side
validators are in written JavaScript and validation errors caught on the client-side
can be processed without a round-trip to the server. For more information, see
Chapter 7, "Validating and Converting Input."
ADF Faces Framework
Introduction to ADF Faces 1-3
Server-side push and streaming
The ADF Faces framework includes server-side push that allows you to provide
real-time data updates for ADF Faces components. For more information, see
Chapter 35, "Using the Active Data Service with an Asynchronous Backend."
Active geometry management
ADF Faces provides a client-side geometry management facility that allows
components to determine how best to make use of available screen real-estate. The
framework notifies layout components of browser resize activity, and they in turn
are able to resize their children. This allows certain components to stretch or
shrink, filling up any available browser space. For more information, see
Section 9.2.1, "Geometry Management and Component Stretching."
Advanced templating and declarative components
You can create page templates, as well as page fragments and composite
components made up of multiple components, which can be used throughout
your application. For more information, see Chapter 10, "Creating and Reusing
Fragments, Page Templates, and Components."
Advanced visualization components
ADF Faces includes data visualization components, which are Flash- and
PNG-enabled components capable of rendering dynamic charts, graphs, gauges,
and other graphics that provide a real-time view of underlying data. For more
information, see Part V, "Using ADF Data Visualization Components".
Skinning
You can create your own look and feel by implementing skins for ADF Faces
components. Oracle provides a stand-alone skin editor, where you can
declaratively create and modify your skins. For more information, see Chapter 28,
"Customizing the Appearance Using Styles and Skins."
Internationalization
You can configure your JSF page or application to use different locales so that it
displays the correct language based on the language setting of a user’s browser.
For more information, see Chapter 29, "Internationalizing and Localizing Pages."
Accessibility
ADF Faces components have built-in accessibility that work with a range of
assistive technologies, including screen readers.ADF Faces accessibility audit rules
provide direction to create accessible images, tables, frames, forms, error
messages, and popup windows using accessible HTML markup. For more
information, see Chapter 30, "Developing Accessible ADF Faces Pages."
User-driven personalization
Many ADF Faces components allow users to change the display of the component
at runtime. By default, these changes live only as long as the page request.
However, you can configure your application so that the changes can be persisted
through the length of the user’s session. For more information, see Chapter 32,
"Allowing User Customization on JSF Pages."
Drag and drop
The ADF Faces framework allows the user to move data from one location to
another by dragging and dropping one component onto another. For more
information, see Chapter 33, "Adding Drag and Drop Functionality."
ADF Faces Components
1-4 Web User Interface Developer's Guide for Oracle Application Development Framework
Integration with other Oracle ADF technologies
You can use ADF Faces in conjunction with the other Oracle ADF technologies,
including ADF Business Components, ADF Controller, and ADF Databinding. For
more information about using ADF Faces with the ADF technology stack, see the
Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development
Framework
Integrated declarative development with Oracle JDeveloper
JDeveloper is a full-featured development environment with built-in declarative
support for ADF Faces components, including a visual layout editor, a Component
Palette that allows you to drag and drop an ADF Faces component onto a page,
and a Property Inspector where you declaratively configure component
functionality. For more information about using JDeveloper, see Chapter 3,
"Getting Started with ADF Faces and JDeveloper."
1.3 ADF Faces Components
ADF Faces components generally fall into the following categories:
Layout components
Layout components act as containers to determine the layout of the page, ADF
Faces layout components also include interactive container components that can
show or hide content, or that provide sections, lists, or empty spaces. JDeveloper
provides prebuilt quick-start layouts that declaratively add layout components to
your page based on how you want the page to look. For more information about
layout components and geometry management, see Chapter 9, "Organizing
Content on Web Pages."
In addition to standard layout components, ADF Faces also provides the following
specialty layout components:
Explorer-type menus and toolbar containers: Allow you to create menu bars
and toolbars. Menus and toolbars allow users to select from a specified list of
options (in the case of a menu) or buttons (in the case of a toolbar) to cause
some change to the application. For more information, see Chapter 16, "Using
Menus, Toolbars, and Toolboxes."
Secondary windows: Display data in popup windows or dialogs. The dialog
framework in ADF Faces provides an infrastructure to support building pages
for a process displayed in a new popup browser window separate from the
parent page. Multiple dialogs can have a control flow of their own. For more
information, see Chapter 15, "Using Popup Dialogs, Menus, and Windows."
Core structure components and tags: Provide the tags needed to create pages
and layouts, such as documents, forms and subforms, and resources. These
tags are discussed in various chapters.
Text and selection components
These components allow you to display text, from a simple output text component
to input components, including selection components, to a complex list of value
component.
Output components: Display text and graphics, and can also play video and
music clips. ADF Faces also includes a carousel component that can display
graphics in a revolving carousel. For more information, see Chapter 18, "Using
Output Components."
ADF Faces Components
Introduction to ADF Faces 1-5
Input components: Allow users to enter data or other types of information,
such as color selection or date selection. ADF Faces also provides simple lists
from which users can choose the data to be posted, as well as a file upload
component. For more information about input components, see Chapter 11,
"Using Input Components and Defining Forms."
List-of-Values (LOV) components: Allow users to make selections from lists
driven by a model that contains functionality like searching for a specific value
or showing values marked as favorites. These LOV components are useful
when a field used to populate an attribute for one object might actually be
contained in a list of other objects, as with a foreign key relationship in a
database. For more information, see Chapter 13, "Using List-of-Values
Components."
Data Views
ADF Faces provides a number of different ways to display complex data.
Table and tree components: Display structured data in tables or expandable
trees. ADF Faces tables provide functionality such as sorting column data,
filtering data, and showing and hiding detailed content for a row. Trees have
built-in expand/collapse behavior. Tree tables combine the functionality of
tables with the data hierarchy functionality of trees. For more information, see
Chapter 12, "Using Tables and Trees."
Data visualization components: Allow users to view and analyze complex
data in real time. ADF data visualization components include graphs, gauges,
pivot tables, geographic maps, Gantt charts, and hierarchy viewers that
display hierarchical data as a set of linked nodes, for example an organization
chart. For more information, see Chapter 21, "Introduction to ADF Data
Visualization Components."
Query components: Allow users to query data. The query component can
support multiple search criteria, dynamically adding and deleting criteria,
selectable search operators, match all/any selections, seeded or saved
searches, a basic or advanced mode, and personalization of searches. For more
information, see Chapter 14, "Using Query Components."
Specialty display components: The calendar component displays activities in
day, week, month, or list view. You can implement popup components that
allow users to create, edit, or delete activities. For more information, see
Chapter 17, "Using a Calendar Component." The carousel component allows
you to display a collection of images in a scrollable manner. For more
information, see Section 18.6, "Displaying Images in a Carousel."
Messaging and help: The framework provides the ability to display tooltips,
messages, and help for input components, as well as the ability to display global
messages for the application. The help framework allows you to create messages
that can be reused throughout the application.You create a help provider using a
Java class, a managed bean, an XLIFF file, or a standard properties file, or you can
link to an external HTML-based help system. For more information, see
Chapter 19, "Displaying Tips, Messages, and Help."
Hierarchical menu model: ADF Faces provides navigation components that render
items such as tabs and breadcrumbs for navigating hierarchical pages. The
framework provides an XML-based menu model that, in conjunction with a
metadata file, contains all the information for generating the appropriate number
of hierarchical levels on each page, and the navigation items that belong to each
level. For more information, see Chapter 20, "Working with Navigation
Components."
ADF Faces Components
1-6 Web User Interface Developer's Guide for Oracle Application Development Framework
General controls
General controls include the components used to navigate, as well as to display
images and icons,
Navigation components: Allow users to go from one page to the next. ADF
Faces navigation components include buttons and links, as well as the
capability to create more complex hierarchical page flows accessed through
different levels of menus. For more information, see Chapter 20, "Working
with Navigation Components."
Images and icon components: Allow you to display images as simple as icons,
to as complex as video. For more information, see Chapter 18, "Using Output
Components."
Operations
While not components, these tags work with components to provide additional
functionality, such as drag and drop, validation, and a variety of event listeners.
These operational tags are discussed with the components that use them.
2
ADF Faces Demo Application 2-1
2ADF Faces Demo Application
This chapter describes the ADF Faces demo application that can be used in
conjunction with this developers guide.
This chapter contains the following sections:
Section 2.1, "About the ADF Faces Demonstration Application"
Section 2.2, "Downloading and Installing the ADF Faces Demo Application"
2.1 About the ADF Faces Demonstration Application
ADF Faces includes a demonstration application that allows you both to experiment
with running samples of the components and architecture features, and view the
source code.
The demo application contains the following:
Tag guide: Demonstrations of ADF Faces components, validators, converters, and
miscellaneous tags, along with a property editor to see how changing attribute
values affects the component. Figure 2–1 shows the demonstration of the
selectManyCheckbox component. Each demo provides a link to the associated
tag documentation.
About the ADF Faces Demonstration Application
2-2 Web User Interface Developer's Guide for Oracle Application Development Framework
Figure 2–1 Tag Demonstration
Skinning: Demonstrations of skinning on the various components. You can see, for
example, how changing style selectors affects how a component is displayed.
Figure 2–2 shows how setting certain style selectors affects the
inputNumberSpinbox component.
About the ADF Faces Demonstration Application
ADF Faces Demo Application 2-3
Figure 2–2 Skinning Demonstration
Feature demos: Various pages that demonstrate different ways you can use ADF
components. For example, the File Explorer is an application with a live data
model that displays a directory structure and allows you to create, save, and move
directories and files. This application is meant to showcase the components and
features of ADF Faces in a working application, as shown in Figure 2–3.
About the ADF Faces Demonstration Application
2-4 Web User Interface Developer's Guide for Oracle Application Development Framework
Figure 2–3 File Explorer Application
Other pages demonstrate the main architectural features of ADF Faces, such as
layout components, Ajax postback functionality, and drag and drop. Figure 2–4
shows the demonstration on using the AutoSubmit attribute and partial page
rendering.
About the ADF Faces Demonstration Application
ADF Faces Demo Application 2-5
Figure 2–4 Framework Demonstration
Visual designs: Demonstrations of how you can use types of components in
different ways to achieve different UI designs. Figure 2–5 shows how you can
achieve different looks for a toolbar.
Figure 2–5 Toolbar Design Demonstration
About the ADF Faces Demonstration Application
2-6 Web User Interface Developer's Guide for Oracle Application Development Framework
Styles: Demonstration of how setting inline styles and content styles affects
components. Figure 2–6 shows different styles applied to the panelBox
component.
Figure 2–6 Styles Demonstration
Commonly confused components: A comparison of components that provide
similar functionality. Figure 2–7 shows the differences between the various
components that display selection lists.
About the ADF Faces Demonstration Application
ADF Faces Demo Application 2-7
Figure 2–7 Commonly Confused Components
Because the File Explorer is a complete working application, many sections in this
guide use that application to illustrate key points, or to provide code samples. The
source for the File Explorer application can be found in the fileExplorer directory.
The File Explorer application uses the fileExplorerTemplate page template. This
template contains a number of layout components that provide the basic look and feel
for the application. For more information about layout components, see Chapter 9,
"Organizing Content on Web Pages." For more information about using templates, see
Chapter 10, "Creating and Reusing Fragments, Page Templates, and Components."
The left-hand side of the application contains a panelAccordion component that
holds two areas: the directory structure and a search field with a results table, as
shown in Figure 2–8.
Figure 2–8 Directory Structure Panel and Search Panel
You can expand and collapse both these areas. The directory structure is created using
a tree component. The search area is created using input components, a command
About the ADF Faces Demonstration Application
2-8 Web User Interface Developer's Guide for Oracle Application Development Framework
button, and a table component. For more information about using
panelAccordion components, see Section 9.9, "Displaying or Hiding Contents in
Accordion Panels and Tabbed Panels." For more information about using input
components, see Chapter 11, "Using Input Components and Defining Forms." For
more information about using command buttons, see Chapter 20, "Working with
Navigation Components." For more information about using tables and trees, see
Chapter 12, "Using Tables and Trees."
The right-hand side of the File Explorer application uses tabbed panes to display the
contents of a directory in either a table, a tree table or a list, as shown in Figure 2–9.
Figure 2–9 Directory Contents in Tabbed Panels
The table and tree table have built-in toolbars that allow you to manipulate how the
contents are displayed. In the table an list, you can drag a file or subdirectory from one
directory and drop it into another. In all tabs, you can right-click a file, and from the
context menu, you can view the properties of the file in a popup window. For more
information about using tabbed panes, see Section 9.9, "Displaying or Hiding Contents
in Accordion Panels and Tabbed Panels." For more information about table and tree
table toolbars, see Section 12.9, "Displaying Table Menus, Toolbars, and Status Bars."
For more information about enabling drag and drop, see Chapter 33, "Adding Drag
and Drop Functionality." For more information about using context menus and popup
windows, see Chapter 15, "Using Popup Dialogs, Menus, and Windows."
The top of the File Explorer application contains a menu and a toolbar, as shown in
Figure 2–10.
Figure 2–10 Menu and Toolbar
The menu options allow you to create and delete files and directories and change how
the contents are displayed. The Help menu opens a help system that allows users to
provide feedback in dialogs, as shown in Figure 2–11.
About the ADF Faces Demonstration Application
ADF Faces Demo Application 2-9
Figure 2–11 Help System
The help system consists of a number of forms created with various input components,
including a rich text editor. For more information about menus, see Section 16.2,
"Using Menus in a Menu Bar." For more information about creating help systems, see
Section 19.5, "Displaying Help for Components." For more information about input
components, see Chapter 11, "Using Input Components and Defining Forms."
Within the toolbar of the File Explorer are controls that allow you navigate within the
directory structure, as well as controls that allow you to change the look and feel of the
application by changing its skin. Figure 2–12 shows the File Explorer application using
the simple skin.
Downloading and Installing the ADF Faces Demo Application
2-10 Web User Interface Developer's Guide for Oracle Application Development Framework
Figure 2–12 File Explorer Application with the Simple Skin
For more information about toolbars, see Section 16.3, "Using Toolbars." For more
information about using skins, see Chapter 28, "Customizing the Appearance Using
Styles and Skins."
2.2 Downloading and Installing the ADF Faces Demo Application
In order to view the demo application (both the code and at runtime), install
JDeveloper, and then download and open the application within JDeveloper.
You can download the ADF Faces demo application from the Oracle Technology
Network (OTN) web site. Navigate to
http://www.oracle.com/technetwork/developer-tools/adf/overview/
index-092391.html and click the ADF Faces Rich Client Components Demo link
in the Download section of the page. The resulting page provides detailed instructions
for downloading the WAR file that contains the application, along with instructions for
deploying the application to a standalone server, or for running the application using
the Integrated WebLogic Server included with JDeveloper.
If you do not want to install the application, you can run the application directly from
OTN by clicking the ADF Faces Rich Client Components Hosted Demo link.
3
Getting Started with ADF Faces and JDeveloper 3-1
3 Getting Started with ADF Faces and
JDeveloper
This chapter describes how to use JDeveloper to declaratively create ADF Faces
applications.
This chapter includes the following sections:
Section 3.1, "About Developing Declaratively in JDeveloper"
Section 3.2, "Creating an Application Workspace"
Section 3.3, "Defining Page Flows"
Section 3.4, "Creating a View Page"
Section 3.5, "Creating EL Expressions"
Section 3.6, "Creating and Using Managed Beans"
Section 3.7, "Viewing ADF Faces Javadoc"
3.1 About Developing Declaratively in JDeveloper
Using JDeveloper 11g with ADF Faces and JSF provides a number of areas where page
and managed bean code is generated for you declaratively, including creating EL
expressions and automatic component binding. Additionally, there are a number of
areas where XML metadata is generated for you declaratively, including metadata that
controls navigation and configuration.
At a high level, the development process for an ADF Faces view project usually
involves the following:
Creating an application workspace
Designing page flows
Designing and creating the pages using either JavaServer Pages (JSPs) or Facelet
pages
Deploying the application. For more information about deployment, see the Oracle
Fusion Middleware Administrator's Guide for Oracle Application Development
Framework. If your application uses ADF Faces with the ADF Model layer, the ADF
Controller, and ADF Business Components, see the "Deploying Fusion Web
Applications" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for
Oracle Application Development Framework.
Ongoing tasks throughout the development cycle will likely include the following:
Creating managed beans
Creating an Application Workspace
3-2 Web User Interface Developer's Guide for Oracle Application Development Framework
Creating and using EL expressions
Viewing ADF Faces source code and Javadoc
JDeveloper also includes debugging and testing capabilities. For more information, see
the "Testing and Debugging ADF Components" chapter of the Oracle Fusion Middleware
Fusion Developer's Guide for Oracle Application Development Framework.
3.2 Creating an Application Workspace
The first steps in building a new application are to assign it a name and to specify the
directory where its source files will be saved. You can either create an application that
just contains the view layer, or you can add an ADF Faces project to an existing
application.
3.2.1 How to Create an ADF Faces Application Workspace
You create an application workspace using the Create Application wizard.
To create an application:
1. In the JDeveloper main menu, choose File > New.
The New Gallery opens, where you can select different application components to
create.
2. Select Applications > Custom Application.
3. In the Create Custom Application dialog, set a name, directory location, and
package prefix of your choice and click Next.
4. In the Name Your Project page, you can optionally change the name and location
for your view project. On the Project Features tab, shuttle ADF Faces Components
to Selected. The necessary libraries and metadata files for ADF Faces will be
added to your project. Click Next.
5. In the Configure Java Settings page, optionally change the package name, Java
source path, and output directory for any Java classes you might create. Click
Finish.
Note: This document covers only how to create the ADF Faces
project in an application, without regard to the business services used
or the binding to those services. For information about how to use
ADF Faces with the ADF Model layer, the ADF Controller, and ADF
Business Components, see the Oracle Fusion Middleware Fusion
Developer's Guide for Oracle Application Development Framework. For
more information about using ADF Faces with the ADF Model layer
and EJBs and JPA, see Oracle Fusion Middleware Java EE Developer's
Guide for Oracle Application Development Framework.
Tip: You can also add ADF Faces to an existing project (for example,
a view project in a JEE Web Application). To do so:
1. Right-click the project and choose Project Properties.
2. In the Project Properties dialog, select Features, then click the Add (green
plus) icon, and shuttle ADF Faces to the Selected pane.
Creating an Application Workspace
Getting Started with ADF Faces and JDeveloper 3-3
3.2.2 What Happens When You Create an Application Workspace
When you create an application workspace using the Custom template, and the select
ADF Faces for your project, JDeveloper creates a project that contains all the source
and configuration files needed for an ADF Faces application. Additionally, JDeveloper
adds the following libraries to your project:
JSF 2.0
JSTL 1.2
JSP Runtime
Once the projects are created for you, you can rename them. Figure 3–1 shows the
workspace for a new ADF Faces application.
Figure 3–1 New Workspace for an ADF Faces Application
JDeveloper also sets configuration parameters in the configuration files based on the
options chosen when you created the application. In the web.xml file, these are
configurations needed to run a JSF application (settings specific to ADF Faces are
added when you create a JSF page with ADF Faces components). Example 3–1 shows
the web.xml file generated by JDeveloper when you create a new Java EE application.
Example 3–1 Generated web.xml File
<?xml version = '1.0' encoding = 'windows-1252'?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
Defining Page Flows
3-4 Web User Interface Developer's Guide for Oracle Application Development Framework
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
version="2.5" xmlns="http://java.sun.com/xml/ns/javaee">
<servlet>
<servlet-name>Faces Servlet</servlet-name>
<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>Faces Servlet</servlet-name>
<url-pattern>/faces/*</url-pattern>
</servlet-mapping>
</web-app>
Configurations required for specific ADF Faces features are covered in the respective
chapters of this guide. For example, any configuration needed in order to use the
Change Persistence framework is covered in Chapter 32, "Allowing User
Customization on JSF Pages." For comprehensive information about configuring an
ADF Faces application, see Appendix A, " ADF Faces Configuration."
3.3 Defining Page Flows
Once you create your application workspace, often the next step is to design the flow
of your UI. As with standard JSF applications, ADF Faces applications use navigation
cases and rules to define the page flow. These definitions are stored in the
faces-config.xml file. JDeveloper provides a diagrammer through which you can
declaratively define your page flow using icons.
Figure 3–2 shows the navigation diagram created for a simple page flow that contains
two pages: a DisplayCustomer page that shows data for a specific customer, and an
EditCustomer page that allows a user to edit the customer information. There is one
navigation rule that goes from the display page to the edit page and one navigation
rule that returns to the display page from the edit page.
Figure 3–2 Navigation Diagram in JDeveloper
Note: If you plan on using Oracle ADF Model data binding and the
ADF Controller, then you use ADF task flows to define your
navigation rules. For more information, see the "Getting Started With
ADF Task Flows" chapter of the Oracle Fusion Middleware Fusion
Developer's Guide for Oracle Application Development Framework.
Best Practice: The ADF Controller extends the JSF default controller.
While you can technically use the JSF controller and ADF Controller in
your application, you should use only one or the other.
Defining Page Flows
Getting Started with ADF Faces and JDeveloper 3-5
With the advent of JSF 2.0, you no longer need to create a navigation case for simple
navigation between two pages. If no matching navigation case is found after checking
all available rules, the navigation handler checks to see whether the action outcome
corresponds to a view ID. If a view matching the action outcome is found, an implicit
navigation to the matching view occurs. For more information on how navigation
works in a JSF application, see the Java EE 6 tutorial
(http://download.oracle.com/javaee/index.html).
3.3.1 How to Define a Page Flow
You use the navigation diagrammer to declaratively create a page flow using Facelets
or JSPX pages. When you use the diagrammer, JDeveloper creates the XML metadata
needed for navigation to work in your application in the faces-config.xml file.
Before you begin:
It may be helpful to have an understanding of page flows. For more information, see
Section 3.3, "Defining Page Flows."
To create a page flow:
1. In the Application Navigator, double-click the faces-config.xml file for your
application. By default, this is in the Web Content/WEB-INF node of your project.
2. In the editor window, click the Diagram tab to open the navigation diagrammer.
3. If the Component Palette is not displayed, from the main menu choose View >
Component Palette. By default, the Component Palette is displayed in the upper
right-hand corner of JDeveloper.
4. In the Component Palette, use the dropdown menu to choose JSF Diagram
Objects.
The components are contained in two accordion panels: Components and
Diagram Annotations. Figure 3–3 shows the Component Palette displaying JSF
navigation components.
Figure 3–3 Component Palette in JDeveloper
5. Select the component you wish to use and drag it onto the diagram.
JDeveloper redraws the diagram with the newly added component.
Creating a View Page
3-6 Web User Interface Developer's Guide for Oracle Application Development Framework
Once the navigation for your application is defined, you can create the pages and add
the components that will execute the navigation. For more information about using
navigation components on a page, see Chapter 20, "Working with Navigation
Components."
3.3.2 What Happens When You Use the Diagrammer to Create a Page Flow
When you use the diagrammer to create a page flow, JDeveloper creates the associated
XML entries in the faces-config.xml file. Example 3–2 shows the XML generated
for the navigation rules displayed in Figure 3–2.
Example 3–2 Navigation Rules in faces-config.xml
<navigation-rule>
<from-view-id>/DisplayCustomer</from-view-id>
<navigation-case>
<from-outcome>edit</from-outcome>
<to-view-id>/EditCustomer</to-view-id>
</navigation-case>
</navigation-rule>
<navigation-rule>
<from-view-id>/EditCustomer</from-view-id>
<navigation-case>
<from-outcome>back</from-outcome>
<to-view-id>/DisplayCustomer</to-view-id>
</navigation-case>
</navigation-rule>
3.4 Creating a View Page
From the page flows you created during the planning stages, you can double-click the
page icons to create the actual JSF page files. You can choose to create either a Facelets
page or a JSP page. Facelet pages use the extension *.jsf. Facelets is a JSF-centric
declarative XML view definition technology that provides an alternative to using the
JSP engine.
If instead you create a JSP page for an ADF Faces application, you create an
XML-based JSP document, which uses the extension *.jspx. Using an XML-based
document has the following advantages:
It simplifies treating your page as a well-formed tree of UI component tags.
It discourages you from mixing Java code and component tags.
It allows you to easily parse the page to create documentation or audit reports.
Tip: You can also use the overview editor to create navigation rules
and navigation cases by clicking the Overview tab. Press F1 for details
on using the overview editor to create navigation.
Additionally, you can manually add elements to the
faces-config.xml file by directly editing the page in the source
editor. To view the file in the source editor, click the Source tab.
Creating a View Page
Getting Started with ADF Faces and JDeveloper 3-7
ADF Faces provides a number of components that you can use to define the overall
layout of a page. JDeveloper contains predefined quick start layouts that use these
components to provide you with a quick and easy way to correctly build the layout.
You can choose from one, two, or three column layouts, and then determine how you
want the columns to behave. For example, you may want one column’s width to be
locked, while another column stretches to fill available browser space. Figure 3–4
shows the quick start layouts available for a two-column layout with the second
column split between two panes. For more information about the layout components,
see Chapter 9, "Organizing Content on Web Pages."
Figure 3–4 Quick Layouts
Along with adding layout components, you can also choose to apply a theme to the
chosen quick layout. These themes add color styling to some of the components used
in the quick start layout. To see the color and where it is added, see Appendix D,
Best Practice: Use Facelets to take advantage of the following:
The Facelets layer was created specifically for JSF, which results in
reduced overhead and improved performance during tag
compilation and execution.
Facelets is considered the primary view definition technology in
JSF 2.0.
Some future performance enhancements to the JSF standard will
only be available with Facelets.
Best Practice: Creating a layout that works correctly in all browsers
can be time consuming. Use a predefined quick layout to avoid any
potential issues.
Creating a View Page
3-8 Web User Interface Developer's Guide for Oracle Application Development Framework
"Quick Start Layout Themes." For more information about themes, see Chapter 28,
"Customizing the Appearance Using Styles and Skins"
When you know you want to use the same layout on many pages in your application,
ADF Faces allows you to create and use predefined page templates. When creating
templates, the template developer can not only determine the layout of any page that
will use the template, but can also provide static content that must appear on all pages,
as well as create placeholder attributes that can be replaced with valid values for each
individual page.
For example, ADF Faces ships with the Oracle Three-Column-Layout template. This
template provides areas for specific content, such as branding, a header, and copyright
information, and also displays a static logo and busy icon, as shown in Figure 3–5.
Figure 3–5 Oracle Three Column Layout Template
Whenever a template is changed, for example if the layout changes, any page that uses
the template will also be automatically updated. For more information about creating
and using templates, see Section 10.4, "Using Page Templates."
At the time you create a JSF page, you can also choose to create an associated backing
bean for the page. Backing beans allow you to access the components on the page
programmatically. For more information about using backing beans with JSF pages,
see Section 3.4.4, "What You May Need to Know About Automatic Component
Binding."
Best Practice: Use templates to ensure consistency and so that in the
future, you can easily update multiple pages in an application.
Best Practice: Create backing beans only for pages that contain
components that must be accessed and manipulated
programmatically. Use managed beans instead if you need only to
provide additional functionality accessed through EL expressions on
component attributes (such as listeners).
Creating a View Page
Getting Started with ADF Faces and JDeveloper 3-9
You can also choose to have your page available for display in mobile devices. Once
your page files are created, you can add UI components and work with the page
source.
3.4.1 How to Create JSF Pages
You create JSF pages (either JSP or Facelets) using the Create JSF Page dialog.
Before you begin:
It may be helpful to have an understanding of the different options when creating a
page. For more information, see Section 3.4, "Creating a View Page."
To create a JSF page:
1. In the Application Navigator, right-click the directory where you would like the
page to be saved, and choose New. In the New Gallery, expand the Web Tier
node, select JSF/Facelets and then Page, and click OK.
OR
From a navigation diagram, double-click a page icon for a page that has not yet
been created.
2. Complete the Create JSF Page dialog. For help, click Help in the dialog. For more
information about the Managed Bean tab, which can be used to automatically
create a backing bean and associated bindings, see Section 3.4.4, "What You May
Need to Know About Automatic Component Binding."
3.4.2 What Happens When You Create a JSF Page
When you use the Create JSF Page dialog to create a JSF page, JDeveloper creates the
physical file and adds the code necessary to import the component libraries and
display a page. The code created depends on whether or not you chose to create a
JSPX or Facelets page.
Example 3–3 shows a Facelets page when it is first created by JDeveloper.
Example 3–3 Declarative Facelets Page Source Created by JDeveloper
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<f:view xmlns:f="http://java.sun.com/jsf/core"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
<af:document title="untitled1.jsf" id="d1">
<af:form id="f1"></af:form>
</af:document>
</f:view>
Example 3–4 shows a .jspx page when it is first created by JDeveloper.
Note: While a Facelets page can use any extension you’d like, a
Facelets page must use the .jsf extension to be customizable. For
more information, see Chapter 32, "Allowing User Customization on
JSF Pages."
Creating a View Page
3-10 Web User Interface Developer's Guide for Oracle Application Development Framework
Example 3–4 Declarative JSPX Page Source Created by JDeveloper
<?xml version='1.0' encoding='UTF-8'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
xmlns:f="http://java.sun.com/jsf/core"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
<jsp:directive.page contentType="text/html;charset=UTF-8"/>
<f:view>
<af:document title="untitled1" id="d1">
<af:form id="f1"></af:form>
</af:document>
</f:view>
</jsp:root>
If you chose to use one of the quick layouts, then JDeveloper also adds the components
necessary to display the layout. Example 3–5 shows the generated code when you
choose a two-column layout, where the first column is locked and the second column
stretches to fill up available browser space, and you also choose to apply themes.
Example 3–5 Two-Column Layout
<?xml version='1.0' encoding='UTF-8'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
xmlns:f="http://java.sun.com/jsf/core"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
<jsp:directive.page contentType="text/html;charset=UTF-8"/>
<f:view>
<af:document title="untitled2" id="d1">
<af:form id="f1">
<af:panelStretchLayout startWidth="100px" id="psl1">
<f:facet name="start"/>
<f:facet name="center">
<!-- id="af_twocol_left_sidebar_stretched" -->
<af:decorativeBox theme="dark" id="db1">
<f:facet name="center">
<af:decorativeBox theme="medium" id="db2">
<f:facet name="center"/>
</af:decorativeBox>
</f:facet>
</af:decorativeBox>
</f:facet>
</af:panelStretchLayout>
</af:form>
</af:document>
</f:view>
</jsp:root>
If you chose to automatically create a backing bean using the Managed Bean tab of the
dialog, JDeveloper also creates and registers a backing bean for the page, and binds
any existing components to the bean. Example 3–6 shows the code created for a
backing bean for a page.
Example 3–6 Declarative Backing Bean Source Created by JDeveloper
package view.backing;
import oracle.adf.view.rich.component.rich.RichDocument;
import oracle.adf.view.rich.component.rich.RichForm;
Creating a View Page
Getting Started with ADF Faces and JDeveloper 3-11
public class MyFile {
private RichForm f1;
private RichDocument d1;
public void setF1(RichForm f1) {
this.f1 = f1;
}
public RichForm getF1() {
return f1;
}
public void setD1(RichDocument d1) {
this.document1 = d1;
}
public RichDocument getD1() {
return d1;
}
}
Additionally, JDeveloper adds the following libraries to the view project:
ADF Faces Runtime 11
ADF Common Runtime
ADF DVT Faces Runtime
ADF DVT Faces Databinding Runtime
ADF DVT Faces Databinding MDS Runtime
Oracle JEWT
JDeveloper also adds entries to the web.xml file. Example 3–7 shows the web.xml file
created once you create a JSPX page.
Example 3–7 Code in the web.xml File After a JSF Page is Created
<?xml version = '1.0' encoding = 'windows-1252'?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
version="2.5" xmlns="http://java.sun.com/xml/ns/javaee">
<context-param>
<param-name>javax.faces.STATE_SAVING_METHOD</param-name>
<param-value>client</param-value>
</context-param>
<context-param>
<param-name>javax.faces.PARTIAL_STATE_SAVING</param-name>
<param-value>false</param-value>
</context-param>
<context-param>
<description>If this parameter is true, there will be an automatic check of
the modification date of your JSPs, and saved state will be discarded when JSP's
Tip: You can access the backing bean source from the JSF page by
right-clicking the page in the editor, and choosing Go to and then
selecting the bean from the list.
Creating a View Page
3-12 Web User Interface Developer's Guide for Oracle Application Development Framework
change. It will also automatically check if your skinning css files have changed
without you having to restart the server. This makes development easier, but adds
overhead. For this reason this parameter should be set to false when your
application is deployed.</description>
<param-name>org.apache.myfaces.trinidad.CHECK_FILE_MODIFICATION</param-name>
<param-value>false</param-value>
</context-param>
<context-param>
<description>Whether the 'Generated by...' comment at the bottom of ADF Faces
HTML pages should contain version number information.</description>
<param-name>oracle.adf.view.rich.versionString.HIDDEN</param-name>
<param-value>false</param-value>
</context-param>
<context-param>
<param-name>javax.faces.FACELETS_SKIP_XML_INSTRUCTIONS</param-name>
<param-value>true</param-value>
</context-param>
<context-param>
<param-name>javax.faces.FACELETS_SKIP_COMMENTS</param-name>
<param-value>true</param-value>
</context-param>
<context-param>
<param-name>javax.faces.FACELETS_DECORATORS</param-name>
<param-value>
oracle.adfinternal.view.faces.facelets.rich.AdfTagDecorator
</param-value>
</context-param>
<context-param>
<param-name>
javax.faces.FACELETS_RESOURCE_RESOLVER
</param-name>
<param-value>
oracle.adfinternal.view.faces.facelets.rich.AdfFaceletsResourceResolver
</param-value>
</context-param>
<filter>
<filter-name>trinidad</filter-name>
<filter-class>org.apache.myfaces.trinidad.webapp.TrinidadFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>trinidad</filter-name>
<servlet-name>Faces Servlet</servlet-name>
<dispatcher>FORWARD</dispatcher>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>
<servlet>
<servlet-name>Faces Servlet</servlet-name>
<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet>
<servlet-name>resources</servlet-name>
<servlet-class>org.apache.myfaces.trinidad.webapp.ResourceServlet</servlet-class>
</servlet>
<servlet>
<servlet-name>BIGRAPHSERVLET</servlet-name>
<servlet-class>oracle.adf.view.faces.bi.webapp.Grap